JSR 86 - Enterprise Media

8/20/2019 JSR 86 - Enterprise Media

1/72

Java Speci fication Request 086

Enterprise Media Beans TM Speci fication,

Version 1.0, Final Release

This is the specification of the Enterprise Media Beans architecture. The Enterprise Media Beansarchitecture allows the seamless integration of rich media data like audio, video, image and componentdocument formats into applications based on the J2EE programming model. Applications writtenusing the Enterprise Media Beans architecture incorporate rich media data as just another datatype in a scalable, transactional, and multi-user secure way. They may be written once, and then deployed onany server platform that implements both the J2EE and the Enterprise Media Beans specifications.

Expert Group:

Dave Bolt

Dr. Harold A. Anderson, Jr.

Dr. Poornachandra G. Sarang

Jonathan R. Earl

Sascha Baumeister, Specification Lead

Document Author:

Sascha Baumeister

Please send technical comments on this specification to:[email protected] (Sascha Baumeister, spec lead)[email protected] (Ralph B. Case, maintenance lead)

Version 1.0, Final Release

April 6, 2004


2/72

Enterprise Media Beans Specification Version 1.0, FinalRelease

1

Table of Contents

CHAPTER 1 INTRODUCTION 4

1.1 Target Audience 4

1.2 Acknowledgements 4

1.3

Organization 5

1.4

Document Conventions 5

CHAPTER 2

POSITIONING 6

2.1

Java Media Framework TM 7

2.2

Content Management Systems 7

2.3

Java Content Repository (JSR170) 8

2.4 Media Streaming 8

CHAPTER 3 ARCHITECTURE 10

3.1

Media Foundation Beans 10

3.2

Media Entity Beans 11

CHAPTER 4

MEDIA FOUNDATION BEANS 15

4.1 javax.emb.Media 16

4.2

javax.emb.MediaBean 18

4.3

javax.emb.MediaFormat 19

4.4 javax.emb.GenericMediaFormat 21

4.5

javax.emb.MediaFormatRegistry 22

4.6 javax.emb.MediaSegment 23

4.7

javax.emb.MediaHeader 25

4.8 javax.emb.GenericMediaHeader 25

4.9

javax.emb.MediaConverter 26

4.10

javax.emb.MediaConverterSpec 27

4.11 javax.emb.MediaException 28

4.12

javax.emb.ContentAccessException 28


3/72

Enterprise Media Beans Specification Version 1.0, Final Release

2

4.13

javax.emb.MediaFormatException 28

4.14

javax.emb.ContentTooLargeException 28

4.15

javax.emb.ConversionException 29

4.16

javax.emb.FormatAlreadyBoundException 29

4.17 javax.emb.FormatFeatureException 29

4.18

javax.emb.FormatNotFoundException 29

4.19 javax.emb.FormatSyntaxException 29

4.20

javax.emb.LinkTranslationException 29

4.21 javax.emb.MalformedLocationException 30

CHAPTER 5

MEDIA ENTITY BEANS 31

5.1 javax.emb.MediaEntityLocal 33

5.2

javax.emb.MediaEntityLocalHome 42

5.3

javax.emb.MediaListener 49

5.4 javax.emb.ProtocolConstraints 51

5.5

javax.emb.MetaDataEntityLocal 52

5.6 javax.emb.MetaDataEntityLocalHome 56

5.7

javax.emb.MediaException 57

5.7.1

javax.emb.ContentUnmutableException 57

5.7.2

javax.emb.IllegalOptionException 57

5.7.3

javax.emb.ListenerVetoException 57

5.7.4

javax.emb.LocationUnmutableException 57

5.7.5

javax.emb.MalformedQueryException 57

5.7.6

javax.emb.MetaDataValidationException 57

5.7.7

javax.emb.MetaDataSyntaxException 58

5.7.8

javax.emb.NoServerFoundException 58

5.7.9

javax.emb.VersionChainIntegrityException 58

5.7.10

javax.emb.UnsupportedQueryLanguageException 58

5.8 javax.ejb.RemoveException 58 5.8.1

javax.emb.ParentAssociationExistsException 58

5.8.2

javax.emb.PredecessorAssociationExistsException 58

CHAPTER 6

RESPONSIBILITIES OF EMB ROLES 59

6.1 Media Foundation Bean Providers 59

6.2

Media Entity Bean Providers 59

6.3

EJB Application Developers 59

6.4 EJB Container Providers 60

6.5

Client Programmer s Responsibilities 60


4/72


3

CHAPTER 7

EXAMPLES 61

7.1

Simple Burst Transfer 62

7.2

Publishing & Burst Transfer 63

7.3

Publishing & Streaming 64

7.4 Presentation & Dynamic Conversion 65

7.5

Dynamic Header Extraction 66

CHAPTER 8

APPENDIX 67

8.1

Reference 67

8.1.1

Classes and Interfaces 67

8.1.2

Exceptions 70

8.2 Related Documents 71


5/72


4

Chapter 1 Introduction

This is the specification of the Enterprise Media Beans (EMB) architecture. TheEnterprise Media Beans architecture is a component-based architecture that extends the

J2EE and Enterprise JavaBeans architectures to allow the seamless integration of richmedia data such as audio, video, image or component documents into J2EE technology based business applications. Such applications can be written once, and thendeployed on any server platform that supports the J2EE and Enterprise Media Beansspecifications.

This specification is accompanied by a container independent reference implementation

(RI) and a technology compatibility kit (TCK) able to test if an implementation isconforming this specification or not. Both the reference implementation and thetechnology compatibility kit are open source, published under Common Public License(CPL), and available athttp://oss.software.ibm.com/developerworks/projects/embri fordownload. Container providers and 3rd parties are invited to implement this specificationif a quality of service exceeding the one provided in said reference implementation isdesired.

1.1 Target Audience

The target audience of this specification is the subset of the J2EE specification audience

working on incorporating support for rich media data into their product offerings. Thisspecification is especially targeting, but is not limited to, the Enterprise JavaBeans part ofthe J2EE community.

In this community, this document mainly targets vendors of EJB transaction processingplatforms and vendors of enterprise application tools. However, the API sections of thisspecification may also be of interest for application programmers who want to useEnterprise Media Beans implementations in their projects.

1.2 Acknowledgements

We !d like to thank Jeffrey Frey, Donna N Dillenberger Gerd Breiter and all others in

IBM contributing directly or indirectly to this work for their tremendous support andinvaluable input during the evolvement of Enterprise Media Beans.

Thanks to Sarah Boaz, Frank Castaneda, Adam J. Goldman and Adrian G. Treuille fortheir dedication and creativity during the Enterprise Media Beans related IBM ExtremeBlue 2000 internship in Boston.

Special thanks also to Ann Black, Lan Vuong and Ralph Case for teaming up to finalizethe reference implementation and the related test kit.

Last but not least, we !d like to acknowledge the Enterprise JavaBeans 2.0 architects aswe took parts of their document layout as a template for this specification. This should


6/72


5

ease navigation and understanding for the audience already familiar with the Enterprise JavaBeans specification.

1.3 Organization

Chapter 2 positions the Enterprise Media Beans technology against related Java and non- Java technology.

Chapter 3 provides a high level view on the Enterprise Media Beans architecture and itscomponents.

Chapter 4 defines the Media Foundation Beans component of the Enterprise MediaBeans architecture. This component is targeting the whole J2EE community. Parts of the

J2SE/J2ME community might find parts of this specification useful too.

Chapter 5 defines the Media Entity Beans component of the Enterprise Media Beansarchitecture. This component is specifically targeting the Enterprise JavaBeanscommunity.

Chapter 6 provides some Servlet code snipplets illustrating the use of Enterprise MediaBeans in J2EE based enterprise applications.

Chapter 7 is the appendix including an API reference, an index, and a list of relateddocuments.

1.4 Document Conventions

The regular Garamond font is used for prescriptive information.

The italic Garamond font is used for descriptive information.

The regular Courier font is used for code samples.

The OMG Unified Modeling Language (UML) is used for diagrams. Concrete classes aredepicted as regular rectangles; interfaces are depicted as rounded rectangles.


7/72


6

Chapter 2 Positioning

Rich media data extends traditional computer data formats into more natural data formatsfor the interaction of humans and computers by incorporating images, documents,animations, motion pictures, voice, audio, and video. Leading market, business, social,and technical indicators point to the growing importance of this digitally recordedcontent. Storing, managing, rendering and integrating this kind of data seamlessly intobusiness applications yields significant competitive advantage and the opportunity fornew markets, new customers, and new services.

The World Wide Web demand for rich media data has brought up a wide variety of

products dealing with recording, authoring, rendering, streaming and storing rich mediadata in recent years. Usually, these products are developed around a specialized andproprietary database, make use of specialized and proprietary file systems and offerproprietary API !s and protocols to handle rich media data.

Content Management Systems for instance are highly complex and heavyweightmiddleware with proprietary data stores and proprietary interfaces to store, retrieve andmanage digital content. Streaming media solutions as another example are non-standardized software products using proprietary protocols to transfer and rendercontent such as audio and video on end users! systems. They mainly work withproprietary formatted content stored in plain files. Products within this fast emergingmarket come from companies like Real Networks, Microsoft, Apple, and IBM.

This has a serious impact on enterprise customers who are interested in incorporatingrich media data into their core business applications. For example, the use of proprietary APIs creates dependencies on the architecture of the products used, making it hard tomigrate from those products later. The integration of standard business applications withproducts exposing proprietary data formats, APIs and protocols is very hard to achieve.The lack of integration with mission critical enterprise data residing in customers ! relational databases violates referential integrity. Backup procedures are not consistent,because the rich media part of the enterprise data is handled by proprietary datamanagement systems. Caching or replication of media data throughout customerintranets is either not handled at all or based on proprietary solutions or stream serverproviders. Also, there is no unified mechanism for authorization and transactionalbehavior when it comes to integrating structured data with rich media data.

What customers are lacking is a standardized middleware extension that provides a

uniform view on rich media data from the backend throughout their infrastructure, and apossibility of maintaining it, using their existing data administration tools andprocedures. In other words, rich media data needs to be treated as just another data typethat is handled similarly to structured data within the application layer. Enterprise MediaBeans addresses these rich media related problems within the J2EE community.


8/72


7

2.1 Java Media FrameworkTM

The Java Media Framework models rich media primarily from the functional perspectiveof capturing, processing and playing back streaming media. It is mainly based aroundthe concept of constructing customized media players in Java in a platform independentway, thereby targeting the distributed programming model (J2SE " applets andapplications). In contrast, Enterprise Media Beans come from a data model perspective,thereby targeting integration of rich media and relational data in the server-centricprogramming model (J2EE, Servlets, JSPs, EJBs).

The Java Media Framework is targeted at streaming media capture and playback and hasas its strength the means to handle rich media that is composed of tracks of content tobe processed (multiplexed/ demultiplexed, compressed/ decompressed, transcoded,rendered etc.). From the perspective of Enterprise Media Beans, the Java Media

Framework is the mechanism that extends J2SE for supporting rich media processing.From the perspective of the Java Media Framework, Enterprise Media Beans is one ofseveral possible ways to manage persistent rich media data.

There is real synergism possible between JMF and EMB when it comes to transcodingand conversion of rich media data. The JMF processor model allows JavaBeans to bedeveloped that perform transcoding and conversion. JMF-based converters andtranscoders implemented as JavaBeans can be incorporated into Enterprise Media. Asthis part of the Java Media Framework doesn ! t seem to be specifically tailored to thedistributed programming model, Enterprise Media Beans transcoders and converters areimplementable based on the Java Media Framework. However, Enterprise Media Beansdoes not architect the internals of such implementations and therefore also allows theintegration of native means of transcoding or conversion.

2.2 Content Management Systems

Content Management Systems are products that manage and persist rich media data.They come with product specific APIs and data models surrounding rich media data,which makes it very hard for customers to exchange data between competing products,like the FileNetTM content management system and IBM !s Content ManagerTM. Contentmanagement systems focus on management and query aspects of rich media, likedistribution of content over the network and federated content search algorithms.

As the requirements for rich media related data depend highly on the use case scenarioand the kind of media involved, the APIs available with these systems tend to be rathercomplicated and large. Also, content management systems tend to integrate rather poorly

with J2EE, especially when it comes to backup/restore, security, and transactions. Inparticular, EJB security credentials and transaction concepts are not compatible withthose in content management systems, if present at all.

Enterprise Media Beans is intended to be a lightweight, standardized middleware thatcan be used with or without an underlying content management system to seamlesslyintegrate rich media data into a J2EE environment. On one hand, it can be implementedon top of a relational database system in conjunction with file system to provide supportfor a variety of platforms. On the other hand, a specific content management system canbe encapsulated as a data store for Enterprise Media Beans.


9/72


8

2.3 Java Content Repository (JSR170)

The Java Content Repository is a work in progress unifying the APIs for contentmanagement systems. The positioning between this API and Enterprise Media Beans ishighly similarly to the positioning between JDBC and EJBs, i.e. Java Content Repositoryprovides the data access function and data model, whereas Enterprise Media Beansprovides the integration into the J2EE/EJB component model. Specifically, EnterpriseMedia Beans can be implemented on top of Java Content Repository compliant contentmanagement systems.

Also similarly to the relation between EJBs and JDBC, we target an evolution of functionbeing incorporated into Enterprise Media Beans over time, like search and indexing.However, we postpone this integration to a future version of Enterprise Media Beans, as

JSR170 has not evolved to a point yet that allows integrating such function into the API.

2.4 Media Streaming

Today, the market for streaming media product offerings is neither standards based nor a Java domain. The leading product offerings can be characterized as proprietary, likeMicrosoft Windows Media ServicesTM, RealNetworks RealSystemTM, Apple QuicktimeTM,IBM VideoChargerTM, or Nullsoft WinampTM. Most of them feature a unique proprietaryplayer. This technique is an optimization of the traditional way to handle data, which isto first transfer the streaming media over a network and to store it locally on the clientcompletely before presenting it. Streaming technology always requires a pair ofcomponents to work together: On the server side a stream server component is requiredto stream the data onto the network. On the client side a player is required that is ableto immediately process and present rich media data stream right when it arrives over thenetwork.

In order to initiate streaming with a media player, a file is often required containing apointer to the media file to be streamed, the IP hostname of the stream server machine,the port the stream server software listens to,and optionally additional information. Such afile is commonly referred to as a metafile, andits format is specific to the kind of streamserver used. To the right is a typical samplecontent of a RealNetworksTM metafile (#.ram$ file).

The major advantage of streaming technology is that it makes transfer and rendering of

rich media realistic regardless of the media size. The major disadvantage is that due tothe lack of accepted standards, stream server and media player components are stronglycoupled by proprietary protocols and therefore don ! t work with components of other

vendors in the majority of cases. Enterprise Media Beans addresses the heterogeneityand proprietary nature of streaming media client/ server systems by encapsulation. Thus,enabling e-business applications to be developed on the J2EE platform without having todeal with the vendor-specific characteristics of the stored streaming media content andinstalled streaming media servers.

Since Enterprise Media Beans abstract over streaming-media-based products, they ineffect represent a J2EE middleware extension for managing and delivering distributed

rtsp://9.164.184.12:200/media/video42.rm

rtsp://9.164.184.12:200/media/audio16.rm

Figure 1: Sample streaming metafil


10/72


9

streaming media content. EMB enables enterprise Java applications to be developed thathave no dependency on the type of specific streaming technology installed.


11/72


10

Chapter 3 Architecture

The J2EETM architecture consists of components that help developers to create enterprisebusiness applications that conform to the Model-View-Controller paradigm within theserver-centric programming model. With the exception of the ServletTM and JavaServerPagesTM components (which deal with view and controller aspects), all J2EEfunctionality can be applied in two forms: either separately by adding atomiccomponents like JDBCTM, JMSTM or JTSTM to enrich applications with specific services, orby using Enterprise JavaBeansTM that integrate all this into a single architecture.Therefore, J2EE applications significantly differ in either utilizing Enterprise JavaBeanstechnology or not.

Enterprise Media Beans targetthe seamless integration of richmedia data into applicationsbased on the J2EE programmingmodel. As such applicationscome in two basic shapes asdescribed above, the EnterpriseMedia Beans architecture isseparated into two componentstoo: Media Foundation Beansrequire only basic Java 2TM technology and can be used inany kind of J2EE application. Incontrast, Media Entity Beans relyon EJB entity beans and aretherefore of interest only forapplications based on the Enterprise JavaBeans architecture.

3.1 Media Foundation Beans

Media Foundation Beans provide definitions for basic media related services in a server-centric programming model. These services specifically target media objects that arepossibly transient, local, and immutable.

Core to this is a model for media formats that offers a service to extract links to external

media resources from non-embedded media, a service to extract header informationwithout the need of programming against platform specific interfaces, and some otherservices required when integrating rich media data into J2EE based applications. Mediaheaders can be used to dynamically calculate information about a media object insteadof storing said information redundantly in a database. For example, if a Servlet wants todisplay song length and sampling rate information about MP3s, this information caneasily be extracted from MP3 files. Extracting link information from non-embeddedmedia objects is useful when analyzing dependencies between media files.

Additionally, a model is defined to convert media objects from one format to another,without the need to program against platform specific interfaces. For example,

Enterprise Media Beans

Media FoundationBeans

Media EntityBeans

EJB 2.Entity Beans

Java 2 basTechnology

require requir

requir

Figure 2: Enterprise Media Bean components and dependencies


12/72


11

applications transcoding media objects can use this in order to meet format requirementsof specific clients. Another use is Servlets dynamically modifying images served through

them, in order to meet size requirements or add watermarks.

In the future, Media Foundation Beans will be extended to offer an architected model fortranscoding, i.e. analyzing a given client !s capabilities and determining whichconversions are necessary to render a given media object on said client. However, asstandards for formally describing and querying client capabilities are still evolving, thetopic has been postponed to future versions ofthis specification.

Both media formats and media converters aredesigned as a plug-in architecture, which means3rd party implementations of these componentscan be used throughout all implementations of

Media Foundation Beans. The referenceimplementation of this specification will comewith specific support for those media formats thatare most common throughout the Internet "

JPEG, BMP, WAV, MPEG audio (MP3), MPEG video and a generic playlist format. Additionally,any kind of embedded media format is genericallysupported.

Media Foundation Beans offer a convenient and lightweight way to include basic richmedia related services in J2EE applications. However, if EJB entity beans are used insuch applications, the use of Media Entity Beans as described in the section belowshould be preferred. Media Entity Beans use the functionality provided by MediaFoundation Beans.

3.2 Media Entity Beans

Media Entity Beans integrate the services provided by Media Foundation Beans into theEnterprise JavaBeans architecture, adding additional services that require mediapersistence.

Core to Media Entity Beans is an EJB entity bean called media entity EJB. Each mediaentity EJB models a single medium that is persistent and mutable. One key design pointof media entity EJBs is that they abstract over the persistent store of rich media data,which means they are opaque to the application model whether persistence of mediacontent is achieved using binary large objects, user defined data types, IBM Datalinks or

simple URL references. Also, as rich media content can range from a few kilobytes tomany gigabytes in size, the freedom of choice in how to map media of various formatscan have a significant impact on the overall system performance.

Media Entity Beans are designed for either container-managed persistence or bean-managed persistence which allows EJB deployers to map these EJBs to a custom datamodel or a content repository.

This is important when it comes to backup/restore processes in enterprises, as consistentbackups of the complete data model, including rich media, become possible. However,

Media Foundation Beans

Media FormatPlug

plu -i plu -i

MediaConverter

3rd PartImplementatio

3rd PartyImplementatio

Figure 3: Media Foundation Beansplug-in architecture


13/72


12

this requires the media content to be persisted using a technology supported bydatabase backup/ restore processes - like binary large objects or Datalinks.

The key advantage of media entity EJBs is their tight integration into the EJBprogramming model. Media entity EJBs share the same transaction and security modelwith all other business entity beans of a complex, EJB based, enterprise application.

Also, if packaged with a business application they can participate fully in EJBrelationships, which iskey to a seamlessintegration ofinformation in EJBbased enterpriseapplications.

The static structure

diagram to the rightdepicts the model of alibrary application thatmaintains and presentsinformation aboutEmmy awards. Themedia entity EJBparticipates in varyingroles in relationshipsto multiple applicationspecific EJBs. Thisallows a seamlessintegration of richmedia data into this

application!s EJB model.

Apart from forming relationships with other EJBs, media entity EJBs can relate with othermedia entity EJBs. This is especially useful to guarantee referential integrity in case ofnon-embedded media formats. Non-embedded media contains links to external mediaresources, which require an understanding of the document format in question.

Media Foundation Beans provide thenecessary support and plug-inmechanisms for analyzing andgenerating the dependencies (links)between non-embedded media objectsand their children, transform such linksto child media objects into parent/child

relationships between media entityEJBs, and manage these relations incase participants are moved or altered.

The sample to the left shows therelations formed between variousmedia entity EJBs after analyzing thenon-embedded media files house.smi(SMIL format) and house.rp (RealPixformat) recursively.

Figure : Media entity EJB participating in custom EJB relationship

Perso

MediaEntit

EpisodSeries

EmmyAsse

EmmyAwardwinne

1 ..

*

1winne 1

1

pictur

1 .. *1 .. *

participa

1 1

poste

1 *

background

1 *

1

1

vide

Figure 5: Parent/ child relationships among media entity EJB

. . .

house.smi

house.rt house.r house.r

image1.jpg image2.jpg image10.jp


14/72


13

Other relationships among media entity EJBs that are part of this specification arepredecessor/successor relations between different editions of the #same$ media and

content/representant relationships between images and thumbnails. Of course, customEJB models may define additional relationships among media entity EJBs.

Also, media entity EJBs can be extended using a built-in persistent observer design. Thisallows application programmers to add custom behavior to various events in mediaentity EJBs, while remaining independent from a media entity EJBs implementation. Forexample, persistent observers allow application-specific relations that involve mediaentity EJBs to be maintained correctly as the observers are notified of remove requests.

Also, the observers are notified of every state change in media entity EJBs, which allowsapplication-specific media entity extensions that are independent of the underlyingmedia entity EJB implementation.

Media entity EJBs also provide an operation that allows publishing media objects to

protocol servers for access, such as HTTP servers or stream servers. While beingmaintained as media entity EJBs, media content is neither bound to a specific protocol,nor a specific protocol server instance. The advantage is that systems built on mediaentity EJBs have no hard dependencies on a specific stream server manufacturer or aproprietary transport protocol, both of which may become legacy in the future.Publishing a media entity to protocol servers will create managed copies of the mediaentity and all its children on said protocol server. In opposition to transferring content toa client as a Servlet response this has a number of advantages, both for embedded andnon-embedded media types:

§ Publishing an embedded media object to stream servers allows streaming access tothe media content, which dramatically reduces latency times in case the content islarge. Also, no streaming metadata has to be maintained for the media entities as it isgenerated on the fly if necessary.

§ Publishing a non-embedded media object to stream servers allows streaming accessto the media content and the content of all its direct or indirect children. Non-embedded media objects cannot be transferred to a client by Servlet response, suchmedia objects always require publishing by nature. Again, no streaming metadatahas to be maintained for the media entities as it is generated on the fly if necessary.

§ Publishing an embedded media object to an HTTP server allows burst access to themedia content, similar to transferring the content as a Servlet response. However, thenetwork infrastructure can efficiently cache the content.

§ Publishing a non-embedded media object to an HTTP server allows burst access tothe media content and the content of all its direct or indirect children. Again non-embedded media objects cannot be transferred to a client by Servlet response, andthis method is preferred over publishing to a stream server in all cases where thesize of the media object and all its children combined is relatively small, as the

network infrastructure can efficiently cache the content.

As a result of a publish request, either a meta-medium or a URL is returned dependingon the kind of request. A meta-medium can be sent directly to a client as a Servletresponse, and most stream servers allow meta-media to be playlists consisting of severalmedia objects. In contrast, a URL has the advantage that it allows content to beembedded as part of an HTML page, for example using the HTML IMG element. Bothkinds of results point to the media content published and contain additional informationabout a specific protocol server and a specific transport protocol to be used for contentaccess.


15/72


14

Of course, subsequent publish requests against the same media object are likely to beoptimized by an EMB implementation. Also, note that the set of protocol servers

supported is up to each implementation of this specification.

A

B

C

A !

B!

!

OriginServer

ProtocolServer

Publishing A causes A, B,and C to be copied to theprotocol server. Inside A ! ,the child links to B and Care replaced to protocol

and server specific links toB ! and C ! .

Figure 6: Publishing a no -embedded media objec


16/72


15

Chapter 4 Media Foundation Beans

Media Foundation Beans model basic operations on media within the server-centric J2EEprogramming model. With the exception of media header extraction they do not targetthe semantic understanding of the media content, but rather represent a syntacticalapproach in order to unify the way media is managed and handled.

So far, the overall design of Media Foundation Beans is mainly driven by therequirements of Media Entity Beans. However, in the long run Media Foundation Beansare intended to offer services independently from Media Entity Beans, like transcodingsupport for the server-centric programming model. Therefore, the design of Media

Foundation Beans will evolve exceeding Media Entity Beans requirements in the future.

Throughout this chapter, the term #link $ describes a reference from within a non-embedded media content to an external resource, most likely a file. Such links come intwo forms: Absolute links are always URLs and therefore contain all the informationnecessary to access external media content: access protocol, machine address, andaccess path. On the other hand, relative links only provide partial information, forexample the full or partial access path in case of a file name. This means that the missinginformation required for access has either to be derived from the context, or has to beprovided explicitly.

Fi ure 7: Me ia Foun ation Beans com onents an interactions

analyze

manage

Medi

MediaFormat

MediaConverterSpec

MediaConverte

MediaBea

MediaFormatRegistry

GenericMediaFormat GenericMediaHeade

extrac extract

conver

utiliz

MediaHeadeMediaSegment


17/72


16

4.1 javax.emb.Media

This basic interface is used throughout Enterprise Media Beans to define the mostcommon behavior for media objects. It defines the services common to all kinds ofmedia objects, regardless of them being persistent or transient.

There are basically two major ways to implement this interface. Media Entity Beans asdescribed in chapter 5 deal with media content modeled as EJB entity beans, i.e. mediathat is persistent and mutable. The class MediaBean models media content that is local,possibly transient and immutable as described later in this chapter.

In order to allow a common view on all kinds of media objects, the Media interfaceextends java.io.Serializable, regardless of media being persistent or transient. Having theMedia interface extend Serializable ensures that instances can be transferred over remoteboundaries, for example using facade stateless session beans.

getContent ()Returns the complete media content as a byte array. This method is intended forconvenient access to media content up to a few MB in size. Streaming I/O access asdefined in readContent() should be used instead to access large content.

If the resulting byte array size exceeds the theoretical maximum Java array size of 2 GB,a javax.emb.ContentTooLargeException is thrown. A javax.emb.ContentAccessExceptionis thrown if the content cannot be accessed.

getFormat ()Queries a suitable media format instance from the MediaFormatRegistry singleton andreturns it. The file extension contained in the name property is used as a key for thisquery.

A javax.emb.FormatNotFoundException is thrown if the file extension is not registeredwith the media format registry.

getHeader ()

Returns the receiver's header information. Queries a suitable media format instance fromthe MediaFormatRegistry singleton and determines the header information based on it.

public interface Media extends Serializable {

static final String MIME_TYPE_UNKNOWN = www/unknown;

byte[] getContent() throws MediaException;

MediaFormat getFormat() throws MediaException;

MediaHeader getHeader() throws MediaException;

String getMimeType() throws MediaException;

String getName() throws MediaException;

Media getProxy() throws MediaException;

long getSize() throws MediaException;

int readContent (long, byte[]) throws MediaException;

int readContent (long, byte[], int, int) throws MediaException;

}


18/72


17

A javax.emb.FormatNotFoundException is thrown if the file extension is not registeredwith the media format registry. A javax.emb.FormatSyntaxException is thrown if the

receiver ! s content does not match the syntax defined for the receiver ! s media format. A javax.emb.FormatFeatureException is thrown if the header cannot be extracted because a vital feature of the media format involved is not supported by the implementation.

A javax.emb.ContentAccessException is thrown if the actual content access fails.

getMimeType ()

Returns a mime type for the receiver's content as a string. This allows media content tobe written directly to a Servlet output stream, as this technique requires a mime type tobe specified in case the output is different from HTML. If no mime type has been setexplicitly a default mime type is returned, possibly based on the receiver ! s format.

A javax.emb.FormatNotFoundException is thrown if the receiver ! s media format cannot

be determined.

getName ()

Returns the receiver's non-unique name as a String. The name is used as a file name hintin case the media content is to be stored in a file system and therefore may only containcharacters that are valid in file names. It contains a file extension that represents thereceiver ! s media format.

getProxy ()

Returns a media object that can be used as a proxy for the receiver, e.g. a thumbnail, anicon, a short video/audio clip. Servlets can use this operation whenever a thumbnail orsound bite is required to represent a given media and give users an up front impression

of the content. The value returned may have any format and is never null.

getSize ()

This operation returns the receiver's content size in number of bytes as a long value.

A javax.emb.ContentAccessException is thrown if there! s a problem accessing thereceiver ! s content.

readContent (long position, byte[] buffer)

Similarly to input streams, this method fills the given buffer with content read from themedia object. The media content is copied from the given position, and the buffer isfilled beginning with offset 0. In case the buffer is larger than the amount of bytes

available, it is only partially filled. The buffer may also be filled partially if theimplementation uses non-blocking I/O. The method returns the number of bytes copiedinto the buffer, or " 1 in case the given position equals the content size.

A java.lang.IndexOutOfBoundsException is thrown if the given position is negative orexceeding the content size. A java.lang.NullPointerExcetion is thrown if the given bufferisnull. A javax.emb.ContentAccessException is thrown if the actual content access fails.

readContent (long position, byte[] buffer, int offset, int length)

Similar to input streams, this method fills the given buffer with content read from themedia object. The media content is copied from the given position, and the buffer is


19/72


18

filled beginning from the given offset with a maximum amount of bytes defined by thegiven length. In case the buffer is larger than the amount of bytes available, it is only

partially filled. The buffer may also be filled partially if the implementation uses non-blocking I/O. The method returns the number of bytes copied into the buffer, or " 1 incase the given position equals the content size.

A java.lang.IndexOutOfBoundsException is thrown if the given position is negative orexceeding the content size, or in case the given offset is negative or exceeding the buffersize. A java.lang.NegativeArraySizeException is thrown if the given length is negative. A

java.lang.NullPointerExcetion is thrown if the given buffer is null. A javax.emb.ContentAccessException is thrown if the actual content access fails.

4.2 javax.emb.MediaBean

This class implements the Media interface and models media objects that are transient,immutable, and local. In order to avoid excessive memory use, a temporary file may beused to store and access the media content while an instance is alive.

Please note that only methods added to the basic Media interface are described in detailbelow.

MediaBean (InputStream contentStream, String mimeType, String name)

This constructor initializes a new instance with content copied from the given contentstream, and the given mime type and name. The given name is a file name that should

be associated with the object. If the given mimeType is null, one is chosenautomatically by analyzing the given file extension, or Media.MIME_TYPE_UNKNOWN isassigned in case none can be derived.

This constructor is suitable for media content regardless of its size. Please note that thegiven input stream is closed once the content is read completely. Also note that atemporary file is used internally to maintain the content. The implementation tries todelete this file once the instance is garbage collected, and again once the process dies incase the former attempt fails.

public class MediaBean implements Media {

public MediaBean(InputStream, String, String) throws MediaException;

public MediaBean(File, String) throws MediaException;

public byte[] getContent() throws MediaException;

public MediaFormat getFormat() throws MediaException;

public MediaHeader getHeader() throws MediaException;

public String getMimeType() throws MediaException;

public String getName() throws MediaException;

public Media getProxy() throws MediaException;

public long getSize() throws MediaException;



}


20/72


19

A javax.emb.ContentAccessException is thrown if something goes wrong during contenttransfer. A java.lang.NullPointerException is thrown if the given content stream or name

isnull.

MediaBean (File mediaFile, String mimeType)

This constructor wraps a new instance around the given media file. The name propertyof the receiver is initialized to the name of the given file (without path information). Ifthe given mimeType is null, one is chosen automatically by analyzing the fileextension, or Media.MIME_TYPE_UNKNOWN is assigned in case none can be derived.

This constructor is useful to invoke a media related service on an existing media filewithout copying the content of the latter. Please note that the file is not deleted once aninstance referencing it is garbage collected.

A javax.emb.ContentAccessException is thrown if something goes wrong during contenttransfer, or if the given file is not present or cannot be accessed. A

java.lang.NullPointerException is thrown if the given media file isnull.

4.3 javax.emb.MediaFormat

This interface is used throughout Enterprise Media Beans for operations that requireknowledge of the media format. Each specific supported media format requires animplementation of this interface to handle format specifics correctly. Applications shouldnot create instances directly using a constructor, but instead query them using theMediaFormatRegistry class. As implementations of this interface may have to betransferred over remote boundaries at times, the MediaFormat interface extends

java.io.Serializable.

assembleContent (URL mediaLocation, MediaSegment[] mediaSegments) Assembles the given media segments and returns the resulting media content as a bytearray. The optional media location describes where the content itself is stored, andpassing it allows links to child media to be written as relative file paths. In case thegiven media location is null, all links in the resulting media content will be URLs. Incase it is not null, those links that can be expressed relative to the given URL will berelative file paths, and all others will be URLs.

This means a media object that has been disassembled into media segments beforehandcan be reassembled using this operation. The given media location is used to handlerelative links to external media correctly. Media Entity Beans use this operation when

public interface MediaFormat extends Serializable {

byte[] assembleContent(URL, MediaSegment[]) throws MediaException;

MediaSegment[] disassembleContent(URL, byte[]) throws MediaException;

MediaHeader extractHeader(InputStream) throws MediaException;

Media extractProxy(InputStream) throws MediaException;

String getDefaultMimeType();

boolean isEmbedded();

boolean isStreamingDesirable();

}


21/72


20

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-embeddedmedia, which tends to be relatively small in size.

If the resulting byte array size exceeds the theoretical maximum Java array size of 2 GB,a javax.emb.ContentTooLargeException is thrown. A LinkTranslationException is thrownif there ! s a problem transforming one of the media segment child locations into aformat specific link. In case of embedded media formats, a

javax.emb.FormatSyntaxException is thrown if the given media segment array containsmore than one element, or if an element is passed that contains a child link that is notnull. A java.lang.NullPointerException is thrown if the given segment array is null.

disassembleContent (URL mediaLocation, byte[] mediaContent)

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

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

A javax.emb.FormatSyntaxException is thrown if the content does not match the

expected media format. A javax.emb.LinkTranslationException is thrown if the givenmedia location is null and the given content contains child links that are not URLs. A java.lang.NullPointerException is thrown if the content passed isnull.

extractHeader (InputStream content)

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

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

A javax.emb.FormatSyntaxException is thrown if the given media content does not matchthe syntax defined for the receiver. A javax.emb.FormatFeatureException is thrown if theheader cannot be extracted because a vital feature of the media format involved is notsupported. A java.lang.NullPointerException is thrown if the value passed is null.

extractProxy (InputStream content)

Extracts a proxy from the given media content and returns it. The proxy may be of anymedia format. For example, a key frame image may be returned in case of video


22/72


21

content, a waveform image in case of audio content, or a thumbnail in case of imagecontent. In case there ! s a problem creating the surrogate, a default format specific proxy

must be returned " for example GenericMediaFormat.GENERIC_PROXY . Pleasenote that the given input stream is closed once the operation is completed.

A java.lang.NullPointerException is thrown if the argument passed isnull.

getDefaultMimeType ()

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

isEmbedded ()Returns false if the media format allows links to external media, or true otherwise. It canbe 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 havingchild and/or parent dependencies to other media objects.

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 thepossibility to stream them with a Real player. Servlets can use this information to decidewhether they should try to stream content or transfer it using burst transfer instead.

4.4 javax.emb.GenericMediaFormat

This class offers a generic implementation of the MediaFormat interface for use with allkinds of embedded media formats. Note that this class should not be used to representnon-embedded media formats, as it does not handle parent/ child relationships. Byregistering instances of this class with the MediaFormatRegistry described in the follow-up section, various media formats can be supported in case no format specific support isavailable.

The public constant DEFAULT_PROXY contains an image that can be used as a defaultproxy for all kinds of media formats or in case the generation of a proxy fails forwhatever reason.

public class GenericMediaFormat implements MediaFormat {

public static final Media DEFAULT_PROXY;

byte[] assembleContent(URL, MediaSegment[]) throws MediaException;

MediaSegment[] disassembleContent(URL, byte[]) throws MediaException;

MediaHeader extractHeader(InputStream) throws MediaException;

Media extractProxy(InputStream) throws MediaException;

String getDefaultMimeType();

boolean isEmbedded();

boolean isStreamingDesirable();

}


23/72


22

assembleContent (URL mediaLocation, MediaSegment[] mediaSegments)

Returns the content of the given media segment array!

s first element, or an empty bytearray if no element is passed.

A javax.emb.FormatSyntaxException is thrown if the given media segment array containsmore than one element, or if an element is passed that contains a child link that is notnull. A java.lang.NullPointerException is thrown if the given segment array is null. A

javax.emb.ContentTooLargeException is thrown if the assembled content is larger thanthe maximum Java array size of 2 GB.

disassembleContent (URL mediaLocation, byte[] mediaContent)

Disassembles the given media content. As embedded media doesn ! t contain any linksand therefore consists of a single media segment, this generic implementation returns aone-element array of media segments, with a segment element composed of null as

child location and the given media content as content.

A java.lang.NullPointerException is thrown if the content passed isnull.

extractHeader (InputStream mediaContent)

Returns an instance of class GenericMediaHeader, as this class cannot make anyassumptions about header fields.

A java.lang.NullPointerException is thrown if the value passed isnull.

extractProxy (InputStream mediaContent)

Returns a default image that is suitable to represent all kinds of content.

getDefaultMimeType ()

Returns Media.MIME_TYPE_UNKNOWN, as this class cannot make any assumptionsabout mime types.

isEmbedded ()

Returns true, as this class assumes media to be embedded.

isStreamingDesirable ()

Returns false, as this class cannot make any assumptions about media to be streamableor not.

4.5 javax.emb.MediaFormatRegistry

This singleton class manages the different header types and allows the generic selectionof a format bean suitable for a given media. The selection criterion is the file extensionassociated with the media, and a media format can be registered multiple times if manyfile extensions are typically associated with it.

The class has a private default constructor to prevent direct construction of instances inapplications. Instead, the SINGLETON constant provides the one and only instance of


24/72


23

this class. Implementations are free to initialize the registry with mappings of theirchoice. However, the design allows applications to plug in additional mappings.

bind (String fileExtension, MediaFormat mediaFormat)This operation associates the given file extension with the given media format instance.

A javax.emb.FormatAlreadyBoundException is thrown if a mapping already exists for thegiven file extension. A java.lang.NullPointerException is thrown if one of the valuespassed is null.

getFileExtensions()

This operation returns the file extensions for which bindings exist in the registry.

rebind (String fileExtension, MediaFormat mediaFormat)

This operation associates the given file extension with the given media format instance.If a mapping already exists for the given file extension, it is replaced by the new one.

A java.lang.NullPointerException is thrown if one of the values passed isnull.

unbind (String fileExtension)

This method removes the mapping defined by the given file extension.

A javax.emb.FormatNotFoundException is thrown if there is no mapping for the givenfile extension. A java.lang.NullPointerException is thrown if the value passed isnull.

lookup (String fileExtension)Returns the media format instance registered under the given file extension.

A javax.emb.FormatNotFoundException is thrown if there is no mapping for the givenfile extension. A java.lang.NullPointerException is thrown if the value passed isnull.

4.6 javax.emb.MediaSegment

This class models a portion of a (usually non-embedded) medium that is optionallyfollowed by a reference to an externalmedia file represented by a media locationURL. The EBNF grammar to the right

Medium := { MediaSegment }MediaSegment := content [ childLocation ]

Figure 8: Me ia segment e initio

public final class MediaFormatRegistry {

public static final MediaFormatRegistry SINGLETON;

private MediaFormatRegistry();

public void bind(String, MediaFormat) throws FormatAlreadyBoundException;

public Iterator getFileExtensions();

public MediaFormat lookup(String) throws FormatNotFoundException;

public void rebind(String, MediaFormat);

public void unbind(String) throws FormatNotFoundException;

}


25/72


24

illustrates the relation between media objects and media segments.

Splitting up media content into media segments is useful if references contained have tobe updated, for example because one of the children has moved. In order to handlesuch a situation it is necessary to disassemble the media, update the reference, andreassemble it afterwards. MediaFormat instances provide the operations necessary, andthe MediaSegment class describes the data container for a single segment.

The value null is a valid value for the childLocation property and indicates that thesegment content is not followed by any reference, for example because the end ofmedia is reached. The content of media segments is restricted to a theoretical maximumsize of 2GB due to the Java restriction of byte array size. However this should notimpose a restriction in practice as non-embedded media tends to be fairly small in size,and embedded media doesn! t require segmentation at all.

Media segments also implement java.io.Serializable in order to allow instances to beexchanged over remote boundaries.

MediaSegment()

Default constructor for media segments. The content field is initialized to an empty bytearray, and the child location field is initialized to null.

getContent ()

Returns the content of the media segment as a byte array.

getChildLocation ()

Returns the media location of a media resource referenced by the receiver.

setContent (byte[] content)Sets the content of the media segment.


setChildLocation (URL childLocation)

Sets the media location of a media resource referenced by the receiver. Passing the valuenull is allowed.

public class MediaSegment extends java.io.Serializable {

public MediaSegment();

public byte[] getContent();

public URL getChildLocation();

public void setContent(byte[]);

public void setChildLocation(URL);

}


26/72


25

4.7 javax.emb.MediaHeader

The interface MediaHeader defines the common behavior between media headerimplementations. All media header instances must allow access to the format specificheader fields by name, in order to allow easy generic access in case some information isrequired for browsing purposes. Additionally, all header fields accessible by theMediaHeader.getField(String) method must be accessible by standard getter methods, too. Asmedia header instances have to be transferred over machine boundaries at times, thisinterface extends java.io.Serializable.

getFieldNames ()

Returns an array of Strings containing all the field names defined for the header.

getField (String fieldName)

Returns the field with the given name downcast to java.lang.Object. If the field ismodeled as a Java base type, an instance of the corresponding wrapper class has to bereturned. The value null is returned if a field name is passed that is not defined for thereceiver.


4.8 javax.emb.GenericMediaHeader

This class offers a generic implementation of the MediaHeader interface. It is suitable forall kinds of media that don! t expose any header information.

getFieldNames ()

Returns an empty array of Strings, as no header information is exposed.

getField (String fieldName)

Returnsnull regardless of the field name passed.


public interface MediaHeader extends Serializable {

String[] getFieldNames();

Object getField(String);

}

public class GenericMediaHeader implements MediaHeader {

public String[] getFieldNames();

public Object getField(String);

}


27/72


26

4.9 javax.emb.MediaConverter

A media converter performs actual conversions of media content. Implementations ofthis interface can work in one of two ways: Synchronous converters perform conversionscompletely before returning the input stream on the converted content. Asynchronousconverters return a piped input stream immediately after checking the input andspawning a new thread to perform the conversion. The latter has the advantage of being

very memory efficient in case the result is consumed immediately, while the first tends tobe more robust because it doesn ! t require the maintenance of additional threads ofexecution.

The design assumes a converter is instantiated for a specific kind of conversion.Therefore, classes implementing this interface should take a media converter spec as aconstructor argument. Said media converter spec should contain the necessaryconversion parameters, for example the desired bandwidth for a WAV to MP3 converter.

process (InputStream inputStream)

Converts the media content offered on the given input stream and returns the convertedmedia content as an input stream. Implementations of this method may, but are notrequired to, spawn a new thread to perform the actual conversion, and return aPipedInputStream immediately.

A java.lang.NullPointerException is thrown if the value passed is null. A javax.emb.FormatSyntaxException is thrown if the content provided with the inputstream does not meet the expected format syntax. A javax.emb.FormatFeatureExceptionis thrown if the content provided in the input stream uses a format feature not supportedby the receiver. A javax.emb.LinkTranslationException is thrown if the content providedcontains relative links to child media objects. A javax.emb.ContentAccessException isthrown if an I/O problem occurs or if said child links cannot be resolved to child mediacontent. A javax.emb.ConversionException is thrown if the conversion fails because aconversion specific problem occurred.

process (InputStream inputStream, OutputStream outputStream)

Converts the media content offered on the given input stream and writes the converted

media content on the given output stream. In any case, this method will block until theconversion is completed.

A java.lang.NullPointerException is thrown if one the values passed is null. A javax.emb.FormatSyntaxException is thrown if the content provided with the inputstream does not meet the expected format syntax. A javax.emb.FormatFeatureExceptionis thrown if the content provided in the input stream utilizes a format feature notsupported by the receiver. A javax.emb.LinkTranslationException is thrown if the contentprovided contains relative links to child media objects. A

javax.emb.ContentAccessException is thrown if an I/O problem occurs or if said childlinks cannot be resolved to child media content. A javax.emb.ConversionException isthrown if the conversion fails because a conversion specific problem occurred.

public interface MediaConverter {

InputStream process (InputStream) throws MediaException;

void process (InputStream, OutputStream) throws MediaException;

}


28/72


27

4.10 javax.emb.MediaConverterSpec

An instance of a class implementing this interface collects all properties necessary toperform a conversion from a specific source format to a specific target format. One ormore converter spec classes correspond to one converter class, and the contract foraccessing the conversion parameters is up to the implementers of the converter specclasses.

A conversion spec instance can be reused for multiple conversions. Also,implementations of this interface must provide a default constructor that initializes allproperties with suitable values, in order to allow default conversions. As converter specssometimes have to be transferred over machine boundaries, this interface extends

java.io.Serializable. The design allows various parties to come up with implementationsfor various combinations of media formats.

getConverter ()

Returns an object implementing the MediaConverter interface that can be used toprocess conversions using the receiver. The instance returned is initialized with thereceiver to define the conversion specific parameters.

A javax.emb.ConversionException is thrown if the instantiation of the converter fails.

getTargetMimeType ()

Returns a MIME type as a String that can be used as a default for media objects createdusing the receiver. A result of null indicates that the receiver does not alter the mediaformat of the content offered on the given input stream.

getTargetFileExtension ()

Returns a file extension as a String that can be used as a default for media objectscreated using the receiver. The String must not include any separator characters. A resultof null indicates that the receiver does not alter the media format of the content offeredon the given input stream.

public interface MediaConverterSpec extends Serializable {

MediaConverter getConverter() throws MediaException;

String getTargetFileExtension();

String getTargetMimeType();

}


29/72


28

4.11 javax.emb.MediaException

This exception is root to most application specific exceptions thrown by EnterpriseMedia Beans components. The idea is to abstract over the specific causes of exceptionalbehavior as the causes of such behavior can differ a lot between different EnterpriseMedia Beans implementations. As this would prevent applications to be written in animplementation independent way, these causes have to be mapped to a unifiedexception model.

There are various subclasses of this exception class to distinguish specific exceptioncauses. Media Format Beans use the exception classes below, while some more aredefined with Media Entity Beans in the next chapter. Note that the additional exceptionconstructors defined in JDK 1.4 are provided in order to enable consistent exceptionchaining.

4.12 javax.emb.ContentAccessException

This exception extends javax.emb.MediaException and is thrown whenever access to

media content fails, be it because a file is not found, there's missing access rights to a fileor subsystem, a subsystem or file is temporarily blocked for access, or contenttransmission fails.

4.13 javax.emb.MediaFormatException

This exception extends javax.emb.MediaException and is thrown whenever a problemoccurs in dealing with a media format. Usually, this exception is not thrown directly.Instead, instances of its subclasses are thrown to indicate a more specific reason for theproblem. Standardized subclasses of this exception class are

javax.emb.FormatSyntaxException, javax.emb.FormatFeatureException, javax.emb.FormatNotFoundException and javax.emb.FormatAlreadyBoundException.

4.14 javax.emb.ContentTooLargeException

This exception extends javax.emb.MediaException and is thrown whenever the creationof a byte array is attempted that exceeds 2GB in size (the current hard limit of byte arraysize in Java).

public class MediaException extends Exception {

MediaException();

MediaException(String);

MediaException(String, Throwable);

MediaException(Throwable);

}


30/72


29

4.15 javax.emb.ConversionException

This exception extends javax.emb.MediaException and is thrown if the actual conversionof media content from one format to another fails and the reason for this is not related tothe media formats involved, but rather because of a limitation of the converter. Forexample, a BMP to JPEG converter can fail because it does not support a specific formatfeature in the source, while the format bean handling the input format itself may wellsupport this feature.

4.16 javax.emb.FormatAlreadyBoundException

This exception extends javax.emb.MediaFormatException and is thrown whenever amedia format cannot be bound to the media format registry because another media

format instance is already bound for the file extension specified.

4.17 javax.emb.FormatFeatureException

This exception extends javax.emb.MediaFormatException and is thrown whenever mediacontent matches the overall syntax defined for a media format, but uses a feature that isnot supported by the media format implementation, for example a specific sub-format.For example, a format bean for the BMP format that supports Windows BMP format onlywill throw such an exception when analyzing a BMP object featuring OS/2 BMPdefinitions.

4.18 javax.emb.FormatNotFoundExceptionThis exception extends javax.emb.MediaFormatException and is thrown whenever amedia format cannot be determined. Usually the media format registry throws thisexception.

4.19 javax.emb.FormatSyntaxException

This exception extends javax.emb.MediaFormatException and is thrown whenever mediacontent does not match the syntax defined for its media format.

4.20 javax.emb.LinkTranslationExceptionThis exception extends javax.emb.MediaException and is thrown whenever a problemoccurs translating a child link contained in non-embedded media content into a locationURL or vice versa, for example because a relative filename is present when only absolutelinks are allowed.


31/72


30

4.21 javax.emb.MalformedLocationException

This exception extends javax.emb.MediaException and is thrown if a location URL is nota valid URL, or if it does not have a supported protocol type (like example "file").


32/72


31

Chapter 5 Media Entity Beans

Media Entity Beans are based on EJB entity beans and are designed to be implementedwith either container-managed persistence (CMP), bean managed persistence (BMP), or acombination of both. At the core they are media entity EJBs, which model media that ispersistent and mutable. They extend the services offered in the basic javax.emb.Mediainterfaces with parent/child relationship management for non-embedded media,metadata management, version management, and a media listener for extendibility.

Media Entity Beans allow a tight integration of rich media data into the EJB programmingmodel as they extend the standard EJB transaction and security models to media data

and can be included directly in EJB entity bean relationships. Also, they offer a powerfulabstraction over server side protocol handlers like stream servers, which removesdependencies from applications.

Media Entity EJBs can be extended by using media listeners, custom persistent observersthat are notified of changes in the persistent state of Media Entity EJBs. For example,media listeners can be used to trigger recalculations in depending business objects, cleanup related resources if a media entity EJB is removed, or count access to the entity iffulfillment or monitoring is required.

Additionally, Media Entity EJBs relate to MetaData Entity EJBs that model XML metadata.Such metadata can be used for XPATH or full text based queries. The design is both

utiliz

Constraints

observ

*1

MediaEntity

Media Entity EJ

MediaEntityLocalHom

MediaEntityLocal

Figure 9: Media Entity Beans components and interactions

MediaListener

Meta Data Entity EJB

MetaDataEntityLocaHo

MetaDataEntityLoca

content /metadata

*

0 .. 1

0 .. 1

predecessor/ successor

0 .. 1

0 .. 1

*

0 .. 1

parent /chil

original /proxy

*

*

*

0 .. 1

parent /chil


33/72


32

open and pluggable; it allows implementations to support multiple query languages,which makes sure existing and upcoming standards for said can be supported.

Media entity EJBs also maintain some relationships among each other:

§ Parent/ child relations model the relationship between non-embedded content andthe files referenced from within it. Every parent can have many children, and everychild can have many parents. The Parent / child relationship is maintainedautomatically by parsing (assembling / dissembling) content once it is inserted, usingsome of the format related function introduced in the Media Foundation Beans.

§ Original / proxy relationships allow content to be associated with a representative,like a thumbnail, sound bite, key frame, etc. Furthermore, implementations of thisspecification may choose to generate and cache representatives automatically.

§ Predecessor / successor relationships offer simple versioning support.

Although it would have been nice to have both local and remote interface definitions forthe API, it is limited to local interfaces only. The reason for this is that many methodnames would have had to be duplicated in case local and remote methods onlydistinguish themselves with their return types (local and home interface types). As thisbecame too complicated to use and with the industry moving away from using remoteentity bean interfaces, we decided to restrict the API to local interfaces only. If anapplication needs to invoke the methods remotely, a stateless session bean facade canbe used to do so.


34/72


33

5.1 javax.emb.MediaEntityLocal

This basic interface extends the javax.emb.Media interface with behavior common to allkinds of media objects that are persistent and can be altered. It also extendsEJBLocalObject 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 contentcan become rather large, additional streaming I/ O accessors are provided in additionto 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) insize. Note that the presence of the content property does not mean animplementation has to load the media content into memory; as mostimplementations will avoid this to keep memory consumption at bay. Also note thatthe content property is correlated to the location property, i.e. the content propertycannot be set if the location property is set and vice versa. The default value for thisproperty isnull.

§ The location property allows a media entity to gain read access to externallymanaged content, as opposed to the content property which models internallymanaged content. For example, a location URL can point to an HTTP site that hostsan image. If the location property is set, read access to the content is possible, butall operations requiring write access to the content will fail. The location property iscorrelated 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 isnull.§ 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 animage 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 contenthas to be exported to a file. The media format of a media entity EJB is derived fromthe file name extension. The default value for this property is null.

§ The mimeType property is used to hint web application programmers of whichmime type to use when transferring content directly over HTTP. The default value

Media Entity EJ

content

location

description

name

mimeType

Figure 10: Media Entity EJB alterable properties


35/72


34

for this property is null, but unless both the mimeType and name properties arenull the mimeType accessor will provide a format specific default mime type.

Note that the following method descriptions repeat the javax.emb.Media methoddescriptions in italics for convenience.

addListener (MediaListener listener)

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

public interface MediaEntityLocal extends EJBLocalObject, Media {

void addListener(MediaListener) throws MediaException;

void addMetaData(MetaDataEntityLocal) throws MediaException;

void convert(MediaConverterSpec[]) throws MediaException;

URL exportMedia(URL) throws MediaException;

MediaEntityLocal[] getChildren() throws MediaException;

byte[] getContent() throws MediaException;

String getDescription() throws MediaException;MediaFormat getFormat() throws MediaException;

MediaHeader getHeader() throws MediaException;

long getLastModified() throws MediaException;

MediaListener[] getListeners() throws MediaException;

URL getLocation() throws MediaException;

MetaDataEntityLocal[] getMetaData() throws MediaException;

String getMimeType() throws MediaException;

String getName() throws MediaException;

MediaEntityLocal getNextVersion() throws MediaException;

MediaEntityLocal[] getParents() throws MediaException;

MediaEntityLocal getPreviousVersion() throws MediaException;

Media getProxy() throws MediaException;

long getSize() throws MediaException;

void importMedia(URL, String) throws MediaException;



void removeListener(MediaListener) throws MediaException;

void removeMetaData(MetaDataEntityLocal) throws MediaException;

void setChildren(MediaEntityLocal[]) throws MediaException;

void setContent(byte[]) throws MediaException;

void setContent(InputStream) throws MediaException;

void setDescription(String) throws MediaException;

void setLocation(URL) throws MediaException;

void setMimeType(String) throws MediaException;

void setName(String) throws MediaException;void setPreviousVersion(MediaEntityLocal) throws MediaException;

void setProxy(MediaEntityLocal) throws MediaException;

}


36/72


35


addMetaData (MetaDataEntityLocal metaData)

Adds the given metadata to the receiver ! s list of associated metadata. Metadata consistsof XML content that has been stored in separate MetaDataEntity EJBs. Severalapplications can associate XML metadata with a single media entity. If the givenmetadata EJB is already part of the receiver !s list of metadata entities, no action isperformed.


convert (MediaConverterSpec[] specifications)

This operation updates the receiver's content after performing a series of transformationson 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 allowsmodification 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 implicitlyupdates the receiver !s lastModified property. Also note that this operation will fail if thelocation property is set.

A java.lang.NullPointerException is thrown if the value passed is null. A javax.emb.ContentAccessException is thrown in case the content cannot be accessed. A javax.emb.ContentUnmutableException is thrown if the location property is not null. A javax.emb.MediaFormatException is thrown in case a problem occurs handling thedifferent media formats involved. A javax.emb.ConversionException is thrown if one ofthe conversions fails. A javax.emb.ListenerVetoException is thrown if a media listener

vetoes the change. A javax.emb.ContentTooLargeException is thrown if the content

generated is larger than supported by the implementation.

exportMedia (URL targetDirectoryLocation)

Copies the receiver !s content to the given target directory location, a URL pointing to adirectory. If null is passed, the content is exported to a default directory. The URL mustbe of protocol type #file$ or any additional protocol supported by the implementation. Incase of non-embedded media formats, the content of related children is also recursivelycopied into the same directory or one of its subdirectories. Implementations mustguarantee that no existing files are overwritten during execution, i.e. they must resolvenaming 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 toknow in case a directory location was given, or the location given pointed to an existing

file.

A javax.emb.ContentAccessException is thrown if the content cannot be stored at thegiven target location, or if the content transfer fails. A

javax.emb.MalformedLocationException is thrown if the given target location ismalformed or the given protocol is not supported. An instance of a subclass of

javax.emb.MediaFormatException is thrown if there is a problem dealing with one of themedia formats involved.


37/72


36

getChildren ()

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

Note that in case of non-embedded media formats a change of the media content canimplicitly alter the set of children. Also note that altering the resulting array content willnot 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.

getContent ()

Returns the complete media content as a byte array. This method is intended forconvenient access to media content up to a few MB in size. Streaming I/O access asdefined in readContent() should be used to access large content instead.

Note that the value returned may be based either on the content property or the locationproperty in case the implementation is able to access the content referenced by thelatter.

If the resulting byte array size exceeds the theoretical maximum Java array size of 2 GB,a javax.emb.ContentTooLargeException is thrown. A javax.emb.ContentAccessExceptionis thrown if the content is null or cannot be accessed.

getDescription ()

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

getFormat ( )

Queries a suitable media format instance from the MediaFormatRegistry singleton andreturns it. The file extension contained in the name property is used as a key for thisquery.

A javax.emb.FormatNotFoundException is thrown if the file extension is not registeredwith the media format registry or if the name property is null.

getH eader ()

Returns the receiver's header information. Queries a suitable media format instance fromthe MediaFormatRegistry singleton and determines the header information based on it.

A javax.emb.FormatNotFoundException is thrown if the file extension is not registeredwith the media format registry. A javax.emb.FormatSyntaxException is thrown if thereceiver ! s content does not match the syntax defined for the receiver ! s media format. A

javax.emb.FormatFeatureException is thrown if the header cannot be extracted because a vital feature of the media format involved is not supported.

getLastModified ()

Returns a timestamp stating when the receiver's persistent state was last modified. Notethat relationships are not considered part of the persistent state and therefore don ! taffect the value of this property.


38/72


37

getListeners ()

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

getLocation ()

Returns the location of the media content as an instance of java.net.URL or null if nolocation has been set.

getMetaData ()

Returns the receiver !s associated metadata as an array of MetaDataEntity EJBs. Metadataconsists of XML content that has been stored in separate MetaDataEntity EJBs. Severalapplications can associate their metadata with a single MetaDataEntity EJB. An empty

array is returned if no metadata has been set.

getM imeType ()

Returns a mime type for the receiver's content as a string. This allows media content tobe written directly to a Servlet output stream, as this technique requires a mime type tobe specified in case the output is different from HTML. . If no mime type has been setexplicitly a default mime type is returned, possibly based on the receiver ! s format.

A javax.emb.FormatNotFoundException is thrown if the mimeType property isnull andno format