Docjar: A Java Source and Docuemnt Enginecom.*    java.*    javax.*    org.*    all    new    plug-in

Quick Search    Search Deep

org.esau.ptarmigan
Interface Generator  view Generator download Generator.java

All Superinterfaces:
org.xml.sax.ContentHandler, org.xml.sax.XMLFilter, org.xml.sax.XMLReader

public interface Generator
extends org.xml.sax.XMLFilter, org.xml.sax.ContentHandler

Generator

The main interface to the Ptarmigan SAX event generator.

Metadata Extraction

Ptarmigan's forté is the extraction of metadata from media files.

Providing an InputStream or system-id in an InputSource to be fed to Ptarmigan will produce SAX events conforming to the Ptarmigan schema.

Convenient Data Positioning

Apart from extracting the metadata, you can have Ptarmigan position the input stream to the start of the MPEG (or other) data. This is especially useful for one-pass consumption.

To use this feature you must:

The recommended size is the default of 8192 bytes. More is better, but too much may slow down parsing.

Ptarmigan will consume the metadata at the start of the stream, produce SAX events and leave the InputStream positioned at the start of the MPEG (or other) data.

If there's a problem positioning the stream to the start of data there will be an error reported in the <log/> of the resulting XML. See ptarmigan.xsd.

Note that if a text source (such as an XML-based playlist) is detected, it will read beyond the buffer limit to consume the entire source.

If you do not need data positioning, you do not need to provide an BufferedInputStream nor do you need to set the PROPERTY_READ_LIMIT property. The InputStream will be at an arbitrary position.

The InputSource

As mentioned above you can provide a BufferedInputStream in the SAX InputSource.

You also have the option of providing only a system-id. Ptarmigan will open up an InputStream to the source as necessary.

However, you may want to provide a system-id in any case, as Ptarmigan may be able provide additional metadata details. A system-id is required if you want to receive the file properties, for example.

Also, providing an InputStream is usually needed when pipelining the SAX events. Various SAX filters may not be able to properly open a file with unusual characters in the filename.

Example

Below is an example of usage with a Digester SAX consumer:

     File infile = new File(args[0]);
     String system_id = infile.toURL().toExternalForm();

     // the consumer
     SampleDigester digester = new SampleDigester();
     digester.configureDigester();

     // the producer
     Generator generator = GeneratorFactory.newInstance();
     generator.setFeature(Generator.FEATURE_INCLUDE_PLAYLIST_ENTRIES, true);

     // attach the consumer to the producer
     generator.setContentHandler(digester);

     // produce and consume!
     generator.parse(new InputSource(system_id));

     System.out.println("\n\nSampleDigester: " + system_id
                        + "\n" + digester.getRoot());
 

For an extended example that uses Ptarmigan in a SAX pipeline see http://jreceiver.sourceforge.net

Version:
$Revision: 1.4 $ $Date: 2002/09/24 02:52:08 $

Field Summary
static boolean DEFAULT_INCLUDE_DIGEST
          by default, do not calculate the digest
static boolean DEFAULT_INCLUDE_PLAYLIST_ENTRIES
          by default, do not include playlist entries in playlist metadata
static int DEFAULT_PROPERTY_READ_LIMIT
          by default, read as many as 8192 bytes from the start of a stream to extract tags and determine mime-type.
static java.lang.String FEATURE_INCLUDE_DIGEST
          Use with setFeature() to indicate whether or not a /ptarmigan/data/digest member will be created.
static java.lang.String FEATURE_INCLUDE_PLAYLIST_ENTRIES
          Use with setFeature() to indicate whether or not playlist entries will be included.
static java.lang.String PROPERTY_READ_LIMIT
          Use with setProperty() to indicate the limit on the number of bytes to be read from the start of a stream to extract tags and determine mime-type.
 
Method Summary
 void resetData()
          Resets data members for Generator reuse.
 
Methods inherited from interface org.xml.sax.XMLFilter
getParent, setParent
 
Methods inherited from interface org.xml.sax.XMLReader
getContentHandler, getDTDHandler, getEntityResolver, getErrorHandler, getFeature, getProperty, parse, parse, setContentHandler, setDTDHandler, setEntityResolver, setErrorHandler, setFeature, setProperty
 
Methods inherited from interface org.xml.sax.ContentHandler
characters, endDocument, endElement, endPrefixMapping, ignorableWhitespace, processingInstruction, setDocumentLocator, skippedEntity, startDocument, startElement, startPrefixMapping
 

Field Detail

FEATURE_INCLUDE_DIGEST

public static final java.lang.String FEATURE_INCLUDE_DIGEST
Use with setFeature() to indicate whether or not a /ptarmigan/data/digest member will be created.

Defaults to FALSE.

See Also:
Constant Field Values

DEFAULT_INCLUDE_DIGEST

public static final boolean DEFAULT_INCLUDE_DIGEST
by default, do not calculate the digest

See Also:
Constant Field Values

FEATURE_INCLUDE_PLAYLIST_ENTRIES

public static final java.lang.String FEATURE_INCLUDE_PLAYLIST_ENTRIES
Use with setFeature() to indicate whether or not playlist entries will be included.

Defaults to FALSE.

NOTE: large playlist files will generate correspondingly large XML content. A SAX Filter which extracts playlist entries and writes them to a database as their SAX events are received is one way to avoid large documents in memory.

See Also:
Constant Field Values

DEFAULT_INCLUDE_PLAYLIST_ENTRIES

public static final boolean DEFAULT_INCLUDE_PLAYLIST_ENTRIES
by default, do not include playlist entries in playlist metadata

See Also:
Constant Field Values

PROPERTY_READ_LIMIT

public static final java.lang.String PROPERTY_READ_LIMIT
Use with setProperty() to indicate the limit on the number of bytes to be read from the start of a stream to extract tags and determine mime-type.

This is typically used in one-pass stream consumption, where the consumer wants the stream positioned to the start of the MPEG (or equivalent) data.

Note that text sources, such as XML-based playlists, will be consumed in their entireity if the despite this feature.

See Also:
Constant Field Values

DEFAULT_PROPERTY_READ_LIMIT

public static final int DEFAULT_PROPERTY_READ_LIMIT
by default, read as many as 8192 bytes from the start of a stream to extract tags and determine mime-type.

See Also:
Constant Field Values
Method Detail

resetData

public void resetData()
Resets data members for Generator reuse.

Note that features and properties are NOT reset to defaults as they are usually set once after generator creation.