javax.emb
Interface MediaFormat

All Superinterfaces:

java.io.Serializable

All Known Implementing Classes:

EmbeddedMediaFormat (src) , GenericMediaFormat (src) , MpegAudioFormat (src) , OggVorbisFormat (src)

public interface MediaFormat

extends java.io.Serializable

This interface is used throughout Enterprise Media Beans for operations that require knowledge of the media format. Each specific supported media format requires an implementation of this interface to handle format specifics correctly. Applications should not create instances directly using a constructor, but instead query them using the MediaFormatRegistry (src) class. As implementations of this interface may have to be transferred over remote boundaries at times, the MediaFormat interface extends Serializable.

assembleContent

public byte[] assembleContent(java.net.URL mediaLocation,
                              MediaSegment (src) [] mediaSegments)
                       throws MediaException (src) 

Assembles the given media segments and returns the resulting media content as a byte array. The optional media location describes where the content itself is stored, and passing it allows links to child media to be written as relative file paths. In case the given media location is null, all links in the resulting media content will be URLs. In case it is not null, those links that can be expressed relative to the given URL will be relative file paths, and all others will be URLs.

This means a media object that has been disassembled into media segments beforehand can be reassembled using this operation. The given media location is used to handle relative links to external media correctly. Media Entity Beans use this operation when maintaining referential integrity between complex graphs of persistent, non-embedded, media objects. The implicit limitation of media size to a theoretical limit of 2GB should not impose a restriction in practice as this operation is only of value for non-embedded media, which tends to be relatively small in size.

Parameters:

mediaLocation - the intended location of the media to be assembled.

mediaSegments - the segments that are to be assembled.

Returns:

the assembled content.

Throws:

ContentTooLargeException (src) - if the resulting byte array size exceeds the theoretical maximum Java array size of 2 GB,

LinkTranslationException (src) - if there's a problem transforming one of the media segment child locations into a format specific link.

FormatSyntaxException (src) - in case of embedded media formats, thrown if the given media segment array contains more than one element, or if an element is passed that contains a child link that is not null.

java.lang.NullPointerException - if the given segment array is null.

MediaException (src)

disassembleContent

public MediaSegment (src) [] disassembleContent(java.net.URL mediaLocation,
                                         byte[] mediaContent)
                                  throws MediaException (src) 

Disassembles the given media content into an array of media segments preserving the order of the original content, and returns said array of media segments. The optional media location describes where the content itself is stored, and passing it allows relative links to child media to be interpreted.

In case of simple media formats, the resulting media segment array contains exactly one element, which consists of null as child location and the complete media content as content. Media Entity Beans use this operation when maintaining referential integrity between complex graphs of persistent, non embedded, media objects. Note that this operation is only of value for non-embedded media formats. As the reassembly is limited to media up to 2GB in size, the MediaFormat.isEmbedded()operation should be used to determine if disassembling a given media content is of value beforehand.

Parameters:

mediaLocation - the location of the media to be disassembled.

mediaContent - the content to be disassembled.

Returns:

the segments.

Throws:

FormatSyntaxException (src) - if the content does not match the expected media format.

LinkTranslationException (src) - if the given media location is null and the given content contains child links that are not URLs.

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

MediaException (src)

extractHeader

public MediaHeader (src)  extractHeader(java.io.InputStream content)
                          throws MediaException (src) 

Extracts a media header instance from the given media content and returns it. The information presented by the header is up to the implementation of the media format bean, and the information returned can therefore be the complete header information as defined in the relevant media format standard, no information at all, or something in between. However, implementers are encouraged to return header information as complete as possible, as such information can be highly useful for format specific algorithms and optimizations.

Please note that the given input stream is not closed once the operation is successfully completed.

Parameters:

content - the media content to extract the header from.

Returns:

the header.

Throws:

FormatSyntaxException (src) - if the given media content does not match the syntax defined for the receiver.

FormatFeatureException (src) - if the header cannot be extracted because a vital feature of the media format involved is not supported.

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

MediaException (src)

extractProxy

public Media (src)  extractProxy(java.io.InputStream content)
                   throws MediaException (src) 

Extracts a proxy from the given media content and returns it. The proxy may be of any media format. For example, a key frame image may be returned in case of video content, a waveform image in case of audio content, or a thumbnail in case of image content. In case there's a problem creating the surrogate, a default format specific proxy must be returned - for example GenericMediaFormat.GENERIC_PROXY. Please note that the given input stream is closed once the operation is completed.

Parameters:

content - the content to extract the proxy from.

Returns:

the proxy.

Throws:

MediaException (src) - if the given media is not compatible with the receiver

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

getDefaultMimeType

public java.lang.String getDefaultMimeType()

Returns the default MIME type for the given media format as a String. If there is no suitable MIME type, Media.MIME_TYPE_UNKNOWN should be returned.

Returns:

the default MIME type.

isEmbedded

public boolean isEmbedded()

Returns false if the media format allows links to external media, or true otherwise. It can be used to determine if the media content has to be examined and possibly altered when a persistent media object is moved from one location to another while having child and/or parent dependencies to other media objects.

Returns:

true if the format is embedded, false if it is non-embedded.

isStreamingDesirable

public boolean isStreamingDesirable()

Returns true if it is always desirable to stream media of this format, or false otherwise. For example, it is not always desirable to stream JPEG or GIF images, even given the possibility to stream them with a Real player. Servlets can use this information to decide whether they should try to stream content or transfer it using burst transfer instead.

Returns:

true if it desirable to stream the format, false otherwise.