/*
 * JBoss, the OpenSource J2EE webOS
 * 
 * Distributable under LGPL license. See terms of license at gnu.org.
 */

package javax.emb;

import java.net.URL;
import java.util.Collection;

import javax.ejb.CreateException;
import javax.ejb.EJBLocalHome;
import javax.ejb.FinderException;

/**
 * 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.
 * 
 * <p>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.
 * 
 * <p>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.
 * 
 * <p>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.
 * 
 * @version <tt>$Revision: 1.1 $</tt>
 * @author <a href="mailto:ricardoarguello@users.sourceforge.net">Ricardo
 *         Argüello</a>
 */
public interface MediaEntityLocalHome extends EJBLocalHome
{
   final static byte TRANSFER_TYPE_STREAM = 0;
   final static byte TRANSFER_TYPE_BURST = 1;

   /**
    * Creates a new media entity EJB with a generated identity key, the value
    * of <code>System.currentTimeMillis()</code> as value of the <code>lastModified</code>
    * property, and <code>null</code> 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.
    * 
    * @return media entity bean.
    * @throws javax.ejb.CreateException is thrown if a problem related to EJB
    *         creation occurs.
    * @throws MediaException
    */
   MediaEntityLocal create() throws CreateException, MediaException;

   /**
    * 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.
    * 
    * <p>If the given <code>targetDirectoryLocation</code> is <code>null</code>,
    * 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 <code>targetLocation</code>
    * URLs are returned in the order of their respective media entity EJBs.
    * Duplicate media entity EJBs result in <code>targetLocation</code> URLs
    * returned in multiple array slots, <code>null</code> media entity EJBs
    * result in respective <code>null</code> 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.
    * 
    * @param sourceMedia
    * @param targetDirectoryLocation
    * @return URLs array
    * @throws java.lang.NullPointerException if the given source media array is
    *         <code>null</code>.
    * @throws javax.emb.ContentAccessException in case content transfer fails.
    * @throws javax.emb.MediaFormatException if there is a problem dealing with
    *         one of the media formats involved.
    * @throws javax.emb.MalformedLocationException if the URL given is
    *         malformed or has a protocol type not supported by the
    *         implementation.
    */
   URL[] exportMedia(
      MediaEntityLocal[] sourceMedia,
      URL targetDirectoryLocation)
      throws MediaException;

   /**
    * 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 <code>null</code>.
    * Passing in <code>null</code> or a partial description not present in
    * the data store will result in an empty collection.
    * 
    * @param partialDescription description.
    * @return all media entities whose description contains the given String.
    * @throws javax.ejb.FinderException if a finder problem occurs.
    */
   Collection findByPartialDescription(String partialDescription)
      throws FinderException;

   /**
    * 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 <code>null</code>. Passing
    * in <code>null</code> or a partial location not present in the data
    * store will result in an empty collection.
    * 
    * @param partialLocation location.
    * @return all media entities in the persistent store whose location URL
    *         contains the given String.
    * @throws javax.ejb.FinderException if a finder problem occurs.
    */
   Collection findByPartialLocation(String partialLocation)
      throws FinderException;

   /**
    * Returns the media entity with the given identity.
    * 
    * @param identity identity.
    * @throws java.lang.NullPointerException if the value passed is <code>null</code>.
    * @throws javax.ejb.FinderException if a finder problem occurs or no media
    *         entity is found.
    */
   MediaEntityLocal findByPrimaryKey(String identity) throws FinderException;

   /**
    * 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.
    * 
    * <p>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.
    * 
    * <p>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.
    * 
    * @param sourceLocations source locations.
    * @param names names.
    * @return @throws java.lang.NullPointerException if one of the arrays
    *         passed is <code>null</code>.
    * @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.
    * @throws javax.ejb.CreateException if the creation of a media entity EJB
    *         fails.
    * @throws javax.emb.ContentAccessException if content transfer fails.
    * @throws javax.emb.MediaFormatException if there's a problem dealing with
    *         one of the media formats involved.
    * @throws javax.emb.MalformedLocationException if one of the URLs given is
    *         malformed or has a protocol type not supported by the
    *         implementation.
    * @throws javax.emb.ContentTooLargeException if one the media entity EJB
    *         contents would become larger than supported by the
    *         implementation.
    */
   MediaEntityLocal[] importMedia(URL[] sourceLocations, String[] names)
      throws CreateException, MediaException;

   /**
    * 
    * 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.
    * 
    * <p>The kind of protocol server chosen may be determined by the given
    * transferType. Specified values are:
    * 
    * <ul><li>TRANSFER_TYPE_STREAM for streaming of media content, using a
    * stream server as protocol server.</li>
    * 
    * <li>TRANSFER_TYPE_BURST for burst transfer of media content, usually
    * using a web server as protocol server. <li></ul>
    * 
    * <p>Specified protocol constraint types are:
    * 
    * <ul><li>"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.</li>
    * 
    * <li>"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.</li></ul>
    * 
    * <p>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.
    * 
    * @param content content.
    * @param transferType transfer type.
    * @param constraints constraints.
    * @return URL
    * @throws java.lang.NullPointerException if the media object passed is
    *         <code>null</code>.
    * @throws java.lang.IllegalArgumentException if a transfer type is passed
    *         that is not supported by the implementation, or if a protocol
    *         type <code>SERVER_TYPE</code> or <code>CLIENT_TYPE</code> is
    *         passed with a value that is not an array of Strings.
    * @throws javax.emb.NoServerFoundException if no suitable protocol server
    *         can be determined.
    * @throws javax.emb.ContentAccessException if content transfer fails or if
    *         non-embedded content is passed in anything other than a media
    *         entity EJB.
    * @throws javax.emb.MediaFormatException if there's a problem dealing with
    *         one of the media formats involved.
    * @throws javax.emb.LinkTranslationException if ingesting protocol specific
    *         links into copies of non-embedded media objects fails.
    * @throws javax.emb.ConversionException if the middleware fails converting
    *         the media content to another format in order to make it suitable
    *         for a specific protocol server.
    */
   URL publishContent(
      Media content,
      byte transferType,
      ProtocolConstraints constraints)
      throws MediaException;

   /**
    * 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.
    * 
    * <p>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.
    * 
    * <p>The kind of protocol server chosen may be determined by the given
    * transferType. Specified values are:
    * 
    * TRANSFER_TYPE_STREAM</code> for streaming of media content, using a
    * stream server as protocol server.</li>
    * 
    * <li><code>TRANSFER_TYPE_BURST</code> for burst transfer of media
    * content, usually using a web server as protocol server.</li></ul>
    * 
    * <p>Specified protocol constraint types are:
    * 
    * <ul><li>"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.</li>
    * 
    * <li>"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.</li></ul>
    * 
    * <p>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.
    * 
    * <p>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.
    * 
    * <p>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.
    * 
    * @param playlist
    * @param transferType
    * @param constraints
    * @return @throws java.lang.NullPointerException if the playlist passed is
    *         <code>null</code>.
    * @throws java.lang.IllegalArgumentException if a transfer type is passed
    *         that is not supported by the implementation, or if a protocol
    *         type <code>SERVER_TYPE</code> or <code>CLIENT_TYPE</code> is
    *         passed with a value that is not an array of Strings.
    * @throws javax.emb.NoServerFoundException if no suitable protocol server
    *         can be determined.
    * @throws javax.emb.ContentAccessException if content transfer fails.
    * @throws javax.emb.MediaFormatException if there's a problem dealing with
    *         one of the media formats involved.
    * @throws javax.emb.LinkTranslationException if ingesting protocol specific
    *         links into copies of non-embedded media objects fails.
    * @throws javax.emb.ConversionException if the middleware fails converting
    *         the media content to another format in order to make it suitable
    *         for a specific protocol server.
    */
   Media publishMedia(
      MediaEntityLocal[] playlist,
      byte transferType,
      ProtocolConstraints constraints)
      throws MediaException;
}