KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > emb > MediaFormat


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.Serializable;
11 import java.net.URL;
12
13 /**
14  * This interface is used throughout Enterprise Media Beans for operations that
15  * require knowledge of the media format. Each specific supported media format
16  * requires an implementation of this interface to handle format specifics
17  * correctly. Applications should not create instances directly using a
18  * constructor, but instead query them using the {@link MediaFormatRegistry}
19  * class. As implementations of this interface may have to be transferred over
20  * remote boundaries at times, the MediaFormat interface extends
21  * {@link java.io.Serializable}.
22  *
23  * @version <tt>$Revision: 1.3 $</tt>
24  * @author <a HREF="mailto:ricardoarguello@users.sourceforge.net">Ricardo
25  * Argüello</a>
26  */

27 public interface MediaFormat extends Serializable
28 {
29    /**
30     * Assembles the given media segments and returns the resulting media
31     * content as a byte array. The optional media location describes where the
32     * content itself is stored, and passing it allows links to child media to
33     * be written as relative file paths. In case the given media location is
34     * <code>null</code>, all links in the resulting media content will be
35     * URLs. In case it is not <code>null</code>, those links that can be
36     * expressed relative to the given URL will be relative file paths, and all
37     * others will be URLs.
38     *
39     * <p>This means a media object that has been disassembled into media
40     * segments beforehand can be reassembled using this operation. The given
41     * media location is used to handle relative links to external media
42     * correctly. Media Entity Beans use this operation when maintaining
43     * referential integrity between complex graphs of persistent, non-embedded,
44     * media objects. The implicit limitation of media size to a theoretical
45     * limit of 2GB should not impose a restriction in practice as this
46     * operation is only of value for non-embedded media, which tends to be
47     * relatively small in size.
48     *
49     * @param mediaLocation the intended location of the media to be assembled.
50     * @param mediaSegments the segments that are to be assembled.
51     * @return the assembled content.
52     * @throws javax.emb.ContentTooLargeException if the resulting byte array
53     * size exceeds the theoretical maximum Java array size of 2 GB,
54     * @throws javax.emb.LinkTranslationException if there's a problem
55     * transforming one of the media segment child locations into a
56     * format specific link.
57     * @throws javax.emb.FormatSyntaxException in case of embedded media
58     * formats, thrown if the given media segment array contains more
59     * than one element, or if an element is passed that contains a
60     * child link that is not <code>null</code>.
61     * @throws java.lang.NullPointerException if the given segment array is
62     * <code>null</code>.
63     */

64    byte[] assembleContent(URL mediaLocation, MediaSegment[] mediaSegments)
65       throws MediaException;
66
67    /**
68     * Disassembles the given media content into an array of media segments
69     * preserving the order of the original content, and returns said array of
70     * media segments. The optional media location describes where the content
71     * itself is stored, and passing it allows relative links to child media to
72     * be interpreted.
73     *
74     * <p>In case of simple media formats, the resulting media segment array
75     * contains exactly one element, which consists of <code>null</code> as
76     * child location and the complete media content as content. Media Entity
77     * Beans use this operation when maintaining referential integrity between
78     * complex graphs of persistent, non embedded, media objects. Note that this
79     * operation is only of value for non-embedded media formats. As the
80     * reassembly is limited to media up to 2GB in size, the
81     * {@link MediaFormat.isEmbedded()}operation should be used to determine if
82     * disassembling a given media content is of value beforehand.
83     *
84     * @param mediaLocation the location of the media to be disassembled.
85     * @param mediaContent the content to be disassembled.
86     * @return the segments.
87     * @throws javax.emb.FormatSyntaxException if the content does not match the
88     * expected media format.
89     * @throws javax.emb.LinkTranslationException if the given media location is
90     * <code>null</code> and the given content contains child links
91     * that are not URLs.
92     * @throws java.lang.NullPointerException if the content passed is <code>null</code>.
93     */

94    MediaSegment[] disassembleContent(URL mediaLocation, byte[] mediaContent)
95       throws MediaException;
96
97    /**
98     * Extracts a media header instance from the given media content and returns
99     * it. The information presented by the header is up to the implementation
100     * of the media format bean, and the information returned can therefore be
101     * the complete header information as defined in the relevant media format
102     * standard, no information at all, or something in between. However,
103     * implementers are encouraged to return header information as complete as
104     * possible, as such information can be highly useful for format specific
105     * algorithms and optimizations.
106     *
107     * <p>Please note that the given input stream is not closed once the
108     * operation is successfully completed.
109     *
110     * @param content the media content to extract the header from.
111     * @return the header.
112     * @throws javax.emb.FormatSyntaxException if the given media content does
113     * not match the syntax defined for the receiver.
114     * @throws javax.emb.FormatFeatureException if the header cannot be
115     * extracted because a vital feature of the media format involved is
116     * not supported.
117     * @throws java.lang.NullPointerException if the value passed is <code>null</code>.
118     */

119    MediaHeader extractHeader(InputStream content) throws MediaException;
120
121    /**
122     * Extracts a proxy from the given media content and returns it. The proxy
123     * may be of any media format. For example, a key frame image may be
124     * returned in case of video content, a waveform image in case of audio
125     * content, or a thumbnail in case of image content. In case there's a
126     * problem creating the surrogate, a default format specific proxy must be
127     * returned - for example <code>GenericMediaFormat.GENERIC_PROXY</code>.
128     * Please note that the given input stream is closed once the operation is
129     * completed.
130     *
131     * @param content the content to extract the proxy from.
132     * @return the proxy.
133     * @throws javax.emb.MediaException if the given media is not compatible
134     * with the receiver
135     * @throws java.lang.NullPointerException if the argument passed is <code>null</code>.
136     */

137    Media extractProxy(InputStream content) throws MediaException;
138
139    /**
140     * Returns the default MIME type for the given media format as a String. If
141     * there is no suitable MIME type, <code>Media.MIME_TYPE_UNKNOWN</code>
142     * should be returned.
143     *
144     * @return the default MIME type.
145     */

146    public String getDefaultMimeType();
147
148    /**
149     * Returns <code>false</code> if the media format allows links to external
150     * media, or true otherwise. It can be used to determine if the media
151     * content has to be examined and possibly altered when a persistent media
152     * object is moved from one location to another while having child and/or
153     * parent dependencies to other media objects.
154     *
155     * @return <code>true</code> if the format is embedded, <code>false</code>
156     * if it is non-embedded.
157     */

158    public boolean isEmbedded();
159
160    /**
161     * Returns <code>true</code> if it is always desirable to stream media of
162     * this format, or false otherwise. For example, it is not always desirable
163     * to stream JPEG or GIF images, even given the possibility to stream them
164     * with a Real player. Servlets can use this information to decide whether
165     * they should try to stream content or transfer it using burst transfer
166     * instead.
167     *
168     * @return <code>true</code> if it desirable to stream the format, <code>false</code>
169     * otherwise.
170     */

171    public boolean isStreamingDesirable();
172 }
Popular Tags