Source code: org/esau/ptarmigan/Generator.java
1 /* $Header: /cvsroot/ptarmigan/ptarmigan/src/java/org/esau/ptarmigan/Generator.java,v 1.4 2002/09/24 02:52:08 reedesau Exp $ */
2
3 package org.esau.ptarmigan;
4
5 import java.io.IOException;
6 import java.io.File;
7 import java.net.URL;
8 import java.net.MalformedURLException;
9
10 import org.xml.sax.ContentHandler;
11 import org.xml.sax.XMLFilter;
12
13 /**
14 * <b>Generator</b>
15 * <p>
16 * The main interface to the Ptarmigan SAX event generator.
17 * <p>
18 * <b>Metadata Extraction</b>
19 * <p>
20 * Ptarmigan's forté is the extraction of metadata from media files.
21 * <p>
22 * Providing an InputStream or system-id in an InputSource to be fed
23 * to Ptarmigan will produce SAX events conforming to the Ptarmigan
24 * schema.
25 * <p>
26 * <b>Convenient Data Positioning</b>
27 * <p>
28 * Apart from extracting the metadata, you can have Ptarmigan position
29 * the input stream to the start of the MPEG (or other) data. This is
30 * especially useful for one-pass consumption.
31 * <p>
32 * To use this feature you must:
33 * <p>
34 * <UL>
35 * <LI>provide a BufferedInputStream in the InputSource
36 * <LI>set the PROPERTY_READ_LIMIT to the size of that buffer
37 * </UL>
38 * <p>
39 * The recommended size is the default of 8192 bytes. More is better,
40 * but too much may slow down parsing.
41 * <p>
42 * Ptarmigan will consume the metadata at the start of the stream,
43 * produce SAX events and leave the InputStream positioned at the start
44 * of the MPEG (or other) data.
45 * <p>
46 * If there's a problem positioning the stream to the start of data there
47 * will be an error reported in the <log/> of the resulting XML.
48 * See ptarmigan.xsd.
49 * <P>
50 * Note that if a text source (such as an XML-based playlist) is detected,
51 * it will read beyond the buffer limit to consume the entire source.
52 * <p>
53 * If you do not need data positioning, you do not need to provide an
54 * BufferedInputStream nor do you need to set the PROPERTY_READ_LIMIT
55 * property. The InputStream will be at an arbitrary position.
56 * <p>
57 * <B>The InputSource</B>
58 * <P>
59 * As mentioned above you can provide a BufferedInputStream in
60 * the SAX InputSource.
61 * <P>
62 * You also have the option of providing only a system-id.
63 * Ptarmigan will open up an InputStream to the source as necessary.
64 * <P>
65 * However, you may want to provide a system-id in any case, as
66 * Ptarmigan may be able provide additional metadata details.
67 * A system-id is required if you want to receive the file properties,
68 * for example.
69 * <P>
70 * Also, providing an InputStream is usually needed when pipelining
71 * the SAX events. Various SAX filters may not be able to
72 * properly open a file with unusual characters in the filename.
73 * <P>
74 * <B>Example</B>
75 * <p>
76 * Below is an example of usage with a Digester SAX consumer:
77 * <P>
78 * <PRE>
79 * File infile = new File(args[0]);
80 * String system_id = infile.toURL().toExternalForm();
81 *
82 * // the consumer
83 * SampleDigester digester = new SampleDigester();
84 * digester.configureDigester();
85 *
86 * // the producer
87 * Generator generator = GeneratorFactory.newInstance();
88 * generator.setFeature(Generator.FEATURE_INCLUDE_PLAYLIST_ENTRIES, true);
89 *
90 * // attach the consumer to the producer
91 * generator.setContentHandler(digester);
92 *
93 * // produce and consume!
94 * generator.parse(new InputSource(system_id));
95 *
96 * System.out.println("\n\nSampleDigester: " + system_id
97 * + "\n" + digester.getRoot());
98 * </PRE>
99 * <p>
100 * For an extended example that uses Ptarmigan in a SAX pipeline
101 * see http://jreceiver.sourceforge.net
102 *
103 * @author Reed Esau
104 * @version $Revision: 1.4 $ $Date: 2002/09/24 02:52:08 $
105 */
106 public interface Generator extends XMLFilter, ContentHandler {
107
108 /**
109 * Resets data members for Generator reuse.
110 * <p>
111 * Note that features and properties are NOT reset to defaults
112 * as they are usually set once after generator creation.
113 */
114 public void resetData();
115
116 /**
117 * Use with setFeature() to indicate whether or not a
118 * /ptarmigan/data/digest member will be created.
119 * <p>
120 * Defaults to FALSE.
121 */
122 static final String FEATURE_INCLUDE_DIGEST =
123 "http://esau.org/ptarmigan/feature/include_digest";
124
125 /**
126 * by default, do not calculate the digest
127 */
128 static final boolean DEFAULT_INCLUDE_DIGEST = false;
129
130 /**
131 * Use with setFeature() to indicate whether or not playlist entries
132 * will be included.
133 * <p>
134 * Defaults to FALSE.
135 * <p>
136 * NOTE: large playlist files will generate correspondingly large
137 * XML content. A SAX Filter which extracts playlist entries and
138 * writes them to a database as their SAX events are received is
139 * one way to avoid large documents in memory.
140 */
141 static final String FEATURE_INCLUDE_PLAYLIST_ENTRIES =
142 "http://esau.org/ptarmigan/feature/include_playlist_entries";
143
144 /**
145 * by default, do not include playlist entries in playlist metadata
146 */
147 static final boolean DEFAULT_INCLUDE_PLAYLIST_ENTRIES = false;
148
149
150 /**
151 * Use with setProperty() to indicate the limit on the number of bytes
152 * to be read from the start of a stream to extract tags and determine
153 * mime-type.
154 * <p>
155 * This is typically used in one-pass stream consumption, where the
156 * consumer wants the stream positioned to the start of the MPEG
157 * (or equivalent) data.
158 * <p>
159 * Note that text sources, such as XML-based playlists, will be consumed
160 * in their entireity if the despite this feature.
161 */
162 static final String PROPERTY_READ_LIMIT =
163 "http://esau.org/ptarmigan/property/read_limit";
164
165 /**
166 * by default, read as many as 8192 bytes from the start of a stream
167 * to extract tags and determine mime-type.
168 */
169 static final int DEFAULT_PROPERTY_READ_LIMIT = 8192;
170 }
171
172 /*
173 PTARMIGAN MODIFIED BSD LICENSE
174
175 Copyright (c) 2002, Reed Esau (reed.esau@pobox.com) All rights reserved.
176
177 Redistribution and use in source and binary forms, with or without
178 modification, are permitted provided that the following conditions are
179 met:
180
181 Redistributions of source code must retain the above copyright notice,
182 this list of conditions and the following disclaimer.
183
184 Redistributions in binary form must reproduce the above copyright notice,
185 this list of conditions and the following disclaimer in the documentation
186 and/or other materials provided with the distribution.
187
188 Neither the name of the Ptarmigan Project
189 (http://ptarmigan.sourceforge.net) nor the names of its contributors may
190 be used to endorse or promote products derived from this software without
191 specific prior written permission.
192
193 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
194 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
195 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
196 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
197 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
198 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
199 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
200 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
201 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
202 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
203 POSSIBILITY OF SUCH DAMAGE.
204 */