KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > emb > MediaEntityLocalHome


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.net.URL;
10 import java.util.Collection;
11
12 import javax.ejb.CreateException;
13 import javax.ejb.EJBLocalHome;
14 import javax.ejb.FinderException;
15
16 /**
17  * This interface defines the local home interface of media entity EJBs and
18  * offers services to create and to query persistent and mutable media objects.
19  * It extends javax.ejb.EJBLocalHome.
20  *
21  * <p>The create method provided allows the creation of empty media entity
22  * EJBs. These instances need to be filled with content in a subsequent step,
23  * by using the setName() and setContent() methods.
24  *
25  * <p>Sometimes networks of associated non-embedded media content can become
26  * quite complex. In order to allow the consistent handling of such complex
27  * content structures the importMedia() and exportMedia() operations allows for
28  * consistent import, creation and export or content if for example many
29  * non-embedded parents share identical children. Using the related methods in
30  * the media entity EJB component interfaces would lead to multiple versions of
31  * the shared children being imported/exported.
32  *
33  * <p>Finally, the publishContent() and publishMedia() operations publish a
34  * transient or persistent media object to a protocol server, and returns a URL
35  * or content that allows clients to access the protocol and server specific
36  * copies of said medium and its children. This abstraction allows applications
37  * to access proprietary content delivery services, without exposing the
38  * application to the details of the implementation of those services. For
39  * example, multiple and distributed streaming server technologies can be used
40  * underneath a publish implementation. Implementations of this specification
41  * are not bound to a specific algorithm to determine a suitable protocol
42  * server. Theoretical possibilities range from dynamic selection from a
43  * pre-configured server pool to relating suitable protocol servers statically
44  * with each media entity. The resulting URL/content is either pointing
45  * directly to the cached copy of the media object with a protocol type of
46  * http, rtsp or similar, or it is an http URL pointing to a managed
47  * meta-medium that points to said cached copy.
48  *
49  * @version <tt>$Revision: 1.1 $</tt>
50  * @author <a HREF="mailto:ricardoarguello@users.sourceforge.net">Ricardo
51  * ArgŁello</a>
52  */

53 public interface MediaEntityLocalHome extends EJBLocalHome
54 {
55    final static byte TRANSFER_TYPE_STREAM = 0;
56    final static byte TRANSFER_TYPE_BURST = 1;
57
58    /**
59     * Creates a new media entity EJB with a generated identity key, the value
60     * of <code>System.currentTimeMillis()</code> as value of the <code>lastModified</code>
61     * property, and <code>null</code> as value for all other properties.
62     * Please note most of the methods of the Media Entity returned will throw
63     * exceptions until the name and either the location or the content
64     * properties are set.
65     *
66     * @return media entity bean.
67     * @throws javax.ejb.CreateException is thrown if a problem related to EJB
68     * creation occurs.
69     * @throws MediaException
70     */

71    MediaEntityLocal create() throws CreateException, MediaException;
72
73    /**
74     * Copies the content of the given media entity EJBs and all their direct
75     * and indirect children to the given targetDirectoryLocation, i.e. a URL of
76     * protocol type "file" or any other type supported by the implementation.
77     * The operation returns an array of URLs of the same size as the source
78     * media array. The elements of the resulting array point to file copies of
79     * the source media array elements' content. If the media objects affected
80     * are non-embedded, the content of the copies is modified to correctly
81     * point to the copies of the children's content instead of the original
82     * locations.
83     *
84     * <p>If the given <code>targetDirectoryLocation</code> is <code>null</code>,
85     * a default export directory location is used. The operation makes sure
86     * that each media entity EJB affected corresponds to exactly one media
87     * object created. Note that the names of the copied media objects may
88     * differ from the original ones, that the operation makes sure no existing
89     * files are overwritten by this operation, and that implementations are
90     * permitted to copy children to subdirectories of the given
91     * targetDirectoryLocation. Also note that the resulting <code>targetLocation</code>
92     * URLs are returned in the order of their respective media entity EJBs.
93     * Duplicate media entity EJBs result in <code>targetLocation</code> URLs
94     * returned in multiple array slots, <code>null</code> media entity EJBs
95     * result in respective <code>null</code> values in the result. Finally,
96     * note that not all media objects exported are necessarily returned, just
97     * the ones for which corresponding media entity EJBs were passed.
98     *
99     * @param sourceMedia
100     * @param targetDirectoryLocation
101     * @return URLs array
102     * @throws java.lang.NullPointerException if the given source media array is
103     * <code>null</code>.
104     * @throws javax.emb.ContentAccessException in case content transfer fails.
105     * @throws javax.emb.MediaFormatException if there is a problem dealing with
106     * one of the media formats involved.
107     * @throws javax.emb.MalformedLocationException if the URL given is
108     * malformed or has a protocol type not supported by the
109     * implementation.
110     */

111    URL[] exportMedia(
112       MediaEntityLocal[] sourceMedia,
113       URL targetDirectoryLocation)
114       throws MediaException;
115
116    /**
117     * Returns all media entities in the persistent store whose description
118     * contains the given String. The query is case-sensitive. Note that passing
119     * an empty string will return all media entity beans in the persistent
120     * store that have a description different from <code>null</code>.
121     * Passing in <code>null</code> or a partial description not present in
122     * the data store will result in an empty collection.
123     *
124     * @param partialDescription description.
125     * @return all media entities whose description contains the given String.
126     * @throws javax.ejb.FinderException if a finder problem occurs.
127     */

128    Collection findByPartialDescription(String partialDescription)
129       throws FinderException;
130
131    /**
132     * Returns all media entities in the persistent store whose location URL
133     * contains the given String. The query is case-sensitive. Note that passing
134     * an empty string will return all media entity beans in the persistent
135     * store that have a location different from <code>null</code>. Passing
136     * in <code>null</code> or a partial location not present in the data
137     * store will result in an empty collection.
138     *
139     * @param partialLocation location.
140     * @return all media entities in the persistent store whose location URL
141     * contains the given String.
142     * @throws javax.ejb.FinderException if a finder problem occurs.
143     */

144    Collection findByPartialLocation(String partialLocation)
145       throws FinderException;
146
147    /**
148     * Returns the media entity with the given identity.
149     *
150     * @param identity identity.
151     * @throws java.lang.NullPointerException if the value passed is <code>null</code>.
152     * @throws javax.ejb.FinderException if a finder problem occurs or no media
153     * entity is found.
154     */

155    MediaEntityLocal findByPrimaryKey(String identity) throws FinderException;
156
157    /**
158     * Imports the given media objects and all their direct and indirect
159     * children from the given source locations and creates new EJBs for said
160     * media objects and children. For the media entity EJBs directly created
161     * from the source locations given, the names are derived from the given
162     * name array at equivalent indices. If a name value is null a generated
163     * name is used, possibly based on the related source location. For all
164     * other media entity EJBs created, the name properties are derived from the
165     * links present in their respective parent content.
166     *
167     * <p>The operation returns an array of media entity EJBs of the same size
168     * as the source location array. The elements of the resulting array are
169     * based on the content of the corresponding elements of the source location
170     * array.
171     *
172     * <p>The operation makes sure that each media object affected corresponds
173     * to exactly one media entity EJB created in the operations context. Note
174     * that the resulting Media ent ity EJBs are returned in the order of their
175     * respective sourceLocations. Duplicate sourceLocations result in media
176     * entity EJBs returned in multiple array slots, null sourceLocations result
177     * in respective null values in the result. If a source location is given
178     * multiple times with differing names, one of the names is picked for the
179     * resulting media entity EJB. Finally, note that not all media entity EJBs
180     * created are necessarily returned, just the ones for which corresponding
181     * location URLs were passed.
182     *
183     * @param sourceLocations source locations.
184     * @param names names.
185     * @return @throws java.lang.NullPointerException if one of the arrays
186     * passed is <code>null</code>.
187     * @throws java.lang.IllegalArgumentException if the two arrays passed
188     * mismatch in length or if one or more of the name arguments passed
189     * contain invalid characters.
190     * @throws javax.ejb.CreateException if the creation of a media entity EJB
191     * fails.
192     * @throws javax.emb.ContentAccessException if content transfer fails.
193     * @throws javax.emb.MediaFormatException if there's a problem dealing with
194     * one of the media formats involved.
195     * @throws javax.emb.MalformedLocationException if one of the URLs given is
196     * malformed or has a protocol type not supported by the
197     * implementation.
198     * @throws javax.emb.ContentTooLargeException if one the media entity EJB
199     * contents would become larger than supported by the
200     * implementation.
201     */

202    MediaEntityLocal[] importMedia(URL[] sourceLocations, String[] names)
203       throws CreateException, MediaException;
204
205    /**
206     *
207     * This operation publishes persistent or transient media content to a
208     * protocol server and returns a URL. The URL allows web clients to access
209     * the protocol and server specific copies of said medium. Note that it also
210     * exports its children if a non-embedded media entity EJB is passed. If the
211     * medium is persistent (i.e. is a media entity EJB), said copies will
212     * likely be managed and updated once the original content changes.
213     * Optionally, the selection of a suitable protocol server can be influenced
214     * using the given constraints object. Implementations of this specification
215     * are not bound to a specific algorithm to determine a suitable protocol
216     * server. Theoretical possibilities range from dynamic selection from a
217     * pre-configured server pool to relating suitable protocol servers
218     * statically with each media entity. The resulting URL is either pointing
219     * directly to the cached copy of the media object with a protocol type of
220     * http, rtsp or similar, or it is an http URL pointing to a managed
221     * meta-medium that points to said cached copy.
222     *
223     * <p>The kind of protocol server chosen may be determined by the given
224     * transferType. Specified values are:
225     *
226     * <ul><li>TRANSFER_TYPE_STREAM for streaming of media content, using a
227     * stream server as protocol server.</li>
228     *
229     * <li>TRANSFER_TYPE_BURST for burst transfer of media content, usually
230     * using a web server as protocol server. <li></ul>
231     *
232     * <p>Specified protocol constraint types are:
233     *
234     * <ul><li>"SERVER_TYPE" for restriction of stream servers to chose from.
235     * The constraint value is an array of Strings. Specified constraint values
236     * are "VideoCharger" for IBM VideoCharger servers, "RealSystem" for
237     * RealNetworks RealSystem servers, and "Windows Media" for Microsoft
238     * Windows Media services, and "QuickTime" for Apple QuickTime servers. The
239     * protocol server selected will be of one of these types. Note that some
240     * server types can feed a number of different clients.</li>
241     *
242     * <li>"CLIENT_TYPE" for restriction of stream servers to chose from. The
243     * constraint value is an array of Strings. Specified constraint values are
244     * "VideoCharger" for IBM VideoCharger players, "RealPlayer" for
245     * RealNetworks players, and "Windows Media" for Microsoft Windows Media
246     * players, and "QuickTime" for Apple QuickTime players. The protocol server
247     * selected will support one of these client types. Note that some players
248     * can work with a number of protocol servers.</li></ul>
249     *
250     * <p>In case the selected protocol server supports more than one client
251     * type, the client type is not constrained and a meta-medium has to be
252     * generated, said meta-medium is generated for the default client type of
253     * the selected protocol server. If in a similar case there is more than one
254     * constraint value for the client type, the constraint value is interpreted
255     * as a priority list and therefore the meta-medium is generated for the
256     * first client type in that list that is supported by the selected protocol
257     * server.
258     *
259     * @param content content.
260     * @param transferType transfer type.
261     * @param constraints constraints.
262     * @return URL
263     * @throws java.lang.NullPointerException if the media object passed is
264     * <code>null</code>.
265     * @throws java.lang.IllegalArgumentException if a transfer type is passed
266     * that is not supported by the implementation, or if a protocol
267     * type <code>SERVER_TYPE</code> or <code>CLIENT_TYPE</code> is
268     * passed with a value that is not an array of Strings.
269     * @throws javax.emb.NoServerFoundException if no suitable protocol server
270     * can be determined.
271     * @throws javax.emb.ContentAccessException if content transfer fails or if
272     * non-embedded content is passed in anything other than a media
273     * entity EJB.
274     * @throws javax.emb.MediaFormatException if there's a problem dealing with
275     * one of the media formats involved.
276     * @throws javax.emb.LinkTranslationException if ingesting protocol specific
277     * links into copies of non-embedded media objects fails.
278     * @throws javax.emb.ConversionException if the middleware fails converting
279     * the media content to another format in order to make it suitable
280     * for a specific protocol server.
281     */

282    URL publishContent(
283       Media content,
284       byte transferType,
285       ProtocolConstraints constraints)
286       throws MediaException;
287
288    /**
289     * This operation publishes the given playlist of persistent media entities
290     * to a protocol server and returns a meta medium that allows clients to
291     * access the protocol and server specific copies of said playlist and its
292     * children. If the implementation chooses to cache the media objects on the
293     * protocol server chosen, it must be guaranteed that eventual child copies
294     * are also managed and will be updated if the original content changes.
295     *
296     * <p>Optionally, the selection of a suitable protocol server can be
297     * influenced using the given constraints object. Implementations of this
298     * specification are not bound to a specific algorithm to determine a
299     * suitable protocol server. Theoretical possibilities range from dynamic
300     * selection from a pre-configured server pool to relating suitable protocol
301     * servers statically with each media entity. The content of the resulting
302     * meta medium is pointing directly to the cached copies of the given media
303     * entities with a protocol type of http, rtsp or similar.
304     *
305     * <p>The kind of protocol server chosen may be determined by the given
306     * transferType. Specified values are:
307     *
308     * TRANSFER_TYPE_STREAM</code> for streaming of media content, using a
309     * stream server as protocol server.</li>
310     *
311     * <li><code>TRANSFER_TYPE_BURST</code> for burst transfer of media
312     * content, usually using a web server as protocol server.</li></ul>
313     *
314     * <p>Specified protocol constraint types are:
315     *
316     * <ul><li>"SERVER_TYPE" for restriction of stream servers to chose from.
317     * The constraint value is an array of Strings. Specified constraint values
318     * are "VideoCharger" for IBM VideoCharger servers, "RealSystem" for
319     * RealNetworks servers, and "Windows Media" for Microsoft Media services,
320     * and "QuickTime" for Apple QuickTime servers. The protocol server selected
321     * will be of one of these types. Note that some server types can feed a
322     * number of different clients.</li>
323     *
324     * <li>"CLIENT_TYPE" for restriction of stream servers to chose from. The
325     * constraint value is an array of Strings. Specified constraint values are
326     * "VideoCharger" for IBM VideoCharger players, "RealPlayer" for
327     * RealNetworks players, and "Windows Media" for Microsoft Windows Media
328     * players, and "QuickTime" for Apple QuickTime players. The protocol server
329     * selected will support one of these client types. Note that some players
330     * can work with a number of protocol servers.</li></ul>
331     *
332     * <p>If the selected protocol server supports more than one client type
333     * and the client type is not constrained, a meta-medium is generated for
334     * the default client type of the selected protocol server. If in a similar
335     * case there is more than one constraint value for the client type, the
336     * constraint value is interpreted as a priority list and therefore the
337     * meta-medium is generated for the first client type in that list that is
338     * supported by the selected protocol server.
339     *
340     * <p>Both the format and the content of the resulting meta-medium are
341     * considered proprietary to an implementation of this specification.
342     * Suitable are streaming metafile formats like Real .ram or IBM .ivs for
343     * streaming, or HTML files - containing auto load links for playlists
344     * consisting of exactly one entry, or clickable links for playlists
345     * consisting of two or more entries - for burst transfer. However, a
346     * Servlet must be able to return the resulting meta-medium directly to its
347     * requesting client to cause a media player to render the playlist on said
348     * client.
349     *
350     * <p>In contrast, publishing the same playlist for the HTML protocol would
351     * have resulted in an html meta media containing HREF links to the SMIL
352     * presentation and the MPEG movie. Also, the cache copy of the SMIL
353     * presentation would contain HTML references to its child media in this
354     * case.
355     *
356     * @param playlist
357     * @param transferType
358     * @param constraints
359     * @return @throws java.lang.NullPointerException if the playlist passed is
360     * <code>null</code>.
361     * @throws java.lang.IllegalArgumentException if a transfer type is passed
362     * that is not supported by the implementation, or if a protocol
363     * type <code>SERVER_TYPE</code> or <code>CLIENT_TYPE</code> is
364     * passed with a value that is not an array of Strings.
365     * @throws javax.emb.NoServerFoundException if no suitable protocol server
366     * can be determined.
367     * @throws javax.emb.ContentAccessException if content transfer fails.
368     * @throws javax.emb.MediaFormatException if there's a problem dealing with
369     * one of the media formats involved.
370     * @throws javax.emb.LinkTranslationException if ingesting protocol specific
371     * links into copies of non-embedded media objects fails.
372     * @throws javax.emb.ConversionException if the middleware fails converting
373     * the media content to another format in order to make it suitable
374     * for a specific protocol server.
375     */

376    Media publishMedia(
377       MediaEntityLocal[] playlist,
378       byte transferType,
379       ProtocolConstraints constraints)
380       throws MediaException;
381 }
Popular Tags