KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > emb > 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 }
Popular Tags