p2r playlister

File Release Notes and Changelog

Release Name: 0.7

Notes:
Added option to write playlists in other directory than the root, 
and for preventing output files to be overwritten with identical content.

The API is slightly modified to support relative paths to output directory,
and to present existing plugins (see change log for details).

Increased the default memory allocation to handle my ever-growing music collection. 
The new setting should handle 35-40,000 files.

Modified a name of property 'filename', new name is 'playlist.name' (existing 
property files muset be updated).

A few more minor fixes - see the change log for details.

Changes:
 p2r playlister
 (c) Peer Törngren 2008

 Project Homepage :
   http://sourceforge.net/projects/p2rplaylister 

------------------------------------------------
p2rplaylister.core version 0.7 alpha (2008-08-17 00:05)

2008-08-17: p2rplaylister 0.7
=============================
- Added option to write playlists in other folder than the root folder.
  *	Set property 'filepath=path/to/playlists' or 'filepath=/path/to/playlists/'
  * path can be absolute or relative to root directory.
  * playlist entries will have relative paths if possible 
    (unless two disjunct absolute paths are specified).
- Increased default memory allocation to handle my growing collection (now +40k files).
- Optionally avoid rewriting playlists with same content (do hash-based analysis of content)
  * define any standard hash.algorithm like SHA or MD5 (MD5 default)
  * use companion files carrying hash in name, or dynamic (inline) hash calculation
  * by default, hash calculation is turned off (behaves like before)
- Fix ISO date/time strings, now uses 24h clock
- changed property names filename + filepath => playlist.name + playlist.path
- log brief description of active plug-ins when job starts
 
API version 0.3
---------------
- Added interface PlugIn, which all plug-in interface now extend
	getNiceName() presents a human readable name of the plugin
	getBriefDescription() presents a one-line description of the plugin.
- ProcessMonitor.onWrittenItem(...)
	Added parameter 'songPathPrefix'. New signature is:
	void onWrittenItem(MP3ItemCollection collection, File playlist, MP3Item item, String songPathPrefix);
- ListSetup.getOutputPathPattern()
	Added. Reads property file to get path to playlist output directory 
	(can hold variables for formatting text, as described in sample property file).	

internal changes
----------------
- PluginManager offers two new methods for direct access to internal plug-ins
- Added OutputFileManager to track and delete files.
- Added ConservativePrintFileWriter to do hash-based analysis of content 
- Added Helper.timestampISO()
- Added tiny utility for working with paths (se.p2r.PathUtil)
- Added generic exception ExtendedIOException to provide more info.
- Using LinkedList instead of ArrayList in many places (marginal performance improvement)  

2007-09-18: p2rplaylister 0.6
=============================

New features and options
------------------------
- Most Recently Added (MRA)
  * "mra" limits list size to specified number of most recently added items 
    (get max nn of Most Recently Added) by adding a ~ qualifier to list directive. 
  * Optional mra "unit" can be (a)rtists, al(b)ums, (d)ays or (m)onths. 
    Default unit (if unspecified) is files (i.e. "tracks").  
  * New list syntax is:
	  list=name[%format][?sorting][:minSize][~mraLimit[a|b|d|m]]
    Example: 
  	  list%mra?mra:10~5b
- Sorting
  * Default list sorting is Artist - Year - Album - Position - Track - Title - Filename
  * Add option to define default and specific sort order. Set property "sort.default" 
    or "sort.someOtherName" and specify list of tags (separated by semi-colon) to sort 
    on (see default settings for example). By default, all lists sort according to 
    sort.default. Define specific sort order by referring to named sorting using syntax 
    described above (see default settings for example). 
  * Option to sort in reversed order by prefixing tag(s) with -
  * Option to specify grouping by one tag in sort order. List will be ordered
    in groups, each group sorted on tags before the "grouping" tag, and each group 
    internally sorted on all tags after "grouping" tag. "Grouping tag" is identified 
    by prefix "^". Note that "grouping" large collections may render really long 
    processing time. Honestly. In practice, "GroupBy" is only usable in limited size 
    lists, and was invented to sort MRA lists on album or artist.
  * New sort syntax is:
  	  [[^][-]tag;] ... 
  	Example: 
  	  sort.mra=-modified; ^album; position; track;
  * Add option to include sort order in playlist header (used in default list header)
- Add "age" filter (collect files modified within period relative to current date)
- Add list setup option 'stripLeadingZeroes' to sort numbered fields with mixed
  conventions properly (e.g. track "05" vs "2"). Default setting is "true".
- Add id3 mapping for shorthand 'position' (in media set) to id3 tag 'mp3.id3tag.disc'

Changes and Fixes
-----------------
- Fix problem with reading file modification date
- Fix problem with reading string tags with numeric data (e.g. Album="5")
- Throw informative error on bad tag values (e.g. non-numeric "year")
  (vs. anonymous ClassCastException when trying to compare years)
- Optional plugin "GenreAnalyst" now writes a report of Artists/Genre and 
  Genre/Artist in each root folder. See notes in plugin folder.
- Add '-h' option to command line (prints syntax)
- minor changes in default properties (layout of playlist header, etc)
- log level "trace" now logs progress in percentage for each root folder being processed 
  (for tracking long-running tasks)

API version 0.2
---------------
- refactored:
    ProcessMonitor.onProcessedRoot() renamed to ProcessMonitor.onListedRoot()
    ProcessSupervisor.okToProcessRoot() renamed to ProcessSupervisor.okToListRoot()
    MP3Item.getLastModified() added 
    Added and reorganized errors
    - PlayListerError is new root class of all errors
    - subclass ProcessError is new root of all runtime errors during process
    - SetupError is now subclass of PlayListerError
    - ItemError classes added to signal errors in tags and tag values
    - Removed parameter-less constructors from most errors to enforce 
      information about error
    - Removed unintentionally redundant SyntaxError.FilterError
- changed:
    MP3ItemCollection.getItems() now returns List<MP3Item> (was: SortedSet<MP3Item>)
- extended: 
	ListSetup.getSortOrder(String sortKey)
	ItemFilter.select(List<MP3Item)
	ItemFilter.select(Set<MP3Item>)
    MP3Item.getAbsolutePath()
    MP3Item.getValues()
	MP3ItemCollection.getNiceSortOrder()
	MP3ItemCollection.getSize()
	MP3Item.getDistinctValue(String tag)
    ProcessMonitor.onCollectedItem() - new param: List<MP3ItemCollector>
    ProcessMonitor.onAcceptedItem() - new param: MP3ItemCollector
    ProcessSupervisor.okToAcceptItem() - new param: MP3ItemCollector
    ProcessSupervisor.okToWriteRoot()
    ProcessSupervisor.okToCollectItem()
    SortOrder
    SorterSyntaxError
	
internal changes
----------------
- Add some brief and preliminary notes on setting up Eclipse (in 'etc' project)
- UTF-8. Got confused about character encoding, tried to get consistent. 
  Intention is to run UTF-8, but some files are default (CP1252), causing my 
  last name to look weird in file headers. Some files have been fixed, the rest 
  will be fixed over time.
- Include a 'doc' directory (the sourceforge "home page") 
- Runtime now includes Apache XML Beans 
  (for reading XML settings and/or write XML reports)
- Add se.p2r.playlister.filter.mp3item.GenericItemFilter
- Add se.p2r.playlister.util.Debug

known issues
------------
- does not parse "track" and "position in mediaset" if given as "1/5"
- does not throw error on bad data in numeric fields (e.g. year="1987[s")
- "Most Recently Added" (MRA) is really Most Recently Modified (it is based
  on File.lastModified()), hence it will also capture changed files
- performance of "groupBy" and MRA in large lists is not good. Since all 
  items are sorted, performance degrades significantly with size of list.
  In particular, there seems to be a mysterious penalty to doing MRA on "days". 

2006-08-29: p2rplaylister 0.5.s1 (alpha)
======================================
Re-released due to download problems with previous release.

internal changes
----------------
- renamed core jar (include ".core" to avoid ambiguity)
- renamed api jar (lowercase)

2006-08-28: p2rplaylister 0.5 (alpha)
=====================================
- simplify launch script; now loads thru an executable jar
- add ability to load plugins for some interfaces (still evolving)
  (one optional plugin provided as sample)
- internal changes to prepare for extensibility (plug-ins)
- fix problem with hack in JavaZoom MP3SPI; no longer returns multiple 
  empty lines for various tags (in particular ID3v1)
- now handles local files (files in root directory being processed)
- job setup file accepts root folders expressed in "unix style" (/my/music)
- logging of suppressed ("empty") lists now done at trace level (not info level)
- log warning for completely empty collections (filter did not match any item)
- include javadoc package
- restructure deliverable files: 
  runtime entire package (including API and all plugs)
  source and javadoc for entire package (including API and all plugs)
  API package with runtime, source and javadoc
- bugfix: handle filters without "or" expressions

2006-07-30: p2rplaylister 0.4 (alpha)
=====================================
First reasonably stable release. Still 'alpha' status, but this version 
should be usable even if property file syntax is still evolving.

- p2rplaylister.bat allocates more heap size (should handle some 20 000 files)
- log summary (files, lists, time) when done 
- debug log includes system properties and max memory (heap size)
- optionally track and log access to setup files (log.level=trace)
- all integer properties can be expressed as 1k (1000), 32M (32000000), etc.
- moved generic utils to se.p2r.util. Might be released as separate package.
- fix default setup of logging (java Logger failed to get lock on %u/p2rplaylister.core)
- updated INSTALLATION.txt 
  simplified sample paths in scheduler setup
  note on redirecting log to stderr (nothing is written on stdout)
  note on multi-line statements in property file (end line with \)
- added ROADMAP.txt
- README.txt: added references to other MP3 tools
- m3u files now includes a "boilerplate" header 
- m3u file formats configurable thru property files
- "splash" now includes time of build
- version now includes status (alpha)

internal changes
----------------
- fix exposed interface of JobSetup.getListSetup()

2006-07-26: p2rplaylister 0.0.3 (alpha)
=======================================
DISCLAIMER: This release is (still) to be considered unstable!
- handle errors in list setup
- log error before aborting
- use Java logging to set up "rotating" logfiles

2006-07-25: p2rplaylister 0.0.2 (alpha)
=======================================
DISCLAIMER: This release is to be considered unstable!
- Fixed a number of typos in INSTALLATION.txt.
- Source files and binaries now in separate zips.
- Zipped without version info in folder name.
- added options to append to logfile
- added some more comments and examples in default properties

Internal changes:
-----------------
- repackaged third party libs and source code to ensure no conflicting content (duplicate="fail")

2006-07-24: p2rplaylister 0.0.1
===============================

Initial unofficial release. 

An alpha release to verify packaging and test-drive the SourceForge File Release System.

Notes :
-----
p2rplaylister depends on a modified version of JavaZOOM MP3SPI 1.9.4 and a subset of ANT 1.6.5.