Java Specification Request 086 Enterprise Media BeansTM ...

Java Specification Request 086 

Enterprise Media Beans TM Specification, 

Version 1.0, Final Release 

This is the specification of the Enterprise Media Beans’ architecture. The Enterprise Media Beans 

architecture allows the seamless integration of rich media data like audio, video, image and component 

document formats into applications based on the J2EE’ programming model. Applications written 

using 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 on 

any 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: 

sbaumei@de.ibm.com (Sascha Baumeister, spec lead) 

caser@us.ibm.com (Ralph B. Case, maintenance lead) 


April 6, 2004

Enterprise Media Beans Specification 

Release 

Version 1.0, Final 

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 

1



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 

2



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 

3



Chapter 1 

Introduction 

This is the specification of the Enterprise Media Beans’ (EMB) architecture. The 

Enterprise Media Beans architecture is a component-based architecture that extends the 

J2EE and Enterprise JavaBeans’ architectures to allow the seamless integration of rich 

media data such as audio, video, image or component documents into J2EE’ 

technology based business applications. Such applications can be written once, and then 

deployed on any server platform that supports the J2EE and Enterprise Media Beans 

specifications. 

This specification is accompanied by a container independent reference implementation 

(RI) and a technology compatibility kit (TCK) able to test if an implementation is 

conforming this specification or not. Both the reference implementation and the 

technology compatibility kit are open source, published under Common Public License 

(CPL), and available at 

http://oss.software.ibm.com/developerworks/projects/embri for 

download. Container providers and 3 rd parties are invited to implement this specification 

if a quality of service exceeding the one provided in said reference implementation is 

desired. 

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. This 

specification is especially targeting, but is not limited to, the Enterprise JavaBeans part of 

the J2EE community. 

In this community, this document mainly targets vendors of EJB transaction processing 

platforms and vendors of enterprise application tools. However, the API sections of this 

specification may also be of interest for application programmers who want to use 

Enterprise 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 and 

invaluable input during the evolvement of Enterprise Media Beans. 

Thanks to Sarah Boaz, Frank Castaneda, Adam J. Goldman and Adrian G. Treuille for 

their dedication and creativity during the Enterprise Media Beans related IBM Extreme 

Blue 2000 internship in Boston. 

Special thanks also to Ann Black, Lan Vuong and Ralph Case for teaming up to finalize 

the reference implementation and the related test kit. 

Last but not least, we –d like to acknowledge the Enterprise JavaBeans 2.0 architects as 

we took parts of their document layout as a template for this specification. This should 

4



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 its 

components. 

Chapter 4 defines the Media Foundation Beans component of the Enterprise Media 

Beans 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 Beans 

architecture. This component is specifically targeting the Enterprise JavaBeans 

community. 

Chapter 6 provides some Servlet code snipplets illustrating the use of Enterprise Media 

Beans in J2EE based enterprise applications. 

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

documents. 

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 are 

depicted as regular rectangles; interfaces are depicted as rounded rectangles. 

5



Chapter 2 

Positioning 

Rich media data extends traditional computer data formats into more natural data formats 

for 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 recorded 

content. Storing, managing, rendering and integrating this kind of data seamlessly into 

business applications yields significant competitive advantage and the opportunity for 

new 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 media 

data in recent years. Usually, these products are developed around a specialized and 

proprietary database, make use of specialized and proprietary file systems and offer 

proprietary API – s and protocols to handle rich media data. 

Content Management Systems for instance are highly complex and heavyweight 

middleware with proprietary data stores and proprietary interfaces to store, retrieve and 

manage digital content. Streaming media solutions as another example are nonstandardized 

software products using proprietary protocols to transfer and render 

content such as audio and video on end users – systems. They mainly work with 

proprietary formatted content stored in plain files. Products within this fast emerging 

market come from companies like Real Networks, Microsoft, Apple, and IBM. 

This has a serious impact on enterprise customers who are interested in incorporating 

rich 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 to 

migrate from those products later. The integration of standard business applications with 

products 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 data 

management systems. Caching or replication of media data throughout customer 

intranets is either not handled at all or based on proprietary solutions or stream server 

providers. Also, there is no unified mechanism for authorization and transactional 

behavior 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 a 

possibility of maintaining it, using their existing data administration tools and 

procedures. In other words, rich media data needs to be treated as just another data type 

that is handled similarly to structured data within the application layer. Enterprise Media 

Beans addresses these rich media related problems within the J2EE community. 

6



2.1 Java Media Framework TM 

The Java Media Framework models rich media primarily from the functional perspective 

of capturing, processing and playing back streaming media. It is mainly based around 

the concept of constructing customized media players in Java in a platform independent 

way, thereby targeting the distributed programming model (J2SE “ applets and 

applications). In contrast, Enterprise Media Beans come from a data model perspective, 

thereby targeting integration of rich media and relational data in the server-centric 

programming model (J2EE, Servlets, JSPs, EJBs). 

The Java Media Framework is targeted at streaming media capture and playback and has 

as its strength the means to handle rich media that is composed of tracks of content to 

be 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 of 

several possible ways to manage persistent rich media data. 

There is real synergism possible between JMF and EMB when it comes to transcoding 

and conversion of rich media data. The JMF processor model allows JavaBeans to be 

developed that perform transcoding and conversion. JMF-based converters and 

transcoders implemented as JavaBeans can be incorporated into Enterprise Media. As 

this part of the Java Media Framework doesn –t seem to be specifically tailored to the 

distributed programming model, Enterprise Media Beans transcoders and converters are 

implementable based on the Java Media Framework. However, Enterprise Media Beans 

does not architect the internals of such implementations and therefore also allows the 

integration 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 FileNet TM content management system and IBM – s Content Manager TM . Content 

management systems focus on management and query aspects of rich media, like 

distribution of content over the network and federated content search algorithms. 

As the requirements for rich media related data depend highly on the use case scenario 

and the kind of media involved, the APIs available with these systems tend to be rather 

complicated and large. Also, content management systems tend to integrate rather poorly 

with J2EE, especially when it comes to backup/restore, security, and transactions. In 

particular, EJB security credentials and transaction concepts are not compatible with 

those in content management systems, if present at all. 

Enterprise Media Beans is intended to be a lightweight, standardized middleware that 

can be used with or without an underlying content management system to seamlessly 

integrate rich media data into a J2EE environment. On one hand, it can be implemented 

on top of a relational database system in conjunction with file system to provide support 

for a variety of platforms. On the other hand, a specific content management system can 

be encapsulated as a data store for Enterprise Media Beans. 

7



2.3 Java Content Repository (JSR170) 

The Java Content Repository is a work in progress unifying the APIs for content 

management systems. The positioning between this API and Enterprise Media Beans is 

highly similarly to the positioning between JDBC and EJBs, i.e. Java Content Repository 

provides the data access function and data model, whereas Enterprise Media Beans 

provides the integration into the J2EE/EJB component model. Specifically, Enterprise 

Media Beans can be implemented on top of Java Content Repository compliant content 

management systems. 

Also similarly to the relation between EJBs and JDBC, we target an evolution of function 

being 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, like 

Microsoft Windows Media Services TM , RealNetworks RealSystem TM , Apple Quicktime TM , 

IBM VideoCharger TM , or Nullsoft Winamp TM . Most of them feature a unique proprietary 

player. This technique is an optimization of the traditional way to handle data, which is 

to first transfer the streaming media over a network and to store it locally on the client 

completely before presenting it. Streaming technology always requires a pair of 

components to work together: On the server side a stream server component is required 

to stream the data onto the network. On the client side a player is required that is able 

to immediately process and present rich media data stream right when it arrives over the 

network. 

In order to initiate streaming with a media player, a file is often required containing a 

pointer 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 a 

file is commonly referred to as a metafile, and 

its format is specific to the kind of stream 

server used. To the right is a typical sample 

content of a RealNetworks TM metafile (”.ram 

file). 

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

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

Figure 1: Sample streaming metafile 

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 to 

the lack of accepted standards, stream server and media player components are strongly 

coupled by proprietary protocols and therefore don –t work with components of other 

vendors in the majority of cases. Enterprise Media Beans addresses the heterogeneity 

and proprietary nature of streaming media client/server systems by encapsulation. Thus, 

enabling e-business applications to be developed on the J2EE platform without having to 

deal with the vendor-specific characteristics of the stored streaming media content and 

installed streaming media servers. 

Since Enterprise Media Beans abstract over streaming-media-based products, they in 

effect represent a J2EE middleware extension for managing and delivering distributed 

8



streaming media content. EMB enables enterprise Java applications to be developed that 

have no dependency on the type of specific streaming technology installed. 

9



Chapter 3 

Architecture 

The J2EE TM architecture consists of components that help developers to create enterprise 

business applications that conform to the Model-View-Controller paradigm within the 

server-centric programming model. With the exception of the Servlet TM and Java 

ServerPages TM components (which deal with view and controller aspects), all J2EE 

functionality can be applied in two forms: either separately by adding atomic 

components like JDBC TM , JMS TM or JTS TM to enrich applications with specific services, or 

by using Enterprise JavaBeans TM that integrate all this into a single architecture. 

Therefore, J2EE applications significantly differ in either utilizing Enterprise JavaBeans 

technology or not. 

Enterprise Media Beans target 

the seamless integration of rich 

Enterprise Media Beans 

media data into applications 

based on the J2EE programming 

Media Foundation Media Entity 

model. As such applications 

Beans 

Beans 

come in two basic shapes as 

described above, the Enterprise 

Media Beans architecture is 

require 

require 

separated into two components 

require 

too: Media Foundation Beans 

require only basic Java 2 TM 

technology and can be used in Java 2 base 

EJB 2.0 

any kind of J2EE application. In 

Technology 

Entity Beans 

contrast, Media Entity Beans rely 

on EJB entity beans and are Figure 2: Enterprise Media Beans components and dependencies 

therefore of interest only for 

applications based on the Enterprise JavaBeans architecture. 

3.1 Media Foundation Beans 

Media Foundation Beans provide definitions for basic media related services in a servercentric 

programming model. These services specifically target media objects that are 

possibly 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 information 

without the need of programming against platform specific interfaces, and some other 

services required when integrating rich media data into J2EE based applications. Media 

headers can be used to dynamically calculate information about a media object instead 

of storing said information redundantly in a database. For example, if a Servlet wants to 

display song length and sampling rate information about MP3s, this information can 

easily be extracted from MP3 files. Extracting link information from non-embedded 

media 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, 

10



applications transcoding media objects can use this in order to meet format requirements 

of 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 for 

transcoding, i.e. analyzing a given client – s capabilities and determining which 

conversions are necessary to render a given media object on said client. However, as 

standards for formally describing and querying client capabilities are still evolving, the 

topic has been postponed to future versions of 

this specification. 

Both media formats and media converters are 

designed as a plug-in architecture, which means 

3 rd party implementations of these components 

can be used throughout all implementations of 

Media Foundation Beans. The reference 

implementation of this specification will come 

with specific support for those media formats that 

are 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 generically 

supported. 

Media Foundation Beans 

Media Format 

Plug 

plug-in 

3rd Party 

Implementatio 

n 

Media 

Converter 

Plug 

plug-in 

3rd Party 

Implementatio 

n 

Figure 3: Media Foundation Beans 

plug-in architecture 

Media Foundation Beans offer a convenient and lightweight way to include basic rich 

media related services in J2EE applications. However, if EJB entity beans are used in 

such applications, the use of Media Entity Beans as described in the section below 

should be preferred. Media Entity Beans use the functionality provided by Media 

Foundation Beans. 

3.2 Media Entity Beans 

Media Entity Beans integrate the services provided by Media Foundation Beans into the 

Enterprise JavaBeans architecture, adding additional services that require media 

persistence. 

Core to Media Entity Beans is an EJB entity bean called media entity EJB. Each media 

entity EJB models a single medium that is persistent and mutable. One key design point 

of 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 media 

content 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 to 

many gigabytes in size, the freedom of choice in how to map media of various formats 

can have a significant impact on the overall system performance. 

Media Entity Beans are designed for either container-managed persistence or beanmanaged 

persistence which allows EJB deployers to map these EJBs to a custom data 

model or a content repository. 

This is important when it comes to backup/restore processes in enterprises, as consistent 

backups of the complete data model, including rich media, become possible. However, 

11



this requires the media content to be persisted using a technology supported by 

database backup/restore processes - like binary large objects or Datalinks. 

The key advantage of media entity EJBs is their tight integration into the EJB 

programming model. Media entity EJBs share the same transaction and security model 

with all other business entity beans of a complex, EJB based, enterprise application. 

Also, if packaged with a business application they can participate fully in EJB 

relationships, which is 

* 

1 .. * 

key to a seamless 

EmmyAward 

winner 

integration of 

Person 

information in EJB 

* 

participa 

1 

based enterprise 

1 .. * 

nt 1 .. * 

applications. 

poster 

The static structure 

diagram to the right 

depicts the model of a 

library application that 

maintains and presents 

information about 

Emmy awards. The 

media entity EJB 

participates in varying 

roles in relationships 

to multiple application 

specific EJBs. This 

allows a seamless 

integration of rich 

media data into this 

application –s EJB model. 

Series 

winner 1 

1 1 

1 

EmmyAsset 

1 * 

1 * 

background 

material 

Episode 

Figure 4: Media entity EJB participating in custom EJB relationships 

picture 

MediaEntity 

Apart from forming relationships with other EJBs, media entity EJBs can relate with other 

media entity EJBs. This is especially useful to guarantee referential integrity in case of 

non-embedded media formats. Non-embedded media contains links to external media 

resources, which require an understanding of the document format in question. 

1 

1 

vide 

o 

house.smi 

house.rt house.rp house.rm 

. . . 

image1.jpg image2.jpg image10.jp 

g 

Figure 5: Parent/child relationships among media entity EJBs 

Media Foundation Beans provide the 

necessary support and plug-in 

mechanisms for analyzing and 

generating the dependencies (links) 

between non-embedded media objects 

and their children, transform such links 

to child media objects into parent/child 

relationships between media entity 

EJBs, and manage these relations in 

case participants are moved or altered. 

The sample to the left shows the 

relations formed between various 

media entity EJBs after analyzing the 

non-embedded media files house.smi 

(SMIL format) and house.rp (RealPix 

format) recursively. 

12



Other relationships among media entity EJBs that are part of this specification are 

predecessor/successor relations between different editions of the ”same media and 

content/representant relationships between images and thumbnails. Of course, custom 

EJB models may define additional relationships among media entity EJBs. 

Also, media entity EJBs can be extended using a built-in persistent observer design. This 

allows application programmers to add custom behavior to various events in media 

entity EJBs, while remaining independent from a media entity EJBs implementation. For 

example, persistent observers allow application-specific relations that involve media 

entity 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 allows 

application-specific media entity extensions that are independent of the underlying 

media 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 being 

maintained 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 media 

entity EJBs have no hard dependencies on a specific stream server manufacturer or a 

proprietary transport protocol, both of which may become legacy in the future. 

Publishing a media entity to protocol servers will create managed copies of the media 

entity and all its children on said protocol server. In opposition to transferring content to 

a client as a Servlet response this has a number of advantages, both for embedded and 

non-embedded media types: 

• Publishing an embedded media object to stream servers allows streaming access to 

the media content, which dramatically reduces latency times in case the content is 

large. Also, no streaming metadata has to be maintained for the media entities as it is 

generated on the fly if necessary. 

• Publishing a non-embedded media object to stream servers allows streaming access 

to the media content and the content of all its direct or indirect children. Nonembedded 

media objects cannot be transferred to a client by Servlet response, such 

media objects always require publishing by nature. Again, no streaming metadata 

has 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 the 

media content, similar to transferring the content as a Servlet response. However, the 

network infrastructure can efficiently cache the content. 

• Publishing a non-embedded media object to an HTTP server allows burst access to 

the media content and the content of all its direct or indirect children. Again nonembedded 

media objects cannot be transferred to a client by Servlet response, and 

this method is preferred over publishing to a stream server in all cases where the 

size 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 depending 

on the kind of request. A meta-medium can be sent directly to a client as a Servlet 

response, and most stream servers allow meta-media to be playlists consisting of several 

media objects. In contrast, a URL has the advantage that it allows content to be 

embedded as part of an HTML page, for example using the HTML IMG element. Both 

kinds of results point to the media content published and contain additional information 

about a specific protocol server and a specific transport protocol to be used for content 

access. 

13



Of course, subsequent publish requests against the same media object are likely to be 

optimized by an EMB implementation. Also, note that the set of protocol servers 

supported is up to each implementation of this specification. 

Origin 

Server 

Protocol 

Server 

A 

B 

C 

Publishing A causes A, B, 

and C to be copied to the 

protocol server. Inside A – , 

the child links to B and C 

are replaced to protocol 

and server specific links to 

B – and C – . 

A 

– 

B 

– 

C 

– 

Figure 6: Publishing a non-embedded media object 

14



Chapter 4 

Media Foundation Beans 

Media Foundation Beans model basic operations on media within the server-centric J2EE 

programming model. With the exception of media header extraction they do not target 

the semantic understanding of the media content, but rather represent a syntactical 

approach in order to unify the way media is managed and handled. 

So far, the overall design of Media Foundation Beans is mainly driven by the 

requirements of Media Entity Beans. However, in the long run Media Foundation Beans 

are intended to offer services independently from Media Entity Beans, like transcoding 

support 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 nonembedded 

media content to an external resource, most likely a file. Such links come in 

two forms: Absolute links are always URLs and therefore contain all the information 

necessary to access external media content: access protocol, machine address, and 

access path. On the other hand, relative links only provide partial information, for 

example the full or partial access path in case of a file name. This means that the missing 

information required for access has either to be derived from the context, or has to be 

provided explicitly. 

MediaFormatRegistry 

manage 

MediaSegment 

MediaHeader 

GenericMediaFormat 

extract 

analyze 

MediaFormat 

extract 

GenericMediaHeader 

Media 

convert 

MediaConverter 

utilize 

MediaBean 

MediaConverterSpec 

Figure 7: Media Foundation Beans components and interactions 

15



4.1 javax.emb.Media 

This basic interface is used throughout Enterprise Media Beans to define the most 

common behavior for media objects. It defines the services common to all kinds of 

media objects, regardless of them being persistent or transient. 

There are basically two major ways to implement this interface. Media Entity Beans as 

described in chapter 5 deal with media content modeled as EJB entity beans, i.e. media 

that 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 interface 

extends java.io.Serializable, regardless of media being persistent or transient. Having the 

Media interface extend Serializable ensures that instances can be transferred over remote 

boundaries, for example using facade stateless session beans. 

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; 

} 

getContent () 

Returns the complete media content as a byte array. This method is intended for 

convenient access to media content up to a few MB in size. Streaming I/O access as 

defined 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.ContentAccessException 

is thrown if the content cannot be accessed. 

getFormat () 

Queries a suitable media format instance from the MediaFormatRegistry singleton and 

returns it. The file extension contained in the name property is used as a key for this 

query. 

A javax.emb.FormatNotFoundException is thrown if the file extension is not registered 

with the media format registry. 

getHeader () 

Returns the receiver's header information. Queries a suitable media format instance from 

the MediaFormatRegistry singleton and determines the header information based on it. 

16




with 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 to 

be written directly to a Servlet output stream, as this technique requires a mime type to 

be specified in case the output is different from HTML. If no mime type has been set 

explicitly 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 hint 

in case the media content is to be stored in a file system and therefore may only contain 

characters that are valid in file names. It contains a file extension that represents the 

receiver –s media format. 

getProxy () 

Returns a media object that can be used as a proxy for the receiver, e.g. a thumbnail, an 

icon, a short video/audio clip. Servlets can use this operation whenever a thumbnail or 

sound 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 the 

receiver –s content. 

readContent (long position, byte[] buffer) 

Similarly to input streams, this method fills the given buffer with content read from the 

media object. The media content is copied from the given position, and the buffer is 

filled 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 the 

implementation uses non-blocking I/O. The method returns the number of bytes copied 

into 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 or 

exceeding the content size. A java.lang.NullPointerExcetion is thrown if the given buffer 

is null. 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 the 


17



filled beginning from the given offset with a maximum amount of bytes defined by the 

given 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 nonblocking 

I/O. The method returns the number of bytes copied into the buffer, or “1 in 

case the given position equals the content size. 


exceeding the content size, or in case the given offset is negative or exceeding the buffer 

size. 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 be 

used 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 detail 

below. 

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; 



} 

MediaBean (InputStream contentStream, String mimeType, String name) 

This constructor initializes a new instance with content copied from the given content 

stream, 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 chosen 

automatically by analyzing the given file extension, or Media.MIME_TYPE_UNKNOWN is 

assigned in case none can be derived. 

This constructor is suitable for media content regardless of its size. Please note that the 

given input stream is closed once the content is read completely. Also note that a 

temporary file is used internally to maintain the content. The implementation tries to 

delete this file once the instance is garbage collected, and again once the process dies in 

case the former attempt fails. 

18



A javax.emb.ContentAccessException is thrown if something goes wrong during content 

transfer. A java.lang.NullPointerException is thrown if the given content stream or name 

is null. 

MediaBean (File mediaFile, String mimeType) 

This constructor wraps a new instance around the given media file. The name property 

of the receiver is initialized to the name of the given file (without path information). If 

the given mimeType is null, one is chosen automatically by analyzing the file 

extension, 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 file 

without copying the content of the latter. Please note that the file is not deleted once an 

instance referencing it is garbage collected. 

A javax.emb.ContentAccessException is thrown if something goes wrong during content 

transfer, or if the given file is not present or cannot be accessed. A 

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

4.3 javax.emb.MediaFormat 

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 class. As implementations of this interface may have to be 

transferred over remote boundaries at times, the MediaFormat interface extends 

java.io.Serializable. 

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(); 

} 

assembleContent (URL mediaLocation, MediaSegment[] mediaSegments) 

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 

19



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. 


a javax.emb.ContentTooLargeException is thrown. A LinkTranslationException is thrown 

if there –s a problem transforming one of the media segment child locations into a 

format specific link. In case of embedded media formats, a 

javax.emb.FormatSyntaxException is 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. 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 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. 

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

expected media format. A javax.emb.LinkTranslationException is thrown if the given 

media location is null and the given content contains child links that are not URLs. A 

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

extractHeader (InputStream content) 

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. 

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

the syntax defined for the receiver. A javax.emb.FormatFeatureException is thrown if the 

header cannot be extracted because a vital feature of the media format involved is not 

supported. 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 any 

media format. For example, a key frame image may be returned in case of video 

20



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. 

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

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. 

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. 

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. 

4.4 javax.emb.GenericMediaFormat 

This class offers a generic implementation of the MediaFormat interface for use with all 

kinds of embedded media formats. Note that this class should not be used to represent 

non-embedded media formats, as it does not handle parent/child relationships. By 

registering instances of this class with the MediaFormatRegistry described in the followup 

section, various media formats can be supported in case no format specific support is 

available. 

The public constant DEFAULT_PROXY contains an image that can be used as a default 

proxy for all kinds of media formats or in case the generation of a proxy fails for 

whatever 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(); 

} 

21



assembleContent (URL mediaLocation, MediaSegment[] mediaSegments) 

Returns the content of the given media segment array – s first element, or an empty byte 

array if no element is passed. 

A javax.emb.FormatSyntaxException is 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. 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 than 

the maximum Java array size of 2 GB. 

disassembleContent (URL mediaLocation, byte[] mediaContent) 

Disassembles the given media content. As embedded media doesn –t contain any links 

and therefore consists of a single media segment, this generic implementation returns a 

one-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 is null. 

extractHeader (InputStream mediaContent) 

Returns an instance of class GenericMediaHeader, as this class cannot make any 

assumptions about header fields. 

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

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 assumptions 

about 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 streamable 

or not. 

4.5 javax.emb.MediaFormatRegistry 

This singleton class manages the different header types and allows the generic selection 

of a format bean suitable for a given media. The selection criterion is the file extension 

associated with the media, and a media format can be registered multiple times if many 

file extensions are typically associated with it. 

The class has a private default constructor to prevent direct construction of instances in 

applications. Instead, the SINGLETON constant provides the one and only instance of 

22



this class. Implementations are free to initialize the registry with mappings of their 

choice. However, the design allows applications to plug in additional mappings. 

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; 

} 

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 the 

given file extension. A java.lang.NullPointerException is thrown if one of the values 

passed 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 is null. 

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 given 

file extension. A java.lang.NullPointerException is thrown if the value passed is null. 

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 given 

file extension. A java.lang.NullPointerException is thrown if the value passed is null. 

4.6 javax.emb.MediaSegment 

This class models a portion of a (usually non-embedded) medium that is optionally 

followed by a reference to an external 

Medium := { MediaSegment } 

media file represented by a media location MediaSegment := content [ childLocation ] 

URL. The EBNF grammar to the right 

Figure 8: Media segment definition 

23



illustrates the relation between media objects and media segments. 

Splitting up media content into media segments is useful if references contained have to 

be updated, for example because one of the children has moved. In order to handle 

such a situation it is necessary to disassemble the media, update the reference, and 

reassemble it afterwards. MediaFormat instances provide the operations necessary, and 

the MediaSegment class describes the data container for a single segment. 

The value null is a valid value for the childLocation property and indicates that the 

segment content is not followed by any reference, for example because the end of 

media is reached. The content of media segments is restricted to a theoretical maximum 

size of 2GB due to the Java restriction of byte array size. However this should not 

impose 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 be 

exchanged over remote boundaries. 

public class MediaSegment extends java.io.Serializable { 

public MediaSegment(); 

public byte[] getContent(); 

public URL getChildLocation(); 

public void setContent(byte[]); 

public void setChildLocation(URL); 

} 

MediaSegment() 

Default constructor for media segments. The content field is initialized to an empty byte 

array, 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 value 

null is allowed. 

24



4.7 javax.emb.MediaHeader 

The interface MediaHeader defines the common behavior between media header 

implementations. All media header instances must allow access to the format specific 

header fields by name, in order to allow easy generic access in case some information is 

required for browsing purposes. Additionally, all header fields accessible by the 

MediaHeader.getField(String) method must be accessible by standard getter methods, too. As 

media header instances have to be transferred over machine boundaries at times, this 

interface extends java.io.Serializable. 

public interface MediaHeader extends Serializable { 

} 

String[] getFieldNames(); 

Object getField(String); 

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 is 

modeled as a Java base type, an instance of the corresponding wrapper class has to be 

returned. The value null is returned if a field name is passed that is not defined for the 

receiver. 


4.8 javax.emb.GenericMediaHeader 

This class offers a generic implementation of the MediaHeader interface. It is suitable for 

all kinds of media that don– t expose any header information. 

public class GenericMediaHeader implements MediaHeader { 

} 

public String[] getFieldNames(); 

public Object getField(String); 

getFieldNames () 

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

getField (String fieldName) 

Returns null regardless of the field name passed. 


25



4.9 javax.emb.MediaConverter 

A media converter performs actual conversions of media content. Implementations of 

this interface can work in one of two ways: Synchronous converters perform conversions 

completely before returning the input stream on the converted content. Asynchronous 

converters return a piped input stream immediately after checking the input and 

spawning 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 to 

be more robust because it doesn –t require the maintenance of additional threads of 

execution. 

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 a 

constructor argument. Said media converter spec should contain the necessary 

conversion parameters, for example the desired bandwidth for a WAV to MP3 converter. 

public interface MediaConverter { 

InputStream process (InputStream) throws MediaException; 

void process (InputStream, OutputStream) throws MediaException; 

} 

process (InputStream inputStream) 

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

media content as an input stream. Implementations of this method may, but are not 

required to, spawn a new thread to perform the actual conversion, and return a 

PipedInputStream 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 input 

stream does not meet the expected format syntax. A javax.emb.FormatFeatureException 

is thrown if the content provided in the input stream uses a format feature not supported 

by the receiver. A javax.emb.LinkTranslationException is thrown if the content provided 

contains relative links to child media objects. A javax.emb.ContentAccessException is 

thrown if an I/O problem occurs or if said child links cannot be resolved to child media 

content. A javax.emb.ConversionException is thrown if the conversion fails because a 

conversion 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 the 

conversion 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 input 

stream does not meet the expected format syntax. A javax.emb.FormatFeatureException 

is thrown if the content provided in the input stream utilizes a format feature not 

supported by the receiver. A javax.emb.LinkTranslationException is thrown if the content 

provided contains relative links to child media objects. A 

javax.emb.ContentAccessException is thrown if an I/O problem occurs or if said child 

links cannot be resolved to child media content. A javax.emb.ConversionException is 

thrown if the conversion fails because a conversion specific problem occurred. 

26



4.10 javax.emb.MediaConverterSpec 

An instance of a class implementing this interface collects all properties necessary to 

perform a conversion from a specific source format to a specific target format. One or 

more converter spec classes correspond to one converter class, and the contract for 

accessing the conversion parameters is up to the implementers of the converter spec 

classes. 

A conversion spec instance can be reused for multiple conversions. Also, 

implementations of this interface must provide a default constructor that initializes all 

properties with suitable values, in order to allow default conversions. As converter specs 

sometimes have to be transferred over machine boundaries, this interface extends 

java.io.Serializable. The design allows various parties to come up with implementations 

for various combinations of media formats. 

public interface MediaConverterSpec extends Serializable { 

MediaConverter getConverter() throws MediaException; 

String getTargetFileExtension(); 

String getTargetMimeType(); 

} 

getConverter () 

Returns an object implementing the MediaConverter interface that can be used to 

process conversions using the receiver. The instance returned is initialized with the 

receiver 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 created 

using the receiver. A result of null indicates that the receiver does not alter the media 

format 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 objects 

created using the receiver. The String must not include any separator characters. A result 

of null indicates that the receiver does not alter the media format of the content offered 

on the given input stream. 

27



4.11 javax.emb.MediaException 

This exception is root to most application specific exceptions thrown by Enterprise 

Media Beans components. The idea is to abstract over the specific causes of exceptional 

behavior as the causes of such behavior can differ a lot between different Enterprise 

Media Beans implementations. As this would prevent applications to be written in an 

implementation independent way, these causes have to be mapped to a unified 

exception model. 

public class MediaException extends Exception { 

} 

MediaException(); 

MediaException(String); 

MediaException(String, Throwable); 

MediaException(Throwable); 

There are various subclasses of this exception class to distinguish specific exception 

causes. Media Format Beans use the exception classes below, while some more are 

defined with Media Entity Beans in the next chapter. Note that the additional exception 

constructors defined in JDK 1.4 are provided in order to enable consistent exception 

chaining. 

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 file 

or subsystem, a subsystem or file is temporarily blocked for access, or content 

transmission fails. 

4.13 javax.emb.MediaFormatException 

This exception extends javax.emb.MediaException and is thrown whenever a problem 

occurs 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 the 

problem. 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 creation 

of a byte array is attempted that exceeds 2GB in size (the current hard limit of byte array 

size in Java). 

28



4.15 javax.emb.ConversionException 

This exception extends javax.emb.MediaException and is thrown if the actual conversion 

of media content from one format to another fails and the reason for this is not related to 

the media formats involved, but rather because of a limitation of the converter. For 

example, a BMP to JPEG converter can fail because it does not support a specific format 

feature in the source, while the format bean handling the input format itself may well 

support this feature. 

4.16 javax.emb.FormatAlreadyBoundException 

This exception extends javax.emb.MediaFormatException and is thrown whenever a 

media 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 media 

content matches the overall syntax defined for a media format, but uses a feature that is 

not 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 only 

will throw such an exception when analyzing a BMP object featuring OS/2 BMP 

definitions. 

4.18 javax.emb.FormatNotFoundException 

This exception extends javax.emb.MediaFormatException and is thrown whenever a 

media format cannot be determined. Usually the media format registry throws this 

exception. 

4.19 javax.emb.FormatSyntaxException 

This exception extends javax.emb.MediaFormatException and is thrown whenever media 

content does not match the syntax defined for its media format. 

4.20 javax.emb.LinkTranslationException 

This exception extends javax.emb.MediaException and is thrown whenever a problem 

occurs translating a child link contained in non-embedded media content into a location 

URL or vice versa, for example because a relative filename is present when only absolute 

links are allowed. 

29



4.21 javax.emb.MalformedLocationException 

This exception extends javax.emb.MediaException and is thrown if a location URL is not 

a valid URL, or if it does not have a supported protocol type (like example "file"). 

30



Chapter 5 

Media Entity Beans 

Media Entity Beans are based on EJB entity beans and are designed to be implemented 

with either container-managed persistence (CMP), bean managed persistence (BMP), or a 

combination of both. At the core they are media entity EJBs, which model media that is 

persistent and mutable. They extend the services offered in the basic javax.emb.Media 

interfaces 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 programming 

model 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 powerful 

abstraction over server side protocol handlers like stream servers, which removes 

dependencies from applications. 

MediaEntity 

Constraints 

utilize 

MediaEntityLocal 

* 

* 

MetaDataEntityLocal 

original / 

proxy 

* 

* 

0 .. 1 

* 

MediaEntityLocalHome 

Media Entity EJB 

content / 

metadata 

0 .. 1 0 .. 1 

predecessor 

/ successor 

0 .. 1 0 .. 1 

0 .. 1 

* 

MetaDataEntityLocalHom 

e 

Meta Data Entity EJB 

parent / 

child 

parent / 

child 

MediaListener 

observ 

e 

1 

* 

Figure 9: Media Entity Beans components and interactions 

Media Entity EJBs can be extended by using media listeners, custom persistent observers 

that 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, clean 

up related resources if a media entity EJB is removed, or count access to the entity if 

fulfillment 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 

31



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 and 

the files referenced from within it. Every parent can have many children, and every 

child can have many parents. The Parent / child relationship is maintained 

automatically by parsing (assembling / dissembling) content once it is inserted, using 

some 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 this 

specification 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 for 

the API, it is limited to local interfaces only. The reason for this is that many method 

names would have had to be duplicated in case local and remote methods only 

distinguish themselves with their return types (local and home interface types). As this 

became too complicated to use and with the industry moving away from using remote 

entity bean interfaces, we decided to restrict the API to local interfaces only. If an 

application needs to invoke the methods remotely, a stateless session bean facade can 

be used to do so. 

32



5.1 javax.emb.MediaEntityLocal 

This basic interface extends the javax.emb.Media interface with behavior common to all 

kinds of media objects that are persistent and can be altered. It also extends 

EJBLocalObject and therefore represents the local interface of a media entity EJB. 

Media Entity EJB 

content 

location 

description 

name 

mimeType 

Figure 10: Media Entity EJB alterable properties 

Media Entity EJBs consist of the five basic alterable properties: 

• The content property models the byte content of a media entity EJB. As such content 

can become rather large, additional streaming I/O accessors are provided in addition 

to the standard set of get/set methods. The content length of a single media entity 

EJB is not limited to 2GB; it can theoretically be up to about 9 hexabytes (2^63) in 

size. Note that the presence of the content property does not mean an 

implementation has to load the media content into memory; as most 

implementations will avoid this to keep memory consumption at bay. Also note that 

the content property is correlated to the location property, i.e. the content property 

cannot be set if the location property is set and vice versa. The default value for this 

property is null. 

• The location property allows a media entity to gain read access to externally 

managed content, as opposed to the content property which models internally 

managed content. For example, a location URL can point to an HTTP site that hosts 

an image. If the location property is set, read access to the content is possible, but 

all operations requiring write access to the content will fail. The location property is 

correlated to the content property, i.e. the location property cannot be set if the 

content property is set and vice versa. The default value for this property is null. 

• The description property allows a textual description to be associated with a media 

entity EJB, for example to be displayed in conjunction with some thumbnail in an 

image list for orientation. The default value for this property is null. 

• The name property models a file name that is used as a default in case the content 

has to be exported to a file. The media format of a media entity EJB is derived from 

the file name extension. The default value for this property is null. 

• The mimeType property is used to hint web application programmers of which 

mime type to use when transferring content directly over HTTP. The default value 

33



for this property is null, but unless both the mimeType and name properties are 

null the mimeType accessor will provide a format specific default mime type. 

Note that the following method descriptions repeat the javax.emb.Media method 

descriptions in italics for convenience. 

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; 


String getDescription() throws MediaException; 



long getLastModified() throws MediaException; 

MediaListener[] getListeners() throws MediaException; 

URL getLocation() throws MediaException; 

MetaDataEntityLocal[] getMetaData() throws MediaException; 



MediaEntityLocal getNextVersion() throws MediaException; 

MediaEntityLocal[] getParents() throws MediaException; 

MediaEntityLocal getPreviousVersion() 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; 

} 

addListener (MediaListener listener) 

Adds the given listener to the list of persistent observers that are notified of important 

state changes or activities inside the receiver. If the given listener is already part of the 

receiver –s list of persistent observers, no action is performed. Note that listeners are 

distinguished using checks for content equality, not content identity. 

34




addMetaData (MetaDataEntityLocal metaData) 

Adds the given metadata to the receiver –s list of associated metadata. Metadata consists 

of XML content that has been stored in separate MetaDataEntity EJBs. Several 

applications can associate XML metadata with a single media entity. If the given 

metadata EJB is already part of the receiver –s list of metadata entities, no action is 

performed. 


convert (MediaConverterSpec[] specifications) 

This operation updates the receiver's content after performing a series of transformations 

on the original content, as defined in the given specifications array. The order of the 

specifications array defines the order of the transformations being performed. This allows 

modification of the receiver without transferring the content over machine boundaries. 

Note that the receiver's format can change due to this operation, and that it implicitly 

updates the receiver –s lastModified property. Also note that this operation will fail if the 

location property is set. 


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 the 

different media formats involved. A javax.emb.ConversionException is thrown if one of 

the 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 a 

directory. If null is passed, the content is exported to a default directory. The URL must 

be of protocol type ”file or any additional protocol supported by the implementation. In 

case of non-embedded media formats, the content of related children is also recursively 

copied into the same directory or one of its subdirectories. Implementations must 

guarantee that no existing files are overwritten during execution, i.e. they must resolve 

naming conflicts by generating file names and adjusting parent content if necessary. 

The location returned points to the file exported for the receiver, which is necessary to 

know in case a directory location was given, or the location given pointed to an existing 

file. 

A javax.emb.ContentAccessException is thrown if the content cannot be stored at the 

given target location, or if the content transfer fails. A 

javax.emb.MalformedLocationException is thrown if the given target location is 

malformed 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 the 

media formats involved. 

35



getChildren () 

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

being referenced from within the receiver's content, and the array is therefore 

guaranteed to be empty in case of embedded media formats. 

Note that in case of non-embedded media formats a change of the media content can 

implicitly alter the set of children. Also note that altering the resulting array content will 

not alter the persisted set of children, i.e. no persistent relationship collection is exposed. 

The reason for this is that the number of children depends on the content. 

getContent () 

Returns the complete media content as a byte array. This method is intended for 

convenient access to media content up to a few MB in size. Streaming I/O access as 

defined 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 location 

property in case the implementation is able to access the content referenced by the 

latter. 


a javax.emb.ContentTooLargeException is thrown. A javax.emb.ContentAccessException 

is 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 to 

have any structure, and is primarily designed to allow storing a descriptive label without 

the need to model an EJB relation to another entity bean describing the receiver. 

getFormat () 

Queries a suitable media format instance from the MediaFormatRegistry singleton and 

returns it. The file extension contained in the name property is used as a key for this 

query. 


with the media format registry or if the name property is null. 

getHeader () 

Returns the receiver's header information. Queries a suitable media format instance from 

the MediaFormatRegistry singleton and determines the header information based on it. 


with 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. 

getLastModified () 

Returns a timestamp stating when the receiver's persistent state was last modified. Note 

that relationships are not considered part of the persistent state and therefore don –t 

affect the value of this property. 

36



getListeners () 

Returns an array containing the media listeners associated with the receiver. If no 

listeners are associated with the receiver, an empty array is returned. Note that listeners 

are distinguished using checks for content equality, not content identity. 

getLocation () 

Returns the location of the media content as an instance of java.net.URL or null if no 

location has been set. 

getMetaData () 

Returns the receiver –s associated metadata as an array of MetaDataEntity EJBs. Metadata 

consists of XML content that has been stored in separate MetaDataEntity EJBs. Several 

applications can associate their metadata with a single MetaDataEntity EJB. An empty 

array is returned if no metadata has been set. 

getMimeType () 

Returns a mime type for the receiver's content as a string. This allows media content to 

be written directly to a Servlet output stream, as this technique requires a mime type to 

be specified in case the output is different from HTML. . If no mime type has been set 

explicitly a default mime type is returned, possibly based on the receiver –s format. 

A javax.emb.FormatNotFoundException is thrown if the mimeType property is null and 

no format can be determined. 

getName () 

Returns the receiver's non-unique name as a String or null. The name is used as a file 

name hint in case the media content is to be stored in a file system and therefore may 

only contain characters that are valid in file names. Also, it must contain a file extension 

that represents the receiver– s media format. 

getNextVersion () 

Returns the succeeding version of the receiver, which allows querying and a history 

chain of media objects that represent the same thing. The value null is returned if no 

next version exists. 

getParents () 

Returns the receiver's parents as an array of media entities. Parents are media entities 

that reference the receiver as their child, and the collection is therefore guaranteed to 

consist entirely of non-embedded media entities. Note that changing parents – content 

can alter a child media entitie –s set of parents implicitly. An empty array is returned if 

no parents are available. 

getPreviousVersion () 

Returns the previous version of the receiver, which allows querying a history of media 

objects that represent the same logical thing. The value null is returned if no previous 

version exists. 

37



getProxy () 

Returns a media object that can be used as a proxy for the receiver, e.g. a thumbnail, an 

icon, a short video/audio clip. Servlets can use this operation whenever a thumbnail or 

sound 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 may never be null. 

If a proxy relationship was explicitly set using setProxy() with a non-null value, the 

persistent proxy set is to be returned. Otherwise, a transient proxy is generated on the 

fly using the MediaFormat.extractProxy() operation and returned. Note that no 

proxy relationship can be defined with such a transient proxy. However, 

implementations are free to use an additional cache mechanism for the transient proxies 

in order to improve performance. 

A javax.emb.MediaFormatException is thrown if there – s a problem handling aspects of 

the receiver –s content. A javax.emb.ContentAccessException is thrown if there – s a 

problem reading the receiver –s content. 

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 the 

receiver –s content. 

importMedia (URL sourceLocation, String name) 

Alters the content of the receiver with the one read from the given source location, a 

URL of type ”file or any other protocol type supported by the implementation pointing 

to a piece of content. If the given name is not null, the name property is also set to 

match the given name. It may only contain characters that are valid in file names. If both 

the name property and the name given are null the name property is updated with a 

generated name, possibly based on the given source location. 

In case the media content is non-embedded, the operation recursively creates media 

entity EJBs for the children, with their respective names being derived from the child 

links within the content. Note that the operation identifies children that are referenced 

from multiple parents in the operation – s context and avoids creating multiple media 

entity EJBs in this case. 

Please note that passing a sourceLocation that is equal to the receiver –s current location 

is allowed and can trigger the recursive recreation of all children. Additionally the 

receiver's format can change due to this operation if the file extension passed with the 

given name differs from the one set for the receiver. Also note that this operation 

implicitly updates the receiver –s lastModified property, and it will fail if the location 

property is set. 


java.lang.IllegalArgumentException is thrown if the name argument passed contains 

invalid characters. A javax.emb.ContentAccessException is thrown if the content cannot 

be accessed at the given source location, or if the content transfer fails. A 


javax.ejb.CreateException is thrown if the creation of a child EJB fails. An instance of a 

subclass of javax.emb.MediaFormatException is thrown if a format related problem 

occurs. A javax.emb.MalformedLocationException is thrown if the given source location 

38



is malformed. A javax.emb.ListenerVetoException is thrown if a media listener vetoes the 

change. A javax.emb.ContentTooLargeException is thrown if the content given is larger 

than supported by the implementation. 

readContent (long position, byte[] buffer) 

Similarly to input streams, this method fills the given buffer with content read from the 


filled beginning with offset 0. If the buffer is larger than the number 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 

if the given position equals the content size. 


property if the implementation is able to access the content referenced by the latter. 


exceeds the content size. A java.lang.NullPointerException is thrown if the given buffer is 

null. 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 the 


filled beginning from the given offset with a maximum number of bytes defined by the 

given length. If the buffer is larger than the number 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 if the given 

position equals the content size. 


property if the implementation is able to access the content referenced by the latter. 


exceeds the content size, or if the given offset is negative or exceeds the buffer size. 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. 

removeListener (MediaListener listener) 

Removes the given listener from the list of persistent observers that are notified of 

important state changes or activities inside the receiver. If the listener is not part of the 

receiver –s list of persistent observers, no action is performed. Note that listeners are 

distinguished using checks for content equality, not content identity. 


removeMetaData (MetaDataEntityLocal metaData) 

Removes the given metadata from the receiver –s list of associated metadata. Metadata 

consists of XML content that has been stored in MetaDataEntity EJBs. Several applications 

can associate XML metadata with a single media entity. If the given metadata EJB is not 

part of the receiver –s list of metadata entities, no action is performed. 

39



Note that this operation will not remove the MetaDataEntity EJB from the persistent 

store, but rather disassociate the metadata from the Media Entity on which the method 

was invoked. 


setChildren (MediaEntityLocal[] children) 

This operation sets the children of the receiver to an array of media entity EJBs. Note 

that the number of children passed must match the number of existing children. Also 

note that this operation is only allowed if the content property is set because it might 

require updating said content. 

A java.lang.NullPointerException is thrown if the value passed or one of its elements is 

null. A java.lang.IllegalArgumentException is thrown if the value passed has more or 

fewer elements than the receiver –s existing number of children. A 

javax.emb.ContentUnmutableException is thrown if the location property is set. A 

javax.emb.ContentAccessException is thrown if the content has not been set. 

setContent (byte[] content) 

This operation offers a convenient way to alter the content of the receiver for small and 

embedded media content. In case the content is non-embedded, the 

importMedia(URL, String) operation should be used instead, as this method only 

modifies the receiver –s content and no child content is affected. The same is true if the 

content is rather large. 

If both the value passed and the receiver –s existing content property are not null, no 

format change may occur during this operation. If the location property is not null then 

this operation is not permitted. Note that the location property may not be set while the 

content property contains a value different from null. Note that this operation implicitly 



A javax.emb.ContentAccessException is thrown if content transfer fails. A 

javax.emb.FormatNotFoundException is thrown if the name property is null. A 

javax.emb.FormatSyntaxException is thrown if the system notices a format change. A 


javax.emb.ContentTooLargeException is thrown if the content given is larger than 

supported by the implementation. 

setContent (InputStream content) 

This operation offers a convenient way to alter the content of the receiver for all kinds of 

embedded media formats. If the content is non-embedded, the importMedia(URL, 

String) operation should be used instead, as this method only modifies the receiver – s 

content and no child content is affected. The same is true if the content is rather large. 

If both the value passed and the receiver –s existing content property are not null, no 

format change may occur during this operation. If the location property is not null, this 

operation is not permitted. The location property may not be set while the content 

property contains a value different from null. Note that this operation implicitly 



40




javax.emb.ContentAccessException is thrown if content transfer fails. A 

javax.emb.FormatNotFoundException is thrown if the name property is null. A 

javax.emb.FormatSyntaxException is thrown if the system notices a format change. A 


javax.emb.ListenerVetoException is thrown if a media listener vetoes the change. A 

javax.emb.ContentTooLargeException is thrown if the content given is larger than 

supported by the implementation. 

setDescription (String description) 

Alters the receiver –s description. The description string is primarily designed to allow 

storing a descriptive label without the need to model an EJB relation to another entity 

bean describing the receiver. Passing null causes the description field to be reset to 

null. Note that this operation implicitly updates the receiver –s lastModified property. 

A javax.emb.ListenerVetoException is thrown if a media listener vetoes the change. 

setLocation (URL location) 

Sets the location of the receiver to the given location URL or null. The purpose of this 

method is to provide a mechanism for read access to externally managed content. For 

example, content that is hosted by an external content provider. 

Note that if the content property is not null, this operation is not permitted. Note that 

the content property may not be set while the location property contains a value 

different from null. Also note that this operation implicitly updates the receiver –s 

lastModified property. 

A javax.emb.ContentAccessException is thrown if the media content cannot be accessed 

under the new location, or if the given location URL points to a directory. A 

javax.emb.LocationUnmutableException is thrown if the content property is not null. A 

javax.emb.ListenerVetoException is thrown if a media listener vetoes the change. 

setMimeType (String mimeType) 

Alters the receiver – s MIME type that allows media content to be written directly to a 

Servlet output stream. Note that this operation implicitly updates the receiver –s 

lastModified property. Note that passing null will cause the getMimeType() method 

to return a format specific default. Also note that this operation implicitly updates the 

receiver –s lastModified property. A javax.emb.ListenerVetoException is thrown if a 

media listener vetoes the change. 

setName (String name) 

Sets the receiver –s non-unique name as a String. The name is used as a file name hint in 

case the media content is to be stored or published in a file system and therefore may 

only contain characters that are valid in file names. Also, it must contain a file extension 

that represents the receiver– s media format. Note that this operation implicitly updates 

the receiver –s lastModified property. 


java.lang.IllegalArgumentException is thrown if the name argument passed contains 

invalid characters. A javax.emb.FormatNotFoundException is thrown if the format cannot 

41



be determined from the file extension. A javax.emb.ListenerVetoException is thrown if a 

media listener vetoes the change. 

setPreviousVersion (MediaEntityLocal mediaEntity) 

Defines the given media entity to be the preceding version of the receiver, which allows 

querying a history chain of media objects that represent the same logical thing. In return, 

the operation causes the receiver to be the given media entity –s next version. Passing 

the value null causes the receiver not to have a previous version anymore. The 

operation is only allowed if version chain integrity is preserved: 

• If the given media entity is the receiver itself: A 

javax.emb.VersionChainIntegrityException is thrown. 

• If the given media entity is already the previous version of the receiver: No action is 

performed. 

• If the given media entity is null: A javax.emb.VersionChainIntegrityException is 

thrown if the receiver has a successor. 

• Otherwise: A javax.emb.VersionChainIntegrityException is thrown if the given media 

entity has a successor, or if the receiver has a predecessor, a successor, or both. 

setProxy (MediaEntityLocal mediaEntity) 

Sets the given media entity as the receiver –s persistent proxy, e.g. a thumbnail, an icon, 

a short video or audio clip of any format. Proxies represent media objects to give people 

interested an up front impression of the latter. If there is already a proxy relation for the 

receiver, the old relation is discarded and the old persistent proxy is not deleted. In case 

null is passed, the relation to any existing persistent proxy is broken up and 

getProxy() will return a generated transient proxy. 

5.2 javax.emb.MediaEntityLocalHome 

This interface defines the local home interface of media entity EJBs and offers services to 

create and to query persistent and mutable media objects. It extends 

javax.ejb.EJBLocalHome. 

The create method provided allows the creation of empty media entity EJBs. These 

instances need to be filled with content in a subsequent step, by using the setName() 

and setContent() methods. 

Sometimes networks of associated non-embedded media content can become quite 

complex. In order to allow the consistent handling of such complex content structures 

the importMedia() and exportMedia() operations allows for consistent import, 

creation and export or content if for example many non-embedded parents share 

identical children. Using the related methods in the media entity EJB component 

interfaces would lead to multiple versions of the shared children being 

imported/exported. 

Finally, the publishContent() and publishMedia() operations publish a 

transient or persistent media object to a protocol server, and returns a URL or content 

that allows clients to access the protocol and server specific copies of said medium and 

its children. This abstraction allows applications to access proprietary content delivery 

services, without exposing the application to the details of the implementation of those 

42



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. 

public interface MediaEntityLocalHome extends EJBLocalHome { 

final static byte TRANSFER_TYPE_STREAM = 0; 

final static byte TRANSFER_TYPE_BURST = 1; 

MediaEntityLocal create() throws CreateException, MediaException; 

URL[] exportMedia (MediaEntityLocal[], URL) throws MediaException; 

Collection findByPartialDescription(String partialDescription) throws FinderException; 

Collection findByPartialLocation(String partialLocation) throws FinderException; 

MediaEntityLocal findByPrimaryKey(String) throws FinderException; 

MediaEntityLocal[] importMedia (URL[], URL) throws CreateException, MediaException; 

URL publishContent(Media, String, ProtocolConstraints) 

throws MediaException; 

Media publishMedia(MediaEntityLocal[], String, ProtocolConstraints) 

throws MediaException; 

} 

create () 

Creates a new media entity EJB with a generated identity key, the value of 

System.currentTimeMillis() as value of the lastModified property, and null as 

value for all other properties. Please note most of the methods of the Media Entity 

returned will throw exceptions until the name and either the location or the content 

properties are set. 

A javax.ejb.CreateException is thrown if a problem related to EJB creation occurs. 

exportMedia(MediaEntityLocal[] sourceMedia, URL targetDirectoryLocation) 

Copies the content of the given media entity EJBs and all their direct and indirect 

children to the given targetDirectoryLocation, i.e. a URL of protocol type ”file or any 

other type supported by the implementation. The operation returns an array of URLs of 

the same size as the source media array. The elements of the resulting array point to file 

copies of the source media array elements – content. If the media objects affected are 

non-embedded, the content of the copies is modified to correctly point to the copies of 

the children –s content instead of the original locations. 

If the given targetDirectoryLocation is null, a default export directory location is used. 

The operation makes sure that each media entity EJB affected corresponds to exactly 

one media object created. Note that the names of the copied media objects may differ 

from the original ones, that the operation makes sure no existing files are overwritten by 

this operation, and that implementations are permitted to copy children to subdirectories 

of the given targetDirectoryLocation. Also note that the resulting targetLocation URLs are 

returned in the order of their respective media entity EJBs. Duplicate media entity EJBs 

43



result in targetLocation URLs returned in multiple array slots, null media entity EJBs 

result in respective null values in the result. Finally, note that not all media objects 

exported are necessarily returned, just the ones for which corresponding media entity 

EJBs were passed. 

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

javax.emb.ContentAccessException is thrown in case content transfer fails. An instance of 

a subclass of javax.emb.MediaFormatException is thrown if there is a problem dealing 

with one of the media formats involved. A javax.emb.MalformedLocationException is 

thrown if the URL given is malformed or has a protocol type not supported by the 

implementation. 

findByPartialDescription (String partialDescription) 

Returns all media entities in the persistent store whose description contains the given 

String. The query is case-sensitive. Note that passing an empty string will return all 

media entity beans in the persistent store that have a description different from null. 

Passing in null or a partial description not present in the data store will result in an 

empty collection. 

A javax.ejb.FinderException is thrown if a finder problem occurs. 

findByPartialLocation (String partialLocation) 

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

String. The query is case-sensitive. Note that passing an empty string will return all 

media entity beans in the persistent store that have a location different from null. 

Passing in null or a partial location not present in the data store will result in an empty 

collection. 

A javax.ejb.FinderException is thrown if a finder problem occurs. 

findByPrimaryKey (String identity) 

Returns the media entity with the given identity. 


javax.ejb.FinderException is thrown if a finder problem occurs or no media entity is 

found. 

importMedia(URL[] sourceLocations, String[] names) 

Imports the given media objects and all their direct and indirect children from the given 

source locations and creates new EJBs for said media objects and children. For the media 

entity EJBs directly created from the source locations given, the names are derived from 

the given name array at equivalent indices. If a name value is null a generated name is 

used, possibly based on the related source location. For all other media entity EJBs 

created, the name properties are derived from the links present in their respective parent 

content. 

The operation returns an array of media entity EJBs of the same size as the source 

location array. The elements of the resulting array are based on the content of the 

corresponding elements of the source location array. 

44



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 entity 

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. 

A java.lang.NullPointerException is thrown if one of the arrays passed is null. A 

java.lang.IllegalArgumentException is thrown the two arrays passed mismatch in length 

or if one or more of the name arguments passed contain invalid characters. A 

javax.ejb.CreateException is thrown if the creation of a media entity EJB fails. A 

javax.emb.ContentAccessException is thrown if content transfer fails. An instance of a 

subclass of javax.emb.MediaFormatException is thrown if there –s a problem dealing 

with one of the media formats involved. A javax.emb.MalformedLocationException is 

thrown if one of the URLs given is malformed or has a protocol type not supported by 

the implementation. A javax.emb.ContentTooLargeException is thrown if one the media 

entity EJB contents would become larger than supported by the implementation. 

publishContent (Media content, byte transferType, ProtocolConstraints constraints) 

This operation publishes persistent or transient media content to a protocol server and 

returns a URL. The URL allows web clients to access the protocol and server specific 

copies of said medium. Note that it also exports its children if a non-embedded media 

entity EJB is passed. If the medium is persistent (i.e. is a media entity EJB), said copies 

will likely be managed and updated once the original content changes. Optionally, the 

selection of a suitable protocol server can be influenced using the given constraints 

object. Implementations of this specification are not bound to a specific algorithm to 

determine a suitable protocol server. Theoretical possibilities range from dynamic 

selection from a pre-configured server pool to relating suitable protocol servers statically 

with each media entity. The resulting URL is either pointing directly to the cached copy 

of the media object with a protocol type of http, rtsp or similar, or it is an http URL 

pointing to a managed meta-medium that points to said cached copy. 

The kind of protocol server chosen may be determined by the given transferType. 

Specified values are: 

• TRANSFER_TYPE_STREAM for streaming of media content, using a stream server as 

protocol server. 

• TRANSFER_TYPE_BURST for burst transfer of media content, usually using a web 

server as protocol server. 

Specified protocol constraint types are: 

• ”SERVER_TYPE for restriction of stream servers to chose from. The constraint value 

is an array of Strings. Specified constraint values are ”VideoCharger for IBM 

VideoCharger servers, ”RealSystem for RealNetworks RealSystem servers, and 

”Windows Media for Microsoft Windows Media services, and ”QuickTime for Apple 

QuickTime servers. The protocol server selected will be of one of these types. Note 

that some server types can feed a number of different clients. 

• ”CLIENT_TYPE for restriction of stream servers to chose from. The constraint value 


VideoCharger players, ”RealPlayer for RealNetworks players, and ”Windows Media 

for Microsoft Windows Media players, and ”QuickTime for Apple QuickTime 

45



players. The protocol server selected will support one of these client types. Note 

that some players can work with a number of protocol servers. 

In case the selected protocol server supports more than one client type, the client type is 

not constrained and a meta-medium has to be generated, said meta-medium is generated 

for the default client type of the selected protocol server. If in a similar case there is 

more than one constraint value for the client type, the constraint value is interpreted as a 

priority list and therefore the meta-medium is generated for the first client type in that 

list that is supported by the selected protocol server. 

A java.lang.NullPointerException is thrown if the media object passed is null. A 

java.lang.IllegalArgumentException is thrown if a transfer type is passed that is not 

supported by the implementation, or if a protocol type SERVER_TYPE or CLIENT_TYPE 

is passed with a value that is not an array of Strings. A 

javax.emb.NoServerFoundException is thrown if no suitable protocol server can be 

determined. A javax.emb.ContentAccessException is thrown if content transfer fails or if 

non-embedded content is passed in anything other than a media entity EJB. An instance 

of a subclass of javax.emb.MediaFormatException is thrown if there –s a problem dealing 

with one of the media formats involved. A javax.emb.LinkTranslationException is thrown 

if ingesting protocol specific links into copies of non-embedded media objects fails. A 

javax.emb.ConversionException is thrown if the middleware fails converting the media 

content to another format in order to make it suitable for a specific protocol server. 

publishMedia (MediaEntityLocal[] playlist, byte transferType, ProtocolConstraints 

constraints) 

This operation publishes the given playlist of persistent media entities to a protocol 

server and returns a meta medium that allows clients to access the protocol and server 

specific copies of said playlist and its children. If the implementation chooses to cache 

the media objects on the protocol server chosen, it must be guaranteed that eventual 

child copies are also managed and will be updated if the original content changes. 

Optionally, the selection of a suitable protocol server can be influenced using the given 

constraints object. Implementations of this specification are not bound to a specific 

algorithm to determine a suitable protocol server. Theoretical possibilities range from 

dynamic selection from a pre-configured server pool to relating suitable protocol servers 

statically with each media entity. The content of the resulting meta medium is pointing 

directly to the cached copies of the given media entities with a protocol type of http, 

rtsp or similar. 

The kind of protocol server chosen may be determined by the given transferType. 

Specified values are: 

• TRANSFER_TYPE_STREAM for streaming of media content, using a stream server as 

protocol server. 

• TRANSFER_TYPE_BURST for burst transfer of media content, usually using a web 

server as protocol server. 

Specified protocol constraint types are: 

• ”SERVER_TYPE for restriction of stream servers to chose from. The constraint value 


VideoCharger servers, ”RealSystem for RealNetworks servers, and ”Windows Media 

for Microsoft Media services, and ”QuickTime for Apple QuickTime servers. The 

46



protocol server selected will be of one of these types. Note that some server types 

can feed a number of different clients. 

• ”CLIENT_TYPE for restriction of stream servers to chose from. The constraint value 


VideoCharger players, ”RealPlayer for RealNetworks players, and ”Windows Media 

for Microsoft Windows Media players, and ”QuickTime for Apple QuickTime 

players. The protocol server selected will support one of these client types. Note 

that some players can work with a number of protocol servers. 

If the selected protocol server supports more than one client type and the client type is 

not constrained, a meta-medium is generated for the default client type of the selected 

protocol server. If in a similar case there is more than one constraint value for the client 

type, the constraint value is interpreted as a priority list and therefore the meta-medium 

is generated for the first client type in that list that is supported by the selected protocol 

server. 

Both the format and the content of the resulting meta-medium are considered 

proprietary to an implementation of this specification. Suitable are streaming metafile 

formats like Real .ram or IBM .ivs for streaming, or HTML files - containing auto load 

links for playlists consisting of exactly one entry, or clickable links for playlists consisting 

of two or more entries - for burst transfer. However, a Servlet must be able to return the 

resulting meta-medium directly to its requesting client to cause a media player to render 

the playlist on said client. For example, publishing an MPEG movie and a SMIL 

presentation for streaming 

delivery can result in the 

.ram file content depicted 

below. Please note that 

the implementation chose 

to cache the SMIL 

presentation and the 

MPEG movie on server 

17.12.88.92, as the 

originals and their children 

are distributed over 4 

different servers. This 

implies that said cache 

copy of the SMIL 

presentation contains rtsp 

references to its child 

media. 

In contrast, publishing the 

same playlist for the HTML 

protocol would have 

resulted in an html meta 

playlist 

file://16.37.12.67/movie.mp 

eg 

file://32.2.12.65/text.rt 

file://16.32.48.64/presentation.s 

mi 

file://32.2.96.66/music.rm 

publish 

(playlist, …RTSP…, null) 

rtsp://17.12.88.92/movie.mpeg 

rtsp://17.12.88.92/presentation.smi 

resulting .ram 

meta-medium 

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. 

A java.lang.NullPointerException is thrown if the playlist passed is null. A 

java.lang.IllegalArgumentExce 

ption is thrown if a transfer Figure 11: Publishing a sample playlist 

type is passed that is not 

supported by the implementation, or if a protocol type SERVER_TYPE or CLIENT_TYPE 

47



is passed with a value that is not an array of Strings. A 

javax.emb.NoServerFoundException is thrown if no suitable protocol server can be 

determined. A javax.emb.ContentAccessException is thrown if content transfer fails. An 

instance of a subclass of javax.emb.MediaFormatException is thrown if there – s a 

problem dealing with one of the media formats involved. A 

javax.emb.LinkTranslationException is thrown if ingesting protocol specific links into 

copies of non-embedded media objects fails. A javax.emb.ConversionException is 

thrown if the middleware fails converting the media content to another format in order 

to make it suitable for a specific protocol server. 

48



5.3 javax.emb.MediaListener 

This interface defines the common behavior of media listener. Such observers are 

implemented by application programmers to be persisted with and extend the semantics 

of media entity EJBs in a way that does not depend on the implementation of the latter. 

Listeners are notified of specific events in media entity EJBs once they are registered 

with said. As they have to be persisted with media entity EJBs, all listeners must be 

serializable. 

The persistent observer design differs from the standard Java listener practice by passing 

the name of properties affected instead of passing the property value to distinct callback 

methods. The reason for this is that the large size of media content makes it practically 

impossible to pass it to observers. Therefore, observers are forced to retrieve property 

values from entity beans when there is a need. Please note that Entity Beans must be 

deployed as reentrant in order for the latter to work. 

public interface MediaEntityListener extends Serializable { 

void handleAboutToChangeMediaEntity(MediaEntityLocal, String) throws MediaException; 

void handleAboutToRemoveMediaEntity(MediaEntityLocal) throws MediaException; 

void handleMediaEntityChanged(MediaEntityLocal, String) throws MediaException; 

} 

handleAboutToChangeMediaEntity (MediaEntityLocal mediaEntity, String 

propertyName) 

This method handles the fact that the given media entity is about to change the value of 

its property named propertyName. Valid property names are …content“, 

…location“, …mimeType“, …name“ and …description“. 

A javax.emb.ListenerVetoException is thrown if the listener does not agree to the 

intended change. An instance of a subclass of javax.emb.MediaException is thrown if 

there – s an application specific problem. A java.lang.NullPointerException is thrown if 

one of the values passed is null. 

handleAboutToRemoveMediaEntity (MediaEntityLocal mediaEntity) 

This method handles the fact that the given media entity is about to be removed. 

A javax.emb.ListenerVetoException is thrown if the listener does not agree to the 

intended removal. An instance of a subclass of javax.emb.MediaException is thrown if 

there – s an application specific problem. A java.lang.NullPointerException is thrown if 

the value passed is null. 

handleMediaEntityChanged (MediaEntityLocal mediaEntity, String 

propertyName) 

This method handles the fact that the given media entity has changed the value of its 

property named propertyName. Valid property names are …content“, …location“, 

…mimeType“, …name“ and …description“. 

49



A javax.emb.ListenerVetoException is thrown if the listener does not agree to the change 

performed. An instance of a subclass of javax.emb.MediaException is thrown if there –s 

an application specific problem. A java.lang.NullPointerException is thrown if one of the 

values passed is null. 

In addition to the methods described, all listeners should overwrite the two methods 

described below. Media listeners are persisted as part of Media Entity EJBs and therefore 

may change their object identity without notice. Therefore, the media entity EJB 

addListener() and removeListener() methods may not work correctly if the 

methods described below are not overwritten. 

equals (Object object) 

This method overwrites the matching method in java.lang.Object. The result is true if the 

given object is a MediaListener and it is content equal to the receiver, otherwise false. 

Note that this behavior is required as listeners are stored and loaded as part of EJB 

operations and therefore frequently change their object identity. 

hashCode () 

This method overwrites the matching method in java.lang.Object. The resulting hash 

code is calculated based on the receiver –s content. Note that this behavior is required as 

listeners are stored and loaded as part of EJB operations and therefore frequently change 

their object identity. 

50



5.4 javax.emb.ProtocolConstraints 

This class models constraints that restrict the selection of protocol servers, like stream 

servers. Instances can contain multiple kinds of constraints. Constraints come as 

type/value pairs, with the type defining the type of constraint and the value giving the 

actual constraint data “ similar to a dictionary. Protocol constraints are used when 

publishing media for a given protocol, see MediaEntityLocalHome.publish(’) 

for reference. As streaming constraints have to be transferred over machine boundaries, 

the class implements java.io.Serializable. 

This specification covers two types of constraint as binding for all implementations: 

• ”CLIENT_TYPE constrains the protocol server selection indirectly by defining an 

array of protocol client types (Strings) that are running on a client machine. 

Protocol servers are only eligible for selection during publish operations if they at 

least support one of the given client types. Also, the metadata generated during 

publish requests must be suitable for one of these clients. Standardized values for 

this constraint type are: ”Quicktime for Apple Quicktime players, ”VideoCharger 

for IBM VideoCharger players, ”Windows Media for Microsoft Windows Media 

players, ”RealPlayer for RealNetworks players. Additional client types may be added 

to this list in future releases of this specification. 

• ”SERVER_TYPE constrains the protocol server selection directly by defining an array 

of protocol server types (Strings) eligible for selection during publish requests. 

Standardized values for this constraint type are: ”Quicktime for Apple Quicktime 

servers, ”VideoCharger for IBM VideoCharger servers, ”Windows Media for 

Microsoft Windows Media services, ”RealSystem for RealNetworks servers. 

Additional protocol server types may be added to this list in future releases of this 

specification. 

public final class ProtocolConstraints implements Serializable { 

public final static String CLIENT_TYPE = …CLIENT_TYPE“; 

public final static String SERVER_TYPE = …SERVER_TYPE“; 

public ProtocolConstraints(); 

public Object getConstraint(String type); 

public void setConstraint(String type, Object value); 

public String[] getConstraintTypes(); 

} 

ProtocolConstraints () 

This is the default constructor. 

getConstraint (String type) 

Returns the value of the constraint defined by the given type, or null if said constraint 

is not present. 

A javax.emb.NullPointerException is thrown if the given type is null. 

51



setConstraint (String type, Object value) 

Alters the value of the constraint defined by the given type to the given value. Passing 

the constraint value null removes a constraint type from the receiver if present. 

A javax.emb.NullPointerException is thrown if the given type is null. A 

java.lang.IllegalArgumentException is thrown in case the constraint type given is either 

”CLIENT_TYPE or ”SERVER_TYPE , and the value given is not an array of Strings. 

getConstraintTypes () 

Returns the receiver –s constraint types as an array of Strings. 

5.5 javax.emb.MetaDataEntityLocal 

This basic interface defines behavior common to all kinds of metadata objects that are 

persistent and can be altered. It also extends EJBLocalObject and therefore represents 

the local interface of a Metadata Entity EJB. 

Meta Data Entity EJB 

xml 

name 

Figure 12: Media Entity Beans components and 

interactions 

MetaDataEntity EJBs consist of the two basic alterable properties: 

• The xml property models the XML content of a Meta Data Entity EJB. XML content 

may be implicitly processed for the creation of persistent indexing information to 

allow efficient content search. The default for this property is null. 

• The name property models a file name that is used as a default in case the xml 

content has to be exported to a file. The default value for this property is null. 

52



public interface MetaDataEntityLocal extends EJBLocalObject { 

void addChild(MetaDataEntityLocal) throws MediaException; 

void addMediaEntity(MediaEntityLocal) throws MediaException; 

URL exportMedia(URL) throws MediaException; 

MetaDataEntityLocal[] getChildren() throws MediaException; 


MediaEntityLocal[] getMediaEntities() throws MediaException; 

MediaEntityLocal[] getMediaEntities(MediaFormat, boolean) throws MediaException; 

MediaEntityLocal[] getMediaEntities(String, boolean) throws MediaException; 


MetaDataEntityLocal getNextVersion() throws MediaException; 

MetaDataEntityLocal[] getParents() throws MediaException; 

MetaDataEntityLocal getPreviousVersion() throws MediaException; 

String getXML() throws MediaException; 

void removeChild(MetaDataEntityLocal) throws MediaException; 

void removeMediaEntity(MediaEntityLocal) throws MediaException; 

void setName(String) throws MediaException; 

void setPreviousVersion(MetaDataEntityLocal) throws MediaException; 

void setXML(String, boolean) throws MediaException; 

} 

addChild (MetaDataEntityLocal child) 

Adds the given Metadata Entity EJB to the receiver– s set of children. If the given 

MetaDataEntity EJB is already part of the receiver – s list of children no action is 

performed. 


addMediaEntity (MediaEntityLocal mediaEntity) 

Adds the given Media Entity EJB to the receiver –s set of associated Media Entity EJBs 

that are described by the receiver. If the given Media Entity EJB is already part of the 

receiver –s list no action is performed. 


getChildren () 

Returns the receiver –s children as an array of Media Entity EJBs. The array is empty if 

no children are related. 

getLastModified () 

Returns a timestamp stating when the receiver's persistent state was last modified. 

getMediaEntities () 

Returns the Media Entity EJBs associated with the receiver. The array is empty if no 

media entity EJBs are related. 

53



getMediaEntities (MediaFormat mediaFormat, boolean searchCildren) 

This method locates all Media Entity EJBs associated with the receiver that have the 

specified media format. If the given recursion flag is true, the search is extended to all 

Media Entity EJBs that relate to the receiver or one of its recursive children. 

A java.lang.NullPointerException is thrown if the media format passed is null. 

getMediaEntities (String mimeType, boolean searchCildren) 

This method locates all Media Entity EJBs associated with the receiver that have the 

given mime type. If the given recursion flag is true, the search is extended to all Media 

Entity EJBs that relate to the receiver or one of its recursive children. 

A java.lang.NullPointerException is thrown if the mime type passed is null. 

getName () 

Returns the receiver's non-unique name as a String. The name is used as a file name hint 

in case the metadata XML content is to be stored in a file system and therefore may only 

contain characters that are valid in file names. Also, it should contain a file extension that 

represents the receiver –s format. Note that as opposed to media entity EJBs, the name 

property is not required to contain a file extension registered with the 

MediaFormatRegistry. 

getNextVersion () 

Returns the succeeding version edition of the receiver, which allows querying and a 

history chain of metadata objects that represent the same thing. The value null is 

returned if no next version exists. 

getParents () 

Returns the receiver's parents as an array of Metadata Entity EJBs. The array is empty if 

no parents are related. 

getPreviousVersion () 

Returns the previous version of the receiver, which allows querying a history of 

metadata objects that represent the same logical thing. The value null is returned if no 

previous version exists. 

getXML () 

This method returns the receiver –s content as an XML string. 

A javax.emb.ContentAccessException is thrown if the value passed is null. 

removeChild (MetaDataEntityLocal child) 

Removes the given Metadata Entity EJB from the receiver –s set of children. If the given 

MetaDataEntity EJB is not part of the receiver –s list of children, no action is performed. 


54



removeMediaEntity (MediaEntityLocal mediaEntity) 

Removes the given Media Entity EJB from the receiver– s set of associated Media Entity 

EJBs that are described by the receiver. If the given Media Entity EJB is not part of the 

receiver –s list no action is performed. 


setName (String name) 

Sets the receiver –s non-unique name as a String. The name is used as a file name hint in 

case the media content is to be stored or published in a file system and therefore may 

only contain characters that are valid in file names. Also, it should contain a file 

extension that represents the receiver –s media format. Note that as opposed media 

entity EJBs the name property is not required to contain a file extension registered with 

the MediaFormatRegistry. 


setPreviousVersion (MetaDataEntityLocal metadata) 

Defines the given metadata entity to be the previous version of the receiver, which 

allows querying a history chain of metadata objects that represent the same logical thing. 

In return, the operation causes the receiver to be the given metadata entity –s successor. 

Passing the value null causes the receiver not to have a predecessor anymore. The 

operation is only allowed if version chain integrity is preserved: 

• If the given metadata entity EJB is the receiver itself: A 

javax.emb.VersionChainIntegrityException is thrown. 

• If the given metadata entity EJB is already the previous version of the receiver: No 

action is performed. 

• If the given metadata entity EJB is null: A 

javax.emb.VersionChainIntegrityException is thrown if the receiver has a successor. 

• Otherwise: A javax.emb.VersionChainIntegrityException is thrown if the given 

metadata entity EJB has a successor, or if the receiver has a predecessor, a successor, 

or both. 

setXML (String xmlContent, boolean validate) 

If the given XML content is well formed, it replaces the receiver –s current metadata 

content. If the given validation flag is true, the content is additionally strictly validated 

before the operation is performed. 

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

javax.emb.MetaDataValidationException is thrown if the validate flag is true and the 

content validation fails. A javax.emb.MetaDataSyntaxException is thrown if the XML 

content is not well formed, regardless of the validate flag. 

55



5.6 javax.emb.MetaDataEntityLocalHome 

This interface defines the local home interface of metadata entity EJBs and therefore 

services relevant for local, persistent and mutable metadata objects. It extends 

javax.ejb.EJBLocalHome and defines additional methods with a semantic requiring the 

persistence of such metadata 

public interface MetaDataEntityLocalHome extends EJBLocalHome { 

MetaDataEntityLocal create() throws CreateException, MediaException; 

MetaDataEntityLocal findByPrimaryKey(String) throws FinderException; 

Collection query(String, String, Map) throws FinderException, MediaException; 

String[] retrieveSupportedOptions(String) throws MediaException; 

String[] retrieveSupportedQueryLanguages() throws MediaException; 

} 

create () 

Creates a new metadata entity EJB with a generated identity key, null XML content and 

default values for the other properties. Please note many of the Metadata Entity EJB 

methods will throw exceptions until the XML content is set. 

A javax.ejb.CreateException is thrown if a problem related to EJB creation occurs. 

findByPrimaryKey (String identity) 

Returns the metadata entity with the given identity. 


javax.ejb.FinderException is thrown if no matching metadata entity is found. 

query (String query, String queryLanguage, Map options) 

Returns the metadata entities that match the given query. The query semantics are 

defined by the given query language in association with the optionally given query 

options. Note that the set of query languages and options supported is up to the 

implementation. Valid keys for the options map can be derived by calling 

retreiveSupportedOptions(). In case unsupported options are passed, 

implementations should ignore them. 

A java.lang.NullPointerException is thrown if the query or query language passed is 

null. A javax.emb.MalformedQueryException is thrown if the query statement does not 

match the syntax defined by the given query language. A 

javax.emb.UnsupportedQueryLanguageException is thrown if the specified query 

language is not supported by the implementation. A javax.emb.IllegalOptionException is 

thrown if the given options are not formatted properly and cannot be read or if one of 

the options is unsupported and cannot be processed. 

retrieveSupportedOptions (String queryLanguage) 

Returns an array containing the names of supported options for the given query 

language. If no query options are supported then an empty array is returned. 

56




javax.emb.UnsupportedQueryLanguageException is thrown if the name of the query 

language passed is not supported by the implementation. 

retrieveSupportedQueryLanguages () 

Returns an array containing the names of supported query languages. If no query 

languages are supported then an empty array is returned. 

5.7 javax.emb.MediaException 

Enterprise Media Beans extend the exception classes introduced with Media Foundation 

Beans with some more subclasses of javax.emb.MediaException. 

5.7.1 javax.emb.ContentUnmutableException 

This exception is thrown during MediaEntityLocal.setContent() whenever the 

content cannot be manually changed on the entity. 

5.7.2 javax.emb.IllegalOptionException 

This exception is thrown during MetaDataEntityLocalHome.query() whenever a 

specified option is not valid for the specified query language. 

5.7.3 javax.emb.ListenerVetoException 

This exception extends javax.emb.MediaException and is thrown by Media entity listener 

EJBs in order to issue a veto against a media entity EJB modification. 

5.7.4 javax.emb.LocationUnmutableException 

This exception is thrown during MediaEntityLocal.setLocation(’) whenever 

the location can not be manually changed on the entity. 

5.7.5 javax.emb.MalformedQueryException 

This exception is thrown during MetaDataEntityLocalHome.query(’) whenever 

a specified query statement is not valid for the specified query language. 

5.7.6 javax.emb.MetaDataValidationException 

This exception is thrown during MetaDataEntityLocal.setXML() whenever the 

XML metadata validation fails. 

57



5.7.7 javax.emb.MetaDataSyntaxException 

This exception is thrown during MetaDataEntityLocal.getXML() whenever the 

XML metadata given is not well formed. 

5.7.8 javax.emb.NoServerFoundException 

This exception is thrown if no suitable protocol server is found during publish 

operations. 

5.7.9 javax.emb.VersionChainIntegrityException 

This exception extends javax.emb.MediaException and is thrown if there is a problem 

altering a media entity previous version association. 

5.7.10 javax.emb.UnsupportedQueryLanguageException 

This exception is thrown during MetaDataEntityLocalHome.query() whenever a 

specified query language is not supported 

5.8 javax.ejb.RemoveException 

Enterprise Media Beans extend the exception model introduced with Enterprise Java 

Beans. 

5.8.1 javax.emb.ParentAssociationExistsException 

This exception extends javax.ejb.RemoveException and is thrown if a media entity EJB 

cannot be removed because it has parents that contain links pointing to the receiver. 

Removing a media entity EJB while it has parents would violate referential integrity and 

is therefore forbidden. 

5.8.2 javax.emb.PredecessorAssociationExistsException 

This exception extends javax.ejb.RemoveException and is thrown if a media entity EJB 

cannot be removed because it has associations to a previous version in the version 

chain. Removing a media entity EJB while it has a previous version would violate 

referential integrity and is therefore forbidden. 

58



Chapter 6 

Responsibilities Of EMB Roles 

In addition to the general responsibilities of EJB roles described in the EJB specification, 

the additional responsibilities applying for Enterprise Media Beans are described below. 

6.1 Media Foundation Bean Providers 

Media Foundation Bean Providers are responsible for providing enhanced support for 

media formats and/or converters as described in the Media Foundation Bean section of 

this specification. The set of converters and/or formats supported is up to the Media 

Foundation Bean Provider. 

Media Foundation Bean Providers are encouraged to deliver implementations that are 

both container and Media Entity Bean Provider (see below) invariant. 

6.2 Media Entity Bean Providers 

Media Entity Bean Providers are responsible for providing implementations of the EJBs 

described in the Media Entity Bean section of this specification. The Media Entity Bean 

Provider chooses the kind of persistent store supported (relational database, file system, 

content management system) and if bean-managed persistence/relationships (BMP/BMR) 

or container-managed persistence/relationships (CMP/CMR) are used. 

Media Entity Bean Providers may additionally support extensions to the EJB deployment 

descriptor for resource configuration, such as format registry content, default directories, 

etc. 

Media Entity Bean Providers are encouraged to provide base support for media formats 

and converters exceeding the content of the javax.emb package. Media Entity Bean 

Providers are also encouraged to deliver implementations that are container invariant. 

6.3 EJB Application Developers 

When creating applications or reusable components, EJB Application Developers can 

directly use the Media Entity Beans and Media Foundation Beans APIs. They may define 

relationships between custom EJBs, media entity EJBs, and metadata entity EJBs. 

Additionally, they can provide custom media listener implementations to extend media 

entity EJBs. 

59



6.4 EJB Container Providers 

EJB Container Providers are additionally encouraged, but not required, to provide tooling 

to manage EMB resources such as the content of the format bean registry. EJB Container 

Providers may provide a default EMB implementation. 

Note that future versions of this specification may agree on common ways to handle 

resource configuration, such as common EMB specific extensions to the EJB deployment 

descriptor, or common container extensions for EMB resource configuration. However, at 

the current point in time we feel there is not enough industry consensus to impose such 

requirements on container providers. 

6.5 Client Programmerⱃs Responsibilities 

The EJB client programmer accesses EJBs, Media Entity EJBs and Metadata Entity EJBs 

via their home and component interfaces. Media Foundation Bean function is accessed 

directly via the Media Foundation Bean API defined in javax.emb. 

60



Chapter 7 

Examples 

This chapter provides some sample Servlet code to illustrate working with Enterprise 

Media Beans. The code assumes that the respective Servlet classes import the java.io, 

javax.servlet and javax.emb packages. 

Please note that the following Servlet code snipplets are designed to receive the identity 

of a media entity EJB as a parameter. Therefore, a parameter called ”identity , along with 

the String representation of a long value, has to be passed with each HTTP request to 

such a Servlet. This is achieved by adding a parameter to the URLs pointing to such 

Servlets - for example, a URL like 

http://myServer/myapp/myservlet?identity=42 

would cause the corresponding Servlet to receive a parameter named ”identity and an 

associated value of ”42 upon invocation. 

Also, all snipplets assume that the Servlet classes declare a static variable called 

mediaEntityHome that caches the local home of the media entity EJB. The method 

below demonstrates a way to initialize this variable. Note that the exact code depends 

on the container used for deployment. 

public void init() throws ServletException { 

try { 

// Lookup the media entity EJB home. 

javax.naming.InitialContext context = new javax.naming.InitialContext(); 

mediaEntityHome = (MediaEntityLocalHome) context.lookup("MediaEntity"); 

} catch (Exception exception) { 

throw new ServletException(exception); 

} 

} 

61



7.1 Simple Burst Transfer 

This sample service method of a Servlet illustrates the basic way to present the content 

of a media entity EJB on a client within the J2EE programming model. In this case, said 

Servlet transfers the content of the media directly through the Servlet engine to a 

requesting web client. Once the content is received, the web client will start an 

appropriate media player by analyzing the mime type set in the response. Note that this 

simple scenario is only suitable for embedded media objects. 

public void service(HttpServletRequest request, HttpServletResponse response) throws ServletException 

{ 

try { 

// Query the media entity EJB instance. 

String identity = request.getParameter("identity"); 

MediaEntityLocal mediaEntity = mediaEntityLocalHome.findByPrimaryKey(identity); 

// Determine if the media entity doesn–t exceed 2GB in size. 

long contentSize = mediaEntity.getSize(); 

if (contentSize > Integer.MAX_VALUE) { 

throw new ServletException(…cannot transfer content larger than 2GB as servlet response“); 

} 

// Fill the servlet response. The content is transferred using streaming I/O 

// to avoid memory clogging due to large content. 

response.setContentLength((int) contentSize); 

response.setContentType(mediaEntity.getMimeType()); 

} 

byte[] buffer = new byte[0x10000]; 

long position = 0; 

int bytesRead = 0; 

while((bytesRead = media.readContent(position, buffer)) != - 1) { 

response.getOutputStream().write(buffer, 0, bytesRead); 

position += bytesRead; 

} 

} catch (Throwable exception) { 


} 

62



7.2 Publishing & Burst Transfer 

This sample service method of a Servlet illustrates how the publish operation can be 

used to present the content of a media entity EJB on a client within the J2EE 

programming model. In this case, said Servlet transfers the content of the media using 

the publish operation with transfer type burst. The resulting URL is used to render the 

medium as integral part of a HTML page. For simplicity, we –ll assume that only images 

are available in the data store. 


{ 

try { 



MediaEntityLocal mediaEntity = mediaEntityHome.findByPrimaryKey(identity); 

// Publish the media entity to an HTTP server 

URL link = mediaEntityHome.publishContent( 

mediaEntity, MediaEntityLocalHome.TRANSFER_TYPE_BURST, 

null 

); 

} 

// Fill the servlet response. A link to the published content is sent 

// that is assembled into the page by the browser. 

response.getOutputStream().write(…“); 



} 

63



7.3 Publishing & Streaming 

This sample service method of a Servlet also illustrates how the publish operation can be 

used to present the content of a media entity EJB on a client within the J2EE 

programming model. In this case, the Servlet engine transfers a streaming metafile to the 

requesting web client. Once the metafile is received, the web client will start an 

appropriate media player by analyzing the mime type set in the response. After that, said 

media player will initiate streaming the media content from the stream server selected by 

the Enterprise Media Beans implementation. 

Note that due to the abstraction performed by the publish operation, the Servlet logic 

depends on neither any proprietary stream server technology, nor any predefined stream 

server location. Also, note that the decision to use a stream server as protocol server is 

the decision of the Servlet logic, not a decision of the media creator. Therefore, this is 

the preferred way to dynamically compose and present the content of media entity EJBs, 

both for burst transfer (http) and streaming (rtsp) protocols. 


{ 

try { 




// Publish the media entity. 

MediaEntityLocal[] playlist = new MediaEntityLocal[] { mediaEntity }; 

Media metaMedium = 

mediaEntityHome.publishContent(playlist, MediaEntityLocalHome.TRANSFER_TYPE_STREAM, null); 

} 

// Fill the servlet response. Note that meta media content is usually small in size. 

response.setContentLength((int) metaMedium.getSize()); 

response.setContentType(metaMedium.getMimeType()); 

response.getOutputStream().write(metaMedium.getContent()); 



} 

64



7.4 Presentation & Dynamic Conversion 

This example is similar to the one in section 6.1, with the difference that the media is 

dynamically converted to watermark the content before sending it to the requesting web 

client. If the media entity– s format does not conform to the one supported by the 

converter (for example in case of specific image formats), an exception is thrown. This 

technique is highly useful in applications incorporating digital rights management, as rich 

media content can be associated with the person requesting it. This allows enterprises to 

trace back illegal copies of copyrighted content to the originator. 

Note that the handling of the watermarked media object (local and transient) is 

analogous to the handling of the original media object persistent in section 6.1. Also note 

that the class WatermarkConverterSpec is not part of this specification, but rather custom 

or bought from a 3 rd party. 


{ 

try { 




// Watermark the media entity. 

MediaConverterSpec[] specs = new MediaConverterSpec[] { new WatermarkConverterSpec() }; 

Media media = mediaEntity.getConvertedMedia(specs); 

// Determine if the converted media is embedded and doesn–t exceed 2GB in size. 

long contentSize = media.getSize(); 

if (contentSize > Integer.MAX_VALUE) { 

throw new ServletException(…cannot transfer content larger than 2GB as servlet response“); 

} else if (!media.getFormat().isEmbedded()) { 

throw new ServletException(…cannot transfer non-embedded content as servlet response“); 

} 

// Fill the servlet response. The content is divided up into 64KB 

// chunks to avoid memory clogging due to large content. 

response.setContentLength((int) contentSize); 

response.setContentType(media.getMimeType()); 

} 

byte[] buffer = new byte[0x10000]; 

long position = 0; 

int bytesRead = 0; 

while((bytesRead = media.readContent(position, buffer)) != - 1) { 

response.getOutputStream().write(buffer, 0, bytesRead); 

position += bytesRead; 

} 



} 

65



7.5 Dynamic Header Extraction 

This sample service method of a Servlet illustrates how descriptive header information 

can be extracted dynamically from media objects. This technique is useful if descriptive 

header information should be processed or displayed in an application without storing it 

redundantly in the EJB entity bean model. 

Note that this technique is independent from any specific media format. Therefore, it can 

be used to add generic header detail information to any kind of Enterprise Media Beans 

based enterprise application. 


{ 

try { 

Writer writer = new OutputStreamWriter(response.getOutputStream()); 




// Respond the HTML header. 

writer.write(…Media Entity #“); 

writer.write(identity); 

writer.write(… 焠 Header Details“); 

} 

// respond the HTML body. 

MediaHeader header = mediaEntity.getHeader(); 

String[] fieldNames = header.getFieldNames(); 

writer.write(…“); 

for (int index = 0; index < fieldNames.length; index++) { 

writer.write(fieldNames[index]); 

writer.write(…: …); 

writer.write(header.getField(fieldNames[index]).toString()); 


} 


writer.flush(); 



} 

66



Chapter 8 

Appendix 

This chapter provides a reference for package javax.emb, an index, and links to related 

information. 

8.1 Reference 

This reference lists all classes and interfaces of package javax.emb. It also lists all 

exceptions introduced with the package. 

8.1.1 Classes and Interfaces 

This section lists all classes and interfaces introduced with the javax.emb package. It also 

lists all method signatures. 

public final class GenericMediaFormat implements MediaFormat 

o 

o 

o 

o 

o 

o 

o 

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

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

public MediaHeader extractHeader(InputStream) throws MediaException; 

public Media extractProxy (InputStream) throws MediaException; 

public String getDefaultMimeType(); 

public boolean isEmbedded(); 

public boolean isStreamingDesirable(); 

public final class GenericMediaHeader implements MediaHeader 

o 

o 

public String[] getFieldNames(); 

public Object getField(String); 

public interface Media 

o static final String MIME_TYPE_UNKNOWN = www/unknown ; 

o 

o 

o 

o 

o 

o 

o 

o 

o 










67



public class MediaBean implements Media 

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

o public MediaBean(File, String) throws MediaException; 

public interface MediaConverter 

o InputStream process (InputStream) throws MediaException; 

o void process (InputStream, OutputStream) throws MediaException; 

public interface MediaConverterSpec extends java.io.Serializable 

o MediaConverter getConverter(); 

o String getTargetMimeType(); 

o String getTargetFileExtension(); 

public interface MediaEntityLocal extends Media, javax.ejb.EJBLocalObject 

o void addListener(MediaListener) throws MediaException; 

o void addMetaData(MetaDataEntityLocal) throws MediaException; 

o void convert(MediaConverterSpec[]) throws MediaException; 

o java.net.URL exportMedia(java.net.URL) throws MediaException; 

o MediaEntityLocal[] getChildren() throws MediaException; 

o String getDescription() throws MediaException; 

o MediaListener[] getListeners(); 

o URL getLocation() throws MediaException; 

o MetaDataEntityLocal[] getMetaData() throws MediaException; 

o MediaEntityLocal getNextVersion() throws MediaException; 

o MediaEntityLocal[] getParents() throws MediaException; 

o MediaEntityLocal getPreviousVersion() throws MediaException; 

o void importMedia(java.net.URL, String) throws MediaException; 

o void removeListener(MediaListener) throws MediaException; 

o void removeMetaDataListener(MetaDataEntityLocal) throws MediaException; 

o void setChildren(MediaEntityLocal[]) throws MediaException; 

o void setContent(byte[]) throws MediaException; 

o void setContent(InputStream) throws MediaException; 

o void setDescription(String) throws MediaException; 

o void setLocation(java.net.URL) throws MediaException; 

o void setMimeType(String) throws MediaException; 

o void setName(String) MediaException 

o void setPreviousVersion(MediaEntityLocal) throws MediaException; 

o void setProxy(MediaEntityLocal) throws MediaException; 

public interface MediaEntityLocalHome extends javax.ejb.EJBLocalHome 

o final static byte TRANSFER_TYPE_STREAM = 0; 

68



o final static byte TRANSFER_TYPE_BURST = 1; 

o 

o 

o 

o 

o 

o 

o 

o 

MediaEntityLocal create() throws CreateException, MediaException; 

java.net.URL[] exportMedia (MediaEntityLocal[], java.net.URL) throws MediaException; 

java.util.Collection findByPartialDescription(String) throws FinderException; 

java.util.Collection findByPartialLocation(String) throws FinderException; 

MediaEntityLocal findByPrimaryKey(String) throws FinderException; 

MediaEntityLocal[] importMedia (java.net.URL[], String[]) throws CreateException, MediaException; 

java.net.URL publishContent(Media, String, ProtocolConstraints) throws MediaException; 

Media publishMedia(MediaEntityLocal[], String, ProtocolConstraints) throws MediaException; 

public interface MediaListener extends java.io.Serializable 

o void handleAboutToChangeMediaEntity(MediaEntityLocal, String) throws MediaException; 

o void handleAboutToRemoveMediaEntity(MediaEntityLocal) throws MediaException; 

o void handleMediaEntityChanged(MediaEntityLocal, String) throws MediaException; 

public interface MediaFormat extends java.io.Serializable 

o byte[] assembleContent(URL, MediaSegment[]); 

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

o MediaHeader extractHeader(InputStream) throws MediaException; 

o Media extractProxy(InputStream) throws MediaException; 

o String getDefaultMimeType(); 

o boolean isEmbedded(); 

o boolean isStreamingDesirable(); 

public final class MediaFormatRegistry 

o public static final MediaFormatRegistry SINGLETON; 

o private MediaFormatRegistry(); 

o public void bind(String, MediaFormat) throws FormatAlreadyBoundException; 

o public Iterator getFileExtensions(); 

o public MediaFormat lookup(String) throws FormatNotFoundException; 

o public void rebind(String, MediaFormat); 

o public void unbind(String) throws FormatNotFoundException; 

public interface MediaHeader extends java.io.Serializable 

o public String[] getFieldNames(); 

o public Object getField(String); 

public final class MediaSegment extends java.io.Serializable 

o public MediaSegment(); 

o public byte[] getContent(); 

o public URL getChildLocation(); 

o public void setContent(byte[]); 

69



o 

public void setChildLocation(URL); 

public interface MetaDataEntityLocal extends javax.ejb.EJBLocalObject 

o 

o 

o 

o 

o 

o 

o 

o 

o 

o 

o 

o 

o 

o 

o 

o 

void addChild(MetaDataEntityLocal) throws MediaException; 

void addMediaEntity(MediaEntityLocal) throws MediaException; 

MetaDataEntityLocal getChildren() throws MediaException; 


MediaEntityLocal[] getMediaEntities() throws MediaException; 

MediaEntityLocal[] getMediaEntities (MediaFormat, boolean) throws MediaException; 

MediaEntityLocal[] getMediaEntities (String, boolean) throws MediaException; 


MetaDataEntityLocal getNextVersion() throws MediaException; 

MetaDataEntityLocal[] getParents() throws MediaException; 

MetaDataEntityLocal getPreviousVersion() throws MediaException; 

String getXML() throws MediaException; 

void removeChild(MetaDataEntityLocal) throws MediaException; 

void removeMdiaEntity(MediaEntityLocal) throws MediaException; 

void setPreviousVersion(MetaDataEntityLocal) throws MediaException; 

void setXML(String, boolean) throws MediaException; 

public interface MetaDataEntityLocalHome extends javax.ejb.EJBLocalHome 

o 

o 

o 

o 

o 

o 

MetaDataEntityLocal create() throws CreateException, MediaException; 

java.util.Collection findByPartialContent(String) throws FinderException; 

MetaDataEntityLocal findByPrimaryKey(String) throws FinderException; 

java.util.Collection query(String, Strin g, java.util.Map) throws FinderException, MediaException; 

String[] retrieveSupportedOptions(String) throws MediaException; 

String[] retrieveSupportedQueryLanguages() throws MediaException; 

public final class ProtocolConstraints implements java.io.Serializable 

o 

o 

o 

o 

o 

o 

public static final String CLIENT_TYPE; 

public static final String SERVER_TYPE; 

public ProtocolConstraints(); 

8.1.2 Exceptions 

public Object getConstraint(String); 

public void setConstraint(String, Object); 

public String[] getConstraintTypes(); 

This section provides an overview over the exception classes introduced with this 

specification. It also depicts the hierarchy relationships between said exceptions. 

Exceptions that are part of the J2EE core are marked with italics. 

java.lang.Throwable 

java.lang.Exception 

70



javax.emb.MediaException 

javax.emb.ContentAccessException 

javax.emb.MediaFormatException 

javax.emb.FormatAlreadyBoundException 

javax.emb.FormatFeatureException 

javax.emb.FormatNotFoundException 

javax.emb.FormatSyntaxException 

javax.emb.ContentTooLargeException 

javax.emb.ContentUnmutableException 

javax.emb.ConversionException 

javax.emb.IllegalLocationException 

javax.emb.LinkTranslationException 

javax.emb.LocationUnmutableException 

javax.emb.MalformedLocationException 

javax.emb.MalformedOptionException 

javax.emb.MalformedQueryException 

javax.emb.MetaDataSyntaxException 

javax.emb.MetaDataValidationException 

javax.emb.ListenerVetoException 

javax.emb.MalformedSecurityMaskException 

javax.emb.NoServerFoundException 

javax.emb.UnsupportedQueryLanguageException 

javax.emb.VersionChainIntegrityException 

javax.ejb.RemoveException 

javax.emb.ParentAssociationExistsException 

javax.emb.PredecessorAssociationExistsException 

8.2 Related Documents 

• Sun Microsystems, ”Designing Enterprise Applications with the J2EE Platform, 

Second Edition , 2002. 

• Sun Microsystems, ”Enterprise JavaBeans TM Specification , Version 2.x 

• Sun Microsystems, ”Java Media Framework TM Specification , Version 2.0, Final 

Release, March 2001. 

• IBM Corporation, ”Datalinks: Managing External Data With DB2 Universal Database , 

February 1999. 

• Object Management Group, ”Unified Modeling Language Specification , Version 1.3, 

March 2000 

71

Java Specification Request 086 Enterprise Media BeansTM ...

Create successful ePaper yourself

Delete template?

Save as template?