javax.emb
Interface MediaEntityLocalHome

All Superinterfaces:

EJBLocalHome (src)

public interface MediaEntityLocalHome

extends EJBLocalHome (src)

This interface defines the local home interface of media entity EJBs and offers services to create and to query persistent and mutable media objects. It extends javax.ejb.EJBLocalHome.

The create method provided allows the creation of empty media entity EJBs. These instances need to be filled with content in a subsequent step, by using the setName() and setContent() methods.

Sometimes networks of associated non-embedded media content can become quite complex. In order to allow the consistent handling of such complex content structures the importMedia() and exportMedia() operations allows for consistent import, creation and export or content if for example many non-embedded parents share identical children. Using the related methods in the media entity EJB component interfaces would lead to multiple versions of the shared children being imported/exported.

Finally, the publishContent() and publishMedia() operations publish a transient or persistent media object to a protocol server, and returns a URL or content that allows clients to access the protocol and server specific copies of said medium and its children. This abstraction allows applications to access proprietary content delivery services, without exposing the application to the details of the implementation of those services. For example, multiple and distributed streaming server technologies can be used underneath a publish implementation. Implementations of this specification are not bound to a specific algorithm to determine a suitable protocol server. Theoretical possibilities range from dynamic selection from a pre-configured server pool to relating suitable protocol servers statically with each media entity. The resulting URL/content is either pointing directly to the cached copy of the media object with a protocol type of http, rtsp or similar, or it is an http URL pointing to a managed meta-medium that points to said cached copy.

TRANSFER_TYPE_STREAM

public static final byte TRANSFER_TYPE_STREAM

See Also:

Constant Field Values (src)

TRANSFER_TYPE_BURST

public static final byte TRANSFER_TYPE_BURST

See Also:

Constant Field Values (src)

create

public MediaEntityLocal (src)  create()
                        throws CreateException (src) ,
                               MediaException (src) 

Creates a new media entity EJB with a generated identity key, the value of System.currentTimeMillis() as value of the lastModified property, and null as value for all other properties. Please note most of the methods of the Media Entity returned will throw exceptions until the name and either the location or the content properties are set.

Returns:

media entity bean.

Throws:

CreateException (src) - is thrown if a problem related to EJB creation occurs.

MediaException (src)

exportMedia

public java.net.URL[] exportMedia(MediaEntityLocal (src) [] sourceMedia,
                                  java.net.URL targetDirectoryLocation)
                           throws MediaException (src) 

Copies the content of the given media entity EJBs and all their direct and indirect children to the given targetDirectoryLocation, i.e. a URL of protocol type "file" or any other type supported by the implementation. The operation returns an array of URLs of the same size as the source media array. The elements of the resulting array point to file copies of the source media array elements' content. If the media objects affected are non-embedded, the content of the copies is modified to correctly point to the copies of the children's content instead of the original locations.

If the given targetDirectoryLocation is null, a default export directory location is used. The operation makes sure that each media entity EJB affected corresponds to exactly one media object created. Note that the names of the copied media objects may differ from the original ones, that the operation makes sure no existing files are overwritten by this operation, and that implementations are permitted to copy children to subdirectories of the given targetDirectoryLocation. Also note that the resulting targetLocation URLs are returned in the order of their respective media entity EJBs. Duplicate media entity EJBs result in targetLocation URLs returned in multiple array slots, null media entity EJBs result in respective null values in the result. Finally, note that not all media objects exported are necessarily returned, just the ones for which corresponding media entity EJBs were passed.

Parameters:

sourceMedia -

targetDirectoryLocation -

Returns:

URLs array

Throws:

java.lang.NullPointerException - if the given source media array is null.

ContentAccessException (src) - in case content transfer fails.

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

MalformedLocationException (src) - if the URL given is malformed or has a protocol type not supported by the implementation.

MediaException (src)

findByPartialDescription

public java.util.Collection findByPartialDescription(java.lang.String partialDescription)
                                              throws FinderException (src) 

Returns all media entities in the persistent store whose description contains the given String. The query is case-sensitive. Note that passing an empty string will return all media entity beans in the persistent store that have a description different from null. Passing in null or a partial description not present in the data store will result in an empty collection.

Parameters:

partialDescription - description.

Returns:

all media entities whose description contains the given String.

Throws:

FinderException (src) - if a finder problem occurs.

findByPartialLocation

public java.util.Collection findByPartialLocation(java.lang.String partialLocation)
                                           throws FinderException (src) 

Returns all media entities in the persistent store whose location URL contains the given String. The query is case-sensitive. Note that passing an empty string will return all media entity beans in the persistent store that have a location different from null. Passing in null or a partial location not present in the data store will result in an empty collection.

Parameters:

partialLocation - location.

Returns:

all media entities in the persistent store whose location URL contains the given String.

Throws:

FinderException (src) - if a finder problem occurs.

findByPrimaryKey

public MediaEntityLocal (src)  findByPrimaryKey(java.lang.String identity)
                                  throws FinderException (src) 

Returns the media entity with the given identity.

Parameters:

identity - identity.

Throws:

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

FinderException (src) - if a finder problem occurs or no media entity is found.

importMedia

public MediaEntityLocal (src) [] importMedia(java.net.URL[] sourceLocations,
                                      java.lang.String[] names)
                               throws CreateException (src) ,
                                      MediaException (src) 

Imports the given media objects and all their direct and indirect children from the given source locations and creates new EJBs for said media objects and children. For the media entity EJBs directly created from the source locations given, the names are derived from the given name array at equivalent indices. If a name value is null a generated name is used, possibly based on the related source location. For all other media entity EJBs created, the name properties are derived from the links present in their respective parent content.

The operation returns an array of media entity EJBs of the same size as the source location array. The elements of the resulting array are based on the content of the corresponding elements of the source location array.

The operation makes sure that each media object affected corresponds to exactly one media entity EJB created in the operations context. Note that the resulting Media ent ity EJBs are returned in the order of their respective sourceLocations. Duplicate sourceLocations result in media entity EJBs returned in multiple array slots, null sourceLocations result in respective null values in the result. If a source location is given multiple times with differing names, one of the names is picked for the resulting media entity EJB. Finally, note that not all media entity EJBs created are necessarily returned, just the ones for which corresponding location URLs were passed.

Parameters:

sourceLocations - source locations.

names - names.

Returns:

@throws java.lang.NullPointerException if one of the arrays passed is null.

Throws:

java.lang.IllegalArgumentException - if the two arrays passed mismatch in length or if one or more of the name arguments passed contain invalid characters.

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

ContentAccessException (src) - if content transfer fails.

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

MalformedLocationException (src) - if one of the URLs given is malformed or has a protocol type not supported by the implementation.

ContentTooLargeException (src) - if one the media entity EJB contents would become larger than supported by the implementation.

MediaException (src)

publishContent

public java.net.URL publishContent(Media (src)  content,
                                   byte transferType,
                                   ProtocolConstraints (src)  constraints)
                            throws MediaException (src) 

This operation publishes persistent or transient media content to a protocol server and returns a URL. The URL allows web clients to access the protocol and server specific copies of said medium. Note that it also exports its children if a non-embedded media entity EJB is passed. If the medium is persistent (i.e. is a media entity EJB), said copies will likely be managed and updated once the original content changes. Optionally, the selection of a suitable protocol server can be influenced using the given constraints object. Implementations of this specification are not bound to a specific algorithm to determine a suitable protocol server. Theoretical possibilities range from dynamic selection from a pre-configured server pool to relating suitable protocol servers statically with each media entity. The resulting URL is either pointing directly to the cached copy of the media object with a protocol type of http, rtsp or similar, or it is an http URL pointing to a managed meta-medium that points to said cached copy.

The kind of protocol server chosen may be determined by the given transferType. Specified values are:

• TRANSFER_TYPE_STREAM for streaming of media content, using a stream server as protocol server.
• TRANSFER_TYPE_BURST for burst transfer of media content, usually using a web server as protocol server.

Specified protocol constraint types are:

• "SERVER_TYPE" for restriction of stream servers to chose from. The constraint value is an array of Strings. Specified constraint values are "VideoCharger" for IBM VideoCharger servers, "RealSystem" for RealNetworks RealSystem servers, and "Windows Media" for Microsoft Windows Media services, and "QuickTime" for Apple QuickTime servers. The protocol server selected will be of one of these types. Note that some server types can feed a number of different clients.
• "CLIENT_TYPE" for restriction of stream servers to chose from. The constraint value is an array of Strings. Specified constraint values are "VideoCharger" for IBM VideoCharger players, "RealPlayer" for RealNetworks players, and "Windows Media" for Microsoft Windows Media players, and "QuickTime" for Apple QuickTime players. The protocol server selected will support one of these client types. Note that some players can work with a number of protocol servers.

In case the selected protocol server supports more than one client type, the client type is not constrained and a meta-medium has to be generated, said meta-medium is generated for the default client type of the selected protocol server. If in a similar case there is more than one constraint value for the client type, the constraint value is interpreted as a priority list and therefore the meta-medium is generated for the first client type in that list that is supported by the selected protocol server.

Parameters:

content - content.

transferType - transfer type.

constraints - constraints.

Returns:

URL

Throws:

java.lang.NullPointerException - if the media object passed is null.

java.lang.IllegalArgumentException - if a transfer type is passed that is not supported by the implementation, or if a protocol type SERVER_TYPE or CLIENT_TYPE is passed with a value that is not an array of Strings.

NoServerFoundException (src) - if no suitable protocol server can be determined.

ContentAccessException (src) - if content transfer fails or if non-embedded content is passed in anything other than a media entity EJB.

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

LinkTranslationException (src) - if ingesting protocol specific links into copies of non-embedded media objects fails.

ConversionException (src) - if the middleware fails converting the media content to another format in order to make it suitable for a specific protocol server.

MediaException (src)

publishMedia

public Media (src)  publishMedia(MediaEntityLocal (src) [] playlist,
                          byte transferType,
                          ProtocolConstraints (src)  constraints)
                   throws MediaException (src) 

This operation publishes the given playlist of persistent media entities to a protocol server and returns a meta medium that allows clients to access the protocol and server specific copies of said playlist and its children. If the implementation chooses to cache the media objects on the protocol server chosen, it must be guaranteed that eventual child copies are also managed and will be updated if the original content changes.

Optionally, the selection of a suitable protocol server can be influenced using the given constraints object. Implementations of this specification are not bound to a specific algorithm to determine a suitable protocol server. Theoretical possibilities range from dynamic selection from a pre-configured server pool to relating suitable protocol servers statically with each media entity. The content of the resulting meta medium is pointing directly to the cached copies of the given media entities with a protocol type of http, rtsp or similar.

The kind of protocol server chosen may be determined by the given transferType. Specified values are: TRANSFER_TYPE_STREAM for streaming of media content, using a stream server as protocol server.

TRANSFER_TYPE_BURST for burst transfer of media content, usually using a web server as protocol server.

Specified protocol constraint types are:

• "SERVER_TYPE" for restriction of stream servers to chose from. The constraint value is an array of Strings. Specified constraint values are "VideoCharger" for IBM VideoCharger servers, "RealSystem" for RealNetworks servers, and "Windows Media" for Microsoft Media services, and "QuickTime" for Apple QuickTime servers. The protocol server selected will be of one of these types. Note that some server types can feed a number of different clients.
• "CLIENT_TYPE" for restriction of stream servers to chose from. The constraint value is an array of Strings. Specified constraint values are "VideoCharger" for IBM VideoCharger players, "RealPlayer" for RealNetworks players, and "Windows Media" for Microsoft Windows Media players, and "QuickTime" for Apple QuickTime players. The protocol server selected will support one of these client types. Note that some players can work with a number of protocol servers.

If the selected protocol server supports more than one client type and the client type is not constrained, a meta-medium is generated for the default client type of the selected protocol server. If in a similar case there is more than one constraint value for the client type, the constraint value is interpreted as a priority list and therefore the meta-medium is generated for the first client type in that list that is supported by the selected protocol server.

Both the format and the content of the resulting meta-medium are considered proprietary to an implementation of this specification. Suitable are streaming metafile formats like Real .ram or IBM .ivs for streaming, or HTML files - containing auto load links for playlists consisting of exactly one entry, or clickable links for playlists consisting of two or more entries - for burst transfer. However, a Servlet must be able to return the resulting meta-medium directly to its requesting client to cause a media player to render the playlist on said client.

In contrast, publishing the same playlist for the HTML protocol would have resulted in an html meta media containing HREF links to the SMIL presentation and the MPEG movie. Also, the cache copy of the SMIL presentation would contain HTML references to its child media in this case.

Parameters:

playlist -

transferType -

constraints -

Returns:

@throws java.lang.NullPointerException if the playlist passed is null.

Throws:

java.lang.IllegalArgumentException - if a transfer type is passed that is not supported by the implementation, or if a protocol type SERVER_TYPE or CLIENT_TYPE is passed with a value that is not an array of Strings.

NoServerFoundException (src) - if no suitable protocol server can be determined.

ContentAccessException (src) - if content transfer fails.

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

LinkTranslationException (src) - if ingesting protocol specific links into copies of non-embedded media objects fails.

ConversionException (src) - if the middleware fails converting the media content to another format in order to make it suitable for a specific protocol server.

MediaException (src)