org.esau.ptarmigan
Interface Generator

All Superinterfaces:

org.xml.sax.ContentHandler, org.xml.sax.XMLFilter, org.xml.sax.XMLReader

All Known Implementing Classes:

GeneratorImpl

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:

• provide a BufferedInputStream in the InputSource
• set the PROPERTY_READ_LIMIT to the size of that buffer

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 $

Author:

Reed Esau

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.

DEFAULT_INCLUDE_DIGEST

public static final boolean DEFAULT_INCLUDE_DIGEST

by default, do not calculate the digest

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.

DEFAULT_INCLUDE_PLAYLIST_ENTRIES

public static final boolean DEFAULT_INCLUDE_PLAYLIST_ENTRIES

by default, do not include playlist entries in playlist metadata

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.

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.

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.