KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > emb > MediaConverter


1 /*
2  * JBoss, the OpenSource J2EE webOS
3  *
4  * Distributable under LGPL license. See terms of license at gnu.org.
5  */
6
7 package javax.emb;
8
9 import java.io.InputStream;
10 import java.io.OutputStream;
11
12 /**
13  * A media converter performs actual conversions of media content.
14  * Implementations of this interface can work in one of two ways: Synchronous
15  * converters perform conversions completely before returning the input stream
16  * on the converted content. Asynchronous converters return a piped input
17  * stream immediately after checking the input and spawning a new thread to
18  * perform the conversion. The latter has the advantage of being very memory
19  * efficient in case the result is consumed immediately, while the first tends
20  * to be more robust because it doesn't require the maintenance of additional
21  * threads of execution.
22  *
23  * <p>The design assumes a converter is instantiated for a specific kind of
24  * conversion. Therefore, classes implementing this interface should take a
25  * media converter spec as a constructor argument. Said media converter spec
26  * should contain the necessary conversion parameters, for example the desired
27  * bandwidth for a WAV to MP3 converter.
28  *
29  * @version <tt>$Revision: 1.3 $</tt>
30  * @author <a HREF="mailto:ricardoarguello@users.sourceforge.net">Ricardo
31  * Argüello</a>
32  */
33 public interface MediaConverter
34 {
35    /**
36     * Converts the media content offered on the given input stream and returns
37     * the converted media content as an input stream. Implementations of this
38     * method may, but are not required to, spawn a new thread to perform the
39     * actual conversion, and return a PipedInputStream immediately.
40     *
41     * @param inputStream the input stream to process.
42     * @return the processed input stream.
43     * @throws java.lang.NullPointerException if the value passed is <code>null</code>.
44     * @throws javax.emb.FormatSyntaxException if the content provided with the
45     * input stream does not meet the expected format syntax.
46     * @throws javax.emb.FormatFeatureException if the content provided in the
47     * input stream utilizes a format feature not supported by the
48     * receiver.
49     * @throws javax.emb.LinkTranslationException if the content provided
50     * contains relative links to child media objects.
51     * @throws javax.emb.ContentAccessException if an I/O problem occurs or if
52     * said child links cannot be resolved to child media content.
53     * @throws javax.emb.ConversionException if the conversion fails because a
54     * conversion specific problem occurred.
55     */
56    InputStream process(InputStream inputStream) throws MediaException;
57
58    /**
59     * Converts the media content offered on the given input stream and writes
60     * the converted media content on the given output stream. In any case, this
61     * method will block until the conversion is completed.
62     *
63     * @param inputStream the stream to process.
64     * @param outputStream the processed stream.
65     * @throws java.lang.NullPointerException if one the values passed is <code>null</code>.
66     * @throws javax.emb.FormatSyntaxException if the content provided with the
67     * input stream does not meet the expected format syntax.
68     * @throws javax.emb.FormatFeatureException if the content provided in the
69     * input stream utilizes a format feature not supported by the
70     * receiver.
71     * @throws javax.emb.LinkTranslationException if the content provided
72     * contains relative links to child media objects.
73     * @throws javax.emb.ContentAccessException if an I/O problem occurs or if
74     * said child links cannot be resolved to child media content.
75     * @throws javax.emb.ConversionException is thrown if the conversion fails
76     * because a conversion specific problem occurred.
77     */
78    public void process(InputStream inputStream, OutputStream outputStream)
79       throws MediaException;
80 }
Popular Tags