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 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Java Books Remove Frame
Popular Tags