javax.emb
Interface MediaEntityLocal

All Superinterfaces:

EJBLocalObject (src) , Media (src) , java.io.Serializable

public interface MediaEntityLocal

extends EJBLocalObject (src) , Media (src)

This basic interface extends the Media (src) interface with behavior common to all kinds of media objects that are persistent and can be altered. It also extends EJBLocalObject and therefore represents the local interface of a media entity EJB.

Media Entity EJBs consist of the five basic alterable properties:

• The content property models the byte content of a media entity EJB. As such content can become rather large, additional streaming I/O accessors are provided in addition to the standard set of get/set methods. The content length of a single media entity EJB is not limited to 2GB; it can theoretically be up to about 9 hexabytes (2^63) in size. Note that the presence of the content property does not mean an implementation has to load the media content into memory; as most implementations will avoid this to keep memory consumption at bay. Also note that the content property is correlated to the location property, i.e. the content property cannot be set if the location property is set and vice versa. The default value for this property is null.
• The location property allows a media entity to gain read access to externally managed content, as opposed to the content property which models internally managed content. For example, a location URL can point to an HTTP site that hosts an image. If the location property is set, read access to the content is possible, but all operations requiring write access to the content will fail. The location property is correlated to the content property, i.e. the location property cannot be set if the content property is set and vice versa. The default value for this property is null.
• The description property allows a textual description to be associated with a media entity EJB, for example to be displayed in conjunction with some thumbnail in an image list for orientation. The default value for this property is null.
• The name property models a file name that is used as a default in case the content has to be exported to a file. The media format of a media entity EJB is derived from the file name extension. The default value for this property is null.
• The mimeType property is used to hint web application programmers of which mime type to use when transferring content directly over HTTP. The default value for this property is null, but unless both the mimeType and name properties are null the mimeType accessor will provide a format specific default mime type.

addListener

public void addListener(MediaListener (src)  listener)
                 throws MediaException (src) 

Adds the given listener to the list of persistent observers that are notified of important state changes or activities inside the receiver. If the given listener is already part of the receiver's list of persistent observers, no action is performed. Note that listeners are distinguished using checks for content equality, not content identity.

Parameters:

listener - the listener.

Throws:

java.lang.NullPointerException - if the value passed is null.

MediaException (src)

addMetaData

public void addMetaData(MetaDataEntityLocal (src)  metaData)
                 throws MediaException (src) 

Adds the given metadata to the receiver's list of associated metadata. Metadata consists of XML content that has been stored in separate MetaDataEntity EJBs. Several applications can associate XML metadata with a single media entity. If the given metadata EJB is already part of the receiver's list of metadata entities, no action is performed.

Parameters:

metaData - metadata.

Throws:

java.lang.NullPointerException - if the value passed is null.

MediaException (src)

convert

public void convert(MediaConverterSpec (src) [] specifications)
             throws MediaException (src) 

This operation updates the receiver's content after performing a series of transformations on the original content, as defined in the given specifications array. The order of the specifications array defines the order of the transformations being performed. This allows modification of the receiver without transferring the content over machine boundaries. Note that the receiver's format can change due to this operation, and that it implicitly updates the receiver's lastModified property. Also note that this operation will fail if the location property is set.

Parameters:

specifications - array of MediaConverterSpecs.

Throws:

java.lang.NullPointerException - if the value passed is null.

ContentAccessException (src) - if the content cannot be accessed.

ContentUnmutableException (src) - if the location property is not null.

MediaFormatException (src) - if a problem occurs handling the different media formats involved.

ConversionException (src) - if one of the conversions fails.

ListenerVetoException (src) - if a media listener vetoes the change.

ContentTooLargeException (src) - if the content generated is larger than supported by the implementation.

MediaException (src)

exportMedia

public java.net.URL exportMedia(java.net.URL targetDirectoryLocation)
                         throws MediaException (src) 

Copies the receiver's content to the given target directory location, a URL pointing to a directory. If null is passed, the content is exported to a default directory. The URL must be of protocol type "file" or any additional protocol supported by the implementation. In case of non-embedded media formats, the content of related children is also recursively copied into the same directory or one of its subdirectories. Implementations must guarantee that no existing files are overwritten during execution, i.e. they must resolve naming conflicts by generating file names and adjusting parent content if necessary.

The location returned points to the file exported for the receiver, which is necessary to know in case a directory location was given, or the location given pointed to an existing file.

Parameters:

targetDirectoryLocation - a URL pointing to a directory. Must be of protocol type "file".

Returns:

URL

Throws:

ContentAccessException (src) - if the content cannot be stored at the given target location, or if the content transfer fails.

MalformedLocationException (src) - if the given target location is malformed or the given protocol is not supported.

MediaFormatException (src) - is thrown if there is a problem dealing with one of the media formats involved.

MediaException (src)

getChildren

public MediaEntityLocal (src) [] getChildren()
                               throws MediaException (src) 

Returns the receiver's children as an array of media entities. Children are media entities being referenced from within the receiver's content, and the array is therefore guaranteed to be empty in case of embedded media formats.

Note that in case of non-embedded media formats a change of the media content can implicitly alter the set of children. Also note that altering the resulting array content will not alter the persisted set of children, i.e. no persistent relationship collection is exposed. The reason for this is that the number of children depends on the content.

Returns:

the receiver's children as an array of media entities.

Throws:

MediaException (src)

getDescription

public java.lang.String getDescription()
                                throws MediaException (src) 

Returns the receiver's description as a String or null. The string is not guaranteed to have any structure, and is primarily designed to allow storing a descriptive label without the need to model an EJB relation to another entity bean describing the receiver.

Returns:

the receiver's description.

Throws:

MediaException (src)

getLastModified

public long getLastModified()
                     throws MediaException (src) 

Returns a timestamp stating when the receiver's persistent state was last modified. Note that relationships are not considered part of the persistent state and therefore don't affect the value of this property.

Returns:

the receiver's persistent state last modification date.

Throws:

MediaException (src)

getListeners

public MediaListener (src) [] getListeners()
                             throws MediaException (src) 

Returns an array containing the media listeners associated with the receiver. If no listeners are associated with the receiver, an empty array is returned. Note that listeners are distinguished using checks for content equality, not content identity.

Returns:

the persistent listeners observing to the receiver.

Throws:

MediaException (src)

getLocation

public java.net.URL getLocation()
                         throws MediaException (src) 

Returns the location of the media content as an instance of URLor null if no location has been set.

Throws:

MediaException (src)

getMetaData

public MetaDataEntityLocal (src) [] getMetaData()
                                  throws MediaException (src) 

Returns the receiver's associated metadata as an array of MetaDataEntity EJBs. Metadata consists of XML content that has been stored in separate MetaDataEntity EJBs. Several applications can associate their metadata with a single MetaDataEntity EJB. An empty array is returned if no metadata has been set.

Returns:

metadata

Throws:

MediaException (src)

getNextVersion

public MediaEntityLocal (src)  getNextVersion()
                                throws MediaException (src) 

Returns the succeeding version of the receiver, which allows querying and a history chain of media objects that represent the same thing. The value null is returned if no next version exists.

Throws:

MediaException (src)

getParents

public MediaEntityLocal (src) [] getParents()
                              throws MediaException (src) 

Returns the receiver's parents as an array of media entities. Parents are media entities that reference the receiver as their child, and the collection is therefore guaranteed to consist entirely of non-embedded media entities. Note that changing parents' content can alter a child media entitie's set of parents implicitly. An empty array is returned if no parents are available.

Throws:

MediaException (src)

getPreviousVersion

public MediaEntityLocal (src)  getPreviousVersion()
                                    throws MediaException (src) 

Returns the previous version of the receiver, which allows querying a history of media objects that represent the same logical thing. The value null is returned if no previous version exists.

Returns:

@throws MediaException

Throws:

MediaException (src)

importMedia

public void importMedia(java.net.URL sourceLocation,
                        java.lang.String name)
                 throws MediaException (src) 

Alters the content of the receiver with the one read from the given source location, a URL of type "file" or any other protocol type supported by the implementation pointing to a piece of content. If the given name is not null, the name property is also set to match the given name. It may only contain characters that are valid in file names. If both the name property and the name given are null the name property is updated with a generated name, possibly based on the given source location.

In case the media content is non-embedded, the operation recursively creates media entity EJBs for the children, with their respective names being derived from the child links within the content. Note that the operation identifies children that are referenced from multiple parents in the operation's context and avoids creating multiple media entity EJBs in this case.

Please note that passing a sourceLocation that is equal to the receiver's current location is allowed and can trigger the recursive recreation of all children. Additionally the receiver's format can change due to this operation if the file extension passed with the given name differs from the one set for the receiver. Also note that this operation implicitly updates the receiver's lastModified property, and it will fail if the location property is set.

Parameters:

sourceLocation -

name -

Throws:

java.lang.NullPointerException - if the value passed is null.

java.lang.IllegalArgumentException - if the name argument passed contains invalid characters.

ContentAccessException (src) - if the content cannot be accessed at the given source location, or if the content transfer fails.

ContentUnmutableException (src) - is thrown if the location property is not null.

CreateException (src) - if the creation of a child EJB fails.

MediaFormatException (src) - if a format related problem occurs.

MalformedLocationException (src) - if the given source location is malformed.

ListenerVetoException (src) - if a media listener vetoes the change.

ContentTooLargeException (src) - if the content given is larger than supported by the implementation.

MediaException (src)

removeListener

public void removeListener(MediaListener (src)  listener)
                    throws MediaException (src) 

Removes the given listener from the list of persistent observers that are notified of important state changes or activities inside the receiver. If the listener is not part of the receiver's list of persistent observers, no action is performed. Note that listeners are distinguished using checks for content equality, not content identity.

Parameters:

listener - the listener.

Throws:

java.lang.NullPointerException - if the value passed is null.

MediaException (src)

removeMetaData

public void removeMetaData(MetaDataEntityLocal (src)  metaData)
                    throws MediaException (src) 

Removes the given metadata from the receiver's list of associated metadata. Metadata consists of XML content that has been stored in MetaDataEntity EJBs. Several applications can associate XML metadata with a single media entity. If the given metadata EJB is not part of the receiver's list of metadata entities, no action is performed.

Note that this operation will not remove the MetaDataEntity EJB from the persistent store, but rather disassociate the metadata from the Media Entity on which the method was invoked.

Parameters:

metaData - metadata

Throws:

java.lang.NullPointerException - if the value passed is null.

MediaException (src)

setChildren

public void setChildren(MediaEntityLocal (src) [] children)
                 throws MediaException (src) 

This operation sets the children of the receiver to an array of media entity EJBs. Note that the number of children passed must match the number of existing children. Also note that this operation is only allowed if the content property is set because it might require updating said content.

Parameters:

children - children

Throws:

java.lang.NullPointerException - if the value passed or one of its elements is null.

java.lang.IllegalArgumentException - if the value passed has more or fewer elements than the receiver's existing number of children.

ContentUnmutableException (src) - if the location property is set.

ContentAccessException (src) - if the content has not been set.

MediaException (src)

setContent

public void setContent(byte[] content)
                throws MediaException (src) 

This operation offers a convenient way to alter the content of the receiver for small and embedded media content. In case the content is non-embedded, the importMedia(URL, String) operation should be used instead, as this method only modifies the receiver's content and no child content is affected. The same is true if the content is rather large.

If both the value passed and the receiver's existing content property are not null, no format change may occur during this operation. If the location property is not null then this operation is not permitted. Note that the location property may not be set while the content property contains a value different from null. Note that this operation implicitly updates the receive's lastModified property. Also note that this operation will fail if the location property is set.

Parameters:

content - content.

Throws:

ContentAccessException (src) - if content transfer fails.

FormatNotFoundException (src) - if the name property is null.

FormatSyntaxException (src) - if the system notices a format change.

ContentUnmutableException (src) - if the location property is not null.

ContentTooLargeException (src) - if the content given is larger than supported by the implementation.

MediaException (src)

setContent

public void setContent(java.io.InputStream content)
                throws MediaException (src) 

This operation offers a convenient way to alter the content of the receiver for all kinds of embedded media formats. If the content is non-embedded, the importMedia(URL, String) operation should be used instead, as this method only modifies the receiver's content and no child content is affected. The same is true if the content is rather large.

If both the value passed and the receiver's existing content property are not null, no format change may occur during this operation. If the location property is not null, this operation is not permitted. The location property may not be set while the content property contains a value different from null. Note that this operation implicitly updates the receiver's lastModified property. Also note that this operation will fail if the location property is set.

Parameters:

content - content.

Throws:

java.lang.NullPointerException - if the value passed is null.

ContentAccessException (src) - if content transfer fails.

FormatNotFoundException (src) - if the name property is null.

FormatSyntaxException (src) - if the system notices a format change.

ContentUnmutableException (src) - if the location property is not null.

ListenerVetoException (src) - if a media listener vetoes the change.

ContentTooLargeException (src) - if the content given is larger than supported by the implementation.

MediaException (src)

setDescription

public void setDescription(java.lang.String description)
                    throws MediaException (src) 

Alters the receiver's description. The description string is primarily designed to allow storing a descriptive label without the need to model an EJB relation to another entity bean describing the receiver. Passing null causes the description field to be reset to null. Note that this operation implicitly updates the receiver's lastModified property.

Parameters:

description - description.

Throws:

ListenerVetoException (src) - if a media listener vetoes the change.

MediaException (src)

setLocation

public void setLocation(java.net.URL location)
                 throws MediaException (src) 

Sets the location of the receiver to the given location URL or null. The purpose of this method is to provide a mechanism for read access to externally managed content. For example, content that is hosted by an external content provider.

Note that if the content property is not null, this operation is not permitted. Note that the content property may not be set while the location property contains a value different from null. Also note that this operation implicitly updates the receiver's lastModified property.

Parameters:

location - location URL.

Throws:

ContentAccessException (src) - if the media content cannot be accessed under the new location, or if the given location URL points to a directory.

LocationUnmutableException (src) - if the content property is not null.

ListenerVetoException (src) - if a media listener vetoes the change.

MediaException (src)

setMimeType

public void setMimeType(java.lang.String mimeType)
                 throws MediaException (src) 

Alters the receiver's MIME type that allows media content to be written directly to a Servlet output stream. Note that this operation implicitly updates the receiver's lastModified property. Note that passing null will cause the getMimeType() method to return a format specific default. Also note that this operation implicitly updates the receiver's lastModified property.

Parameters:

mimeType - MIME type.

Throws:

ListenerVetoException (src) - if a media listener vetoes the change.

MediaException (src)

setName

public void setName(java.lang.String name)
             throws MediaException (src) 

Sets the receiver's non-unique name as a String. The name is used as a file name hint in case the media content is to be stored or published in a file system and therefore may only contain characters that are valid in file names. Also, it must contain a file extension that represents the receiver's media format. Note that this operation implicitly updates the receiver's lastModified property.

Parameters:

name - name.

Throws:

java.lang.NullPointerException - if the value passed is null.

java.lang.IllegalArgumentException - if the name argument passed contains invalid characters.

FormatNotFoundException (src) - if the format cannot be determined from the file extension.

ListenerVetoException (src) - is thrown if a media listener vetoes the change.

MediaException (src)

setPreviousVersion

public void setPreviousVersion(MediaEntityLocal (src)  mediaEntity)
                        throws MediaException (src) 

Defines the given media entity to be the preceding version of the receiver, which allows querying a history chain of media objects that represent the same logical thing. In return, the operation causes the receiver to be the given media entity's next version. Passing the value null causes the receiver not to have a previous version anymore. The operation is only allowed if version chain integrity is preserved:

• If the given media entity is the receiver itself: A javax.emb.VersionChainIntegrityException is thrown.
• If the given media entity is already the previous version of the receiver: No action is performed.
• If the given media entity is null: A javax.emb.VersionChainIntegrityException is thrown if the receiver has a successor.
• Otherwise: A javax.emb.VersionChainIntegrityException is thrown if the given media entity has a successor, or if the receiver has a predecessor, a successor, or both.

Throws:

MediaException (src)

setProxy

public void setProxy(MediaEntityLocal (src)  mediaEntity)
              throws MediaException (src) 

Sets the given media entity as the receiver's persistent proxy, e.g. a thumbnail, an icon, a short video or audio clip of any format. Proxies represent media objects to give people interested an up front impression of the latter. If there is already a proxy relation for the receiver, the old relation is discarded and the old persistent proxy is not deleted. In case null is passed, the relation to any existing persistent proxy is broken up and getProxy() will return a generated transient proxy.

Parameters:

mediaEntity - media entity.

Throws:

MediaException (src)