MediaEntityLocal


1   /*
2    * JBoss, the OpenSource J2EE webOS
3    * 
4    * Distributable under LGPL license.
5    * See terms of license at gnu.org.
6    */
7   
8   package javax.emb;
9   
10  import java.io.InputStream;
11  import java.net.URL;
12  
13  import javax.ejb.EJBLocalObject;
14  
15  /**
16   * This basic interface extends the {@link javax.emb.Media}interface with
17   * behavior common to all kinds of media objects that are persistent and can be
18   * altered. It also extends <code>EJBLocalObject</code> and therefore
19   * represents the local interface of a media entity EJB.
20   * 
21   * <p>Media Entity EJBs consist of the five basic alterable properties:
22   * 
23   * <ul><li>The content property models the byte content of a media entity
24   * EJB. As such content can become rather large, additional streaming I/O
25   * accessors are provided in addition to the standard set of get/set methods.
26   * The content length of a single media entity EJB is not limited to 2GB; it
27   * can theoretically be up to about 9 hexabytes (2^63) in size. Note that the
28   * presence of the content property does not mean an implementation has to load
29   * the media content into memory; as most implementations will avoid this to
30   * keep memory consumption at bay. Also note that the content property is
31   * correlated to the location property, i.e. the content property cannot be set
32   * if the location property is set and vice versa. The default value for this
33   * property is <code>null</code>.</li>
34   * 
35   * <li>The location property allows a media entity to gain read access to
36   * externally managed content, as opposed to the content property which models
37   * internally managed content. For example, a location URL can point to an HTTP
38   * site that hosts an image. If the location property is set, read access to
39   * the content is possible, but all operations requiring write access to the
40   * content will fail. The location property is correlated to the content
41   * property, i.e. the location property cannot be set if the content property
42   * is set and vice versa. The default value for this property is <code>null</code>.
43   * </li>
44   * 
45   * <li>The description property allows a textual description to be associated
46   * with a media entity EJB, for example to be displayed in conjunction with
47   * some thumbnail in an image list for orientation. The default value for this
48   * property is <code>null</code>.</li>
49   * 
50   * <li>The name property models a file name that is used as a default in case
51   * the content has to be exported to a file. The media format of a media entity
52   * EJB is derived from the file name extension. The default value for this
53   * property is <code>null</code>.</li>
54   * 
55   * <li>The mimeType property is used to hint web application programmers of
56   * which mime type to use when transferring content directly over HTTP. The
57   * default value for this property is <code>null</code>, but unless both the
58   * mimeType and name properties are <code>null</code> the mimeType accessor
59   * will provide a format specific default mime type.</li></ul>
60   * 
61   * @version <tt>$Revision: 1.3 $</tt>
62   * @author <a HREF="mailto:ricardoarguello@users.sourceforge.net">Ricardo
63   *         Arg�ello</a>
64   */
65  public interface MediaEntityLocal extends EJBLocalObject, Media
66  {
67     /**
68      * Adds the given listener to the list of persistent observers that are
69      * notified of important state changes or activities inside the receiver. If
70      * the given listener is already part of the receiver's list of persistent
71      * observers, no action is performed. Note that listeners are distinguished
72      * using checks for content equality, not content identity.
73      * 
74      * @param listener the listener.
75      * @throws java.lang.NullPointerException if the value passed is <code>null</code>.
76      */
77     void addListener(MediaListener listener) throws MediaException;
78  
79     /**
80      * Adds the given metadata to the receiver's list of associated metadata.
81      * Metadata consists of XML content that has been stored in separate
82      * MetaDataEntity EJBs. Several applications can associate XML metadata with
83      * a single media entity. If the given metadata EJB is already part of the
84      * receiver's list of metadata entities, no action is performed.
85      * 
86      * @param metaData metadata.
87      * @throws java.lang.NullPointerException if the value passed is <code>null</code>.
88      */
89     void addMetaData(MetaDataEntityLocal metaData) throws MediaException;
90  
91     /**
92      * This operation updates the receiver's content after performing a series
93      * of transformations on the original content, as defined in the given
94      * specifications array. The order of the specifications array defines the
95      * order of the transformations being performed. This allows modification of
96      * the receiver without transferring the content over machine boundaries.
97      * Note that the receiver's format can change due to this operation, and
98      * that it implicitly updates the receiver's lastModified property. Also
99      * note that this operation will fail if the location property is set.
100     * 
101     * @param specifications array of <code>MediaConverterSpec</code>s.
102     * @throws java.lang.NullPointerException if the value passed is <code>null</code>.
103     * @throws javax.emb.ContentAccessException if the content cannot be
104     *         accessed.
105     * @throws javax.emb.ContentUnmutableException if the <code>location</code>
106     *         property is not <code>null</code>.
107     * @throws javax.emb.MediaFormatException if a problem occurs handling the
108     *         different media formats involved.
109     * @throws javax.emb.ConversionException if one of the conversions fails.
110     * @throws javax.emb.ListenerVetoException if a media listener vetoes the
111     *         change.
112     * @throws javax.emb.ContentTooLargeException if the content generated is
113     *         larger than supported by the implementation.
114     */
115    void convert(MediaConverterSpec[] specifications) throws MediaException;
116 
117    /**
118     * Copies the receiver's content to the given target directory location, a
119     * URL pointing to a directory. If <code>null</code> is passed, the
120     * content is exported to a default directory. The URL must be of protocol
121     * type "file" or any additional protocol supported by the implementation.
122     * In case of non-embedded media formats, the content of related children is
123     * also recursively copied into the same directory or one of its
124     * subdirectories. Implementations must guarantee that no existing files are
125     * overwritten during execution, i.e. they must resolve naming conflicts by
126     * generating file names and adjusting parent content if necessary.
127     * 
128     * <p>The location returned points to the file exported for the receiver,
129     * which is necessary to know in case a directory location was given, or the
130     * location given pointed to an existing file.
131     * 
132     * @param targetDirectoryLocation a URL pointing to a directory. Must be of
133     *        protocol type "file".
134     * @return URL
135     * @throws javax.emb.ContentAccessException if the content cannot be stored
136     *         at the given target location, or if the content transfer fails.
137     * @throws javax.emb.MalformedLocationException if the given target location
138     *         is malformed or the given protocol is not supported.
139     * @throws javax.emb.MediaFormatException is thrown if there is a problem
140     *         dealing with one of the media formats involved.
141     */
142    URL exportMedia(URL targetDirectoryLocation) throws MediaException;
143 
144    /**
145     * Returns the receiver's children as an array of media entities. Children
146     * are media entities being referenced from within the receiver's content,
147     * and the array is therefore guaranteed to be empty in case of embedded
148     * media formats.
149     * 
150     * <p>Note that in case of non-embedded media formats a change of the media
151     * content can implicitly alter the set of children. Also note that altering
152     * the resulting array content will not alter the persisted set of children,
153     * i.e. no persistent relationship collection is exposed. The reason for
154     * this is that the number of children depends on the content.
155     * 
156     * @return the receiver's children as an array of media entities.
157     */
158    MediaEntityLocal[] getChildren() throws MediaException;
159 
160    /**
161     * Returns the receiver's description as a String or <code>null</code>.
162     * The string is not guaranteed to have any structure, and is primarily
163     * designed to allow storing a descriptive label without the need to model
164     * an EJB relation to another entity bean describing the receiver.
165     * 
166     * @return the receiver's description.
167     */
168    String getDescription() throws MediaException;
169 
170    /**
171     * Returns a timestamp stating when the receiver's persistent state was last
172     * modified. Note that relationships are not considered part of the
173     * persistent state and therefore don't affect the value of this property.
174     * 
175     * @return the receiver's persistent state last modification date.
176     */
177    long getLastModified() throws MediaException;
178 
179    /**
180     * Returns an array containing the media listeners associated with the
181     * receiver. If no listeners are associated with the receiver, an empty
182     * array is returned. Note that listeners are distinguished using checks for
183     * content equality, not content identity.
184     * 
185     * @return the persistent listeners observing to the receiver.
186     */
187    MediaListener[] getListeners() throws MediaException;
188 
189    /**
190     * Returns the location of the media content as an instance of
191     * {@link java.net.URL}or <code>null</code> if no location has been set.
192     */
193    URL getLocation() throws MediaException;
194 
195    /**
196     * Returns the receiver's associated metadata as an array of MetaDataEntity
197     * EJBs. Metadata consists of XML content that has been stored in separate
198     * MetaDataEntity EJBs. Several applications can associate their metadata
199     * with a single MetaDataEntity EJB. An empty array is returned if no
200     * metadata has been set.
201     * 
202     * @return metadata
203     */
204    MetaDataEntityLocal[] getMetaData() throws MediaException;
205 
206    /**
207     * Returns the succeeding version of the receiver, which allows querying and
208     * a history chain of media objects that represent the same thing. The value
209     * <code>null</code> is returned if no next version exists.
210     */
211    MediaEntityLocal getNextVersion() throws MediaException;
212 
213    /**
214     * Returns the receiver's parents as an array of media entities. Parents are
215     * media entities that reference the receiver as their child, and the
216     * collection is therefore guaranteed to consist entirely of non-embedded
217     * media entities. Note that changing parents' content can alter a child
218     * media entitie's set of parents implicitly. An empty array is returned if
219     * no parents are available.
220     */
221    MediaEntityLocal[] getParents() throws MediaException;
222 
223    /**
224     * Returns the previous version of the receiver, which allows querying a
225     * history of media objects that represent the same logical thing. The value
226     * <code>null</code> is returned if no previous version exists.
227     * 
228     * @return @throws MediaException
229     */
230    MediaEntityLocal getPreviousVersion() throws MediaException;
231 
232    /**
233     * Alters the content of the receiver with the one read from the given
234     * source location, a URL of type "file" or any other protocol type
235     * supported by the implementation pointing to a piece of content. If the
236     * given name is not <code>null</code>, the name property is also set to
237     * match the given name. It may only contain characters that are valid in
238     * file names. If both the name property and the name given are <code>null</code>
239     * the name property is updated with a generated name, possibly based on the
240     * given source location.
241     * 
242     * <p>In case the media content is non-embedded, the operation recursively
243     * creates media entity EJBs for the children, with their respective names
244     * being derived from the child links within the content. Note that the
245     * operation identifies children that are referenced from multiple parents
246     * in the operation's context and avoids creating multiple media entity EJBs
247     * in this case.
248     * 
249     * <p>Please note that passing a sourceLocation that is equal to the
250     * receiver's current location is allowed and can trigger the recursive
251     * recreation of all children. Additionally the receiver's format can change
252     * due to this operation if the file extension passed with the given name
253     * differs from the one set for the receiver. Also note that this operation
254     * implicitly updates the receiver's lastModified property, and it will fail
255     * if the location property is set.
256     * 
257     * @param sourceLocation
258     * @param name
259     * @throws java.lang.NullPointerException if the value passed is <code>null</code>.
260     * @throws java.lang.IllegalArgumentException if the name argument passed
261     *         contains invalid characters.
262     * @throws javax.emb.ContentAccessException if the content cannot be
263     *         accessed at the given source location, or if the content transfer
264     *         fails.
265     * @throws javax.emb.ContentUnmutableException is thrown if the location
266     *         property is not <code>null</code>.
267     * @throws javax.ejb.CreateException if the creation of a child EJB fails.
268     * @throws javax.emb.MediaFormatException if a format related problem
269     *         occurs.
270     * @throws javax.emb.MalformedLocationException if the given source location
271     *         is malformed.
272     * @throws javax.emb.ListenerVetoException if a media listener vetoes the
273     *         change.
274     * @throws javax.emb.ContentTooLargeException if the content given is larger
275     *         than supported by the implementation.
276     */
277    void importMedia(URL sourceLocation, String name) throws MediaException;
278 
279    /**
280     * Removes the given listener from the list of persistent observers that are
281     * notified of important state changes or activities inside the receiver. If
282     * the listener is not part of the receiver's list of persistent observers,
283     * no action is performed. Note that listeners are distinguished using
284     * checks for content equality, not content identity.
285     * 
286     * @param listener the listener.
287     * @throws java.lang.NullPointerException if the value passed is <code>null</code>.
288     */
289    void removeListener(MediaListener listener) throws MediaException;
290 
291    /**
292     * Removes the given metadata from the receiver's list of associated
293     * metadata. Metadata consists of XML content that has been stored in
294     * MetaDataEntity EJBs. Several applications can associate XML metadata with
295     * a single media entity. If the given metadata EJB is not part of the
296     * receiver's list of metadata entities, no action is performed.
297     * 
298     * <p>Note that this operation will not remove the MetaDataEntity EJB from
299     * the persistent store, but rather disassociate the metadata from the Media
300     * Entity on which the method was invoked.
301     * 
302     * @param metaData metadata
303     * @throws java.lang.NullPointerException if the value passed is <code>null</code>.
304     */
305    void removeMetaData(MetaDataEntityLocal metaData) throws MediaException;
306 
307    /**
308     * This operation sets the children of the receiver to an array of media
309     * entity EJBs. Note that the number of children passed must match the
310     * number of existing children. Also note that this operation is only
311     * allowed if the content property is set because it might require updating
312     * said content.
313     * 
314     * @param children children
315     * @throws java.lang.NullPointerException if the value passed or one of its
316     *         elements is <code>null</code>.
317     * @throws java.lang.IllegalArgumentException if the value passed has more
318     *         or fewer elements than the receiver's existing number of
319     *         children.
320     * @throws javax.emb.ContentUnmutableException if the <code>location</code>
321     *         property is set.
322     * @throws javax.emb.ContentAccessException if the <code>content</code>
323     *         has not been set.
324     */
325    void setChildren(MediaEntityLocal[] children) throws MediaException;
326 
327    /**
328     * This operation offers a convenient way to alter the content of the
329     * receiver for small and embedded media content. In case the content is
330     * non-embedded, the <code>importMedia(URL, String)</code> operation
331     * should be used instead, as this method only modifies the receiver's
332     * content and no child content is affected. The same is true if the content
333     * is rather large.
334     * 
335     * <p>If both the value passed and the receiver's existing content property
336     * are not <code>null</code>, no format change may occur during this
337     * operation. If the location property is not <code>null</code> then this
338     * operation is not permitted. Note that the location property may not be
339     * set while the content property contains a value different from <code>null</code>.
340     * Note that this operation implicitly updates the receive's <code>lastModified</code>
341     * property. Also note that this operation will fail if the <code>location</code>
342     * property is set.
343     * 
344     * @param content content.
345     * @throws javax.emb.ContentAccessException if content transfer fails.
346     * @throws javax.emb.FormatNotFoundException if the name property is <code>null</code>.
347     * @throws javax.emb.FormatSyntaxException if the system notices a format
348     *         change.
349     * @throws javax.emb.ContentUnmutableException if the location property is
350     *         not <code>null</code>.
351     * @throws javax.emb.ContentTooLargeException if the content given is larger
352     *         than supported by the implementation.
353     */
354    void setContent(byte[] content) throws MediaException;
355 
356    /**
357     * This operation offers a convenient way to alter the content of the
358     * receiver for all kinds of embedded media formats. If the content is
359     * non-embedded, the <code>importMedia(URL, String)</code> operation
360     * should be used instead, as this method only modifies the receiver's
361     * content and no child content is affected. The same is true if the content
362     * is rather large.
363     * 
364     * <p>If both the value passed and the receiver's existing content property
365     * are not <code>null</code>, no format change may occur during this
366     * operation. If the location property is not <code>null</code>, this
367     * operation is not permitted. The location property may not be set while
368     * the content property contains a value different from <code>null</code>.
369     * Note that this operation implicitly updates the receiver's lastModified
370     * property. Also note that this operation will fail if the <code>location</code>
371     * property is set.
372     * 
373     * @param content content.
374     * @throws java.lang.NullPointerException if the value passed is <code>null</code>.
375     * @throws javax.emb.ContentAccessException if content transfer fails.
376     * @throws javax.emb.FormatNotFoundException if the name property is <code>null</code>.
377     * @throws javax.emb.FormatSyntaxException if the system notices a format
378     *         change.
379     * @throws javax.emb.ContentUnmutableException if the location property is
380     *         not <code>null</code>.
381     * @throws javax.emb.ListenerVetoException if a media listener vetoes the
382     *         change.
383     * @throws javax.emb.ContentTooLargeException if the content given is larger
384     *         than supported by the implementation.
385     */
386    void setContent(InputStream content) throws MediaException;
387 
388    /**
389     * Alters the receiver's description. The description string is primarily
390     * designed to allow storing a descriptive label without the need to model
391     * an EJB relation to another entity bean describing the receiver. Passing
392     * <code>null</code> causes the description field to be reset to <code>null</code>.
393     * Note that this operation implicitly updates the receiver's <code>lastModified</code>
394     * property.
395     * 
396     * @param description description.
397     * @throws javax.emb.ListenerVetoException if a media listener vetoes the
398     *         change.
399     */
400    void setDescription(String description) throws MediaException;
401 
402    /**
403     * Sets the location of the receiver to the given location URL or <code>null</code>.
404     * The purpose of this method is to provide a mechanism for read access to
405     * externally managed content. For example, content that is hosted by an
406     * external content provider.
407     * 
408     * <p>Note that if the content property is not <code>null</code>, this
409     * operation is not permitted. Note that the content property may not be set
410     * while the <code>location</code> property contains a value different
411     * from <code>null</code>. Also note that this operation implicitly
412     * updates the receiver's <code>lastModified</code> property.
413     * 
414     * @param location location URL.
415     * @throws javax.emb.ContentAccessException if the media content cannot be
416     *         accessed under the new location, or if the given location URL
417     *         points to a directory.
418     * @throws javax.emb.LocationUnmutableException if the content property is
419     *         not <code>null</code>.
420     * @throws javax.emb.ListenerVetoException if a media listener vetoes the
421     *         change.
422     */
423    void setLocation(URL location) throws MediaException;
424 
425    /**
426     * Alters the receiver's MIME type that allows media content to be written
427     * directly to a Servlet output stream. Note that this operation implicitly
428     * updates the receiver's <code>lastModified</code> property. Note that
429     * passing <code>null</code> will cause the <code>getMimeType()</code>
430     * method to return a format specific default. Also note that this operation
431     * implicitly updates the receiver's <code>lastModified</code> property.
432     * 
433     * @param mimeType MIME type.
434     * @throws javax.emb.ListenerVetoException if a media listener vetoes the
435     *         change.
436     */
437    void setMimeType(String mimeType) throws MediaException;
438 
439    /**
440     * Sets the receiver's non-unique name as a <code>String</code>. The name
441     * is used as a file name hint in case the media content is to be stored or
442     * published in a file system and therefore may only contain characters that
443     * are valid in file names. Also, it must contain a file extension that
444     * represents the receiver's media format. Note that this operation
445     * implicitly updates the receiver's <code>lastModified</code> property.
446     * 
447     * @param name name.
448     * @throws java.lang.NullPointerException if the value passed is <code>null</code>.
449     * @throws java.lang.IllegalArgumentException if the name argument passed
450     *         contains invalid characters.
451     * @throws javax.emb.FormatNotFoundException if the format cannot be
452     *         determined from the file extension.
453     * @throws javax.emb.ListenerVetoException is thrown if a media listener
454     *         vetoes the change.
455     */
456    void setName(String name) throws MediaException;
457 
458    /**
459     * Defines the given media entity to be the preceding version of the
460     * receiver, which allows querying a history chain of media objects that
461     * represent the same logical thing. In return, the operation causes the
462     * receiver to be the given media entity's next version. Passing the value
463     * <code>null</code> causes the receiver not to have a previous version
464     * anymore. The operation is only allowed if version chain integrity is
465     * preserved:
466     * 
467     * <ul><li>If the given media entity is the receiver itself: A
468     * javax.emb.VersionChainIntegrityException is thrown.</li>
469     * 
470     * <li>If the given media entity is already the previous version of the
471     * receiver: No action is performed.</li>
472     * 
473     * <li>If the given media entity is <code>null</code>: A
474     * javax.emb.VersionChainIntegrityException is thrown if the receiver has a
475     * successor.</li>
476     * 
477     * <li>Otherwise: A javax.emb.VersionChainIntegrityException is thrown if
478     * the given media entity has a successor, or if the receiver has a
479     * predecessor, a successor, or both.</li></ul>
480     *  
481     */
482    void setPreviousVersion(MediaEntityLocal mediaEntity) throws MediaException;
483 
484    /**
485     * Sets the given media entity as the receiver's persistent proxy, e.g. a
486     * thumbnail, an icon, a short video or audio clip of any format. Proxies
487     * represent media objects to give people interested an up front impression
488     * of the latter. If there is already a proxy relation for the receiver, the
489     * old relation is discarded and the old persistent proxy is not deleted. In
490     * case <code>null</code> is passed, the relation to any existing
491     * persistent proxy is broken up and <code>getProxy()</code> will return a
492     * generated transient proxy.
493     * 
494     * @param mediaEntity media entity.
495     */
496    void setProxy(MediaEntityLocal mediaEntity) throws MediaException;
497 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Java Books Remove Frame
Popular Tags