Jakarta Activation 2.0

The DataHandler class (shown in the diagram above) provides a consistent interface between Activation-aware clients and other subsystems.

The DataSource interface encapsulates an object that contains data, and that can return both a stream providing data access, and a string defining the MIME type describing the data.

Classes can be implemented for common data sources (web, file system, IMAP, ftp, etc.). The DataSource interface can also be extended to allow per data source user customizations. Once the DataSource is set in the DataHandler, the client can determine the operations available on that data.

Jakarta Activation includes two DataSource class implementations for convenience:

The CommandMap provides a service that allows consumers of its interfaces to determine the ‘commands’ available on a particular MIME type as well as an interface to retrieve an object that can operate on an object of a particular MIME type (effectively a component registry). The Command Map can generate and maintain a list of available capabilities on a particular data type by a mechanism defined by the implementation of the particular instance of the CommandMap.

The JavaBeans™ package provides the programming model for the software components that implement the commands. Each JavaBeans™ component can use externalization, or can implement the CommandObject interface to allow the typed data to be passed to it.

Jakarta Activation defines the CommandMap interface, which provides a flexible and extensible framework for the CommandMap. The CommandMap interface allows developers to develop their own solutions for discovering which commands are available on the system. A possible implementation can access the ‘types registry’ on the platform or use a server-based solution. Jakarta Activation provides a simple default solution based on RFC 1524 (.mailcap) like functionality. See “Deliverables” below.

Beans extend the CommandObject interface in order to interact with Activation services. Activation-aware JavaBeans™ components can directly access their DataSource and DataHandler objects in order to retrieve the data type and to act on the data.

Description of tasks performed by the application is broken down into three discrete steps, for clarity:

One of the interfaces mentioned below is the ‘DataSource’ object. Recall that the DataSource object encapsulates the underlying data object in a class that abstracts the underlying data storage mechanism, and presents its consumers with a common data access and typing interface. The file viewer application queries the file system for its contents.

The viewer instantiates a DataSource object for each file in the directory. Then it instantiates a a DataHandler with the DataSource as its constructor argument. The DataHandler object provides the client application with access to the CommandMap, which provides a service that enables access to commands that can operate on the data. The application maintains a list of the DataHandler objects, queries them for their names to generate its display.

Once the application has been initialized and has presented a list of files to the user, the user can select a file on the list. When the user selects a file, the application displays a popup menu that lists the available operations on that file.

The application implements this functionality by requesting the list of available commands from the DataHandler object associated with a file. The DataHandler retrieves the MIME type of the data from the DataSource object and queries the CommandMap for operations that are available on that type. The application interprets the list and presents it to the user on a popup menu. The user then selects one of the operations from that list.

After the user has selected a command from the popup menu, the application uses the appropriate CommandInfo class to retrieve the Bean that corresponds to the selected command, and associates the data with that Bean using the appropriate mechanism (DataHandler, Externalization etc.). Some CommandObjects (viewers for instance) are subclassed from java.awt.Component and require that they are given a parent container. Others (like a default print Command) might not present a user interface. This allows them to be flexible enough to function as stand alone viewer/editors, or perhaps as components in a compound document system. The ‘application’ is responsible for providing the proper environment (containment, life cycle, etc.) for the CommandObject to execute in. We expect that the requirements will be lightweight (not much beyond JavaBeans™ containers and AWT containment for visible components).

The first scenario was the ‘canonical’ case. There are also circumstances where the application has already created objects to represent its data. In this case creating an in-memory instance of a DataSource that converted an existing object into an InputStream is an inefficient use of system resources and can result in a loss of data fidelity.

In these cases, the application can instantiate a DataHandler, using the DataHandler(Object obj, String mimeType) constructor. DataHandler implements the Transferable interface, so the consuming Bean can request representations other than InputStreams. The DataHandler also constructs a DataSource for consumers that request it. The DataContentHandler mechanism is extended to also allow conversion from Objects to InputStreams.

The following code is an example of a database front end using Jakarta Activation, which provides query results in terms of objects.

The DataSource interface is used by the DataHandler (and possibly other classes elsewhere) to access the underlying data. The DataSource object encapsulates the underlying data object in a class that abstracts the underlying data storage and typing mechanism, and presents its consumers with a common data access interface.

Jakarta Activation provides DataSource implementations that support file systems and URLs. Application system vendors can use the DataSource interface to implement their own specialized DataSource classes to support IMAP servers, object databases, or other sources.

There is a one-to-one correspondence between underlying data items (files for instance) and DataSource objects. Also note that the class that implements the DataSource interface is responsible for typing the data. To manage a file system, a DataSource can use a simple mechanism such as a file extension to type data, while a DataSource that supports incoming web-based data can actually examine the data stream to determine its type.

The DataHandler class encapsulates a Data object, and provides methods which act on that data.

DataHandler encapsulates the type-to-command object binding service of the CommandMap interface for applications. It provides a handle to the operations and data available on a data element.

DataHandler also implements the Transferable interface. This allows applications and applets to retrieve alternative representations of the underlying data, in the form of objects. The DataHandler encapsulates the interface to the component repository and data source.

Let’s examine these groups of features in more detail:

The DataContentHandler interface is implemented by classes that are used by the DataHandler to convert InputStreams into objects and vice versa. In effect, the DataHandler object uses a DataContentHandler object to implement the Transferable interface. DataContentHandlers are discovered via the current CommandMap. A DataContentHandler uses DataFlavors to represent the data types it can access.

The DataContentHandler also converts data from objects into InputStreams. For instance, if an application needs to access a .gif file, it passes the file to the image/gif DataContentHandler. The image/gif DataContentHandler converts the image object into a gif-formatted byte stream.

Applications will typically need to provide DataContentHandlers for all the MIME types they intend to support. (Note that the Jakarta Mail implementation provides DataContentHandlers for many of the MIME types used in mail messages.)

Once the DataHandler has a MIME type describing the content, it can query the CommandMap for the operations, or commands that are available for that data type. The application requests commands available through the DataHandler and specifies a command on that list. The DataHandler uses the CommandMap to retrieve the Bean associated with that command. Some or all of the command map is stored in some ‘common’ place, like a .mailcap (RFC 1524) file. Other more complex implementations can be distributed, or can provide licensing or authentication features.

The CommandInfo class is used to represent commands in an underlying registry. From a CommandInfo object, an application can instantiate the Bean or request the verb (command) it describes.

Beans designed specifically for use with Jakarta Activation should implement the CommandObject interface. This interface provides direct access to DataHandler methods and notifies an Activation-aware Bean which verb was used to call it. Upon instantiation, the Bean takes a string specifying a user-selected command verb, and the DataHandler object managing the target data. The DataHandler takes a DataSource object, which provides an input stream linked to that data, and a string specifying the data type.

Like the ContentHandler factory in the java.net package, the DataContentHandlerFactory is an interface that allows developers to write objects that map MIME types to DataContentHandlers. The interface is extremely simple, in order to allow developers as much design and implementation freedom as possible.

This section describes the specification of well-behaved Activation-aware Bean viewers. Note that this proposal assumes the reader is comfortable with the JavaBeans™ Specification. Developers intending to implement viewer Beans for Jakarta Activation should be familiar with JavaBeans™ concepts and architecture.

We are attempting to limit the amount of extra baggage that needs to be implemented beyond ‘generic’ Beans. In many cases, JavaBeans™ components that weren’t developed with knowledge of the framework can be used. Jakarta Activation exploits the existing features of JavaBeans™ and the JDK™, and defines as few additional interfaces and policies as possible.

We expect that viewers/editors will be bound to data via a simple registry mechanism similar in function to a .mailcap file. In addition, mailcap format files may be bundled with components, allowing additional packages to be added at runtime.

Our viewers/editors and related classes and files are encapsulated into JAR files, as is the preferred method for JavaBeans™. Jakarta Activation does not restrict the choice of classes used to implement Activaiton-aware ‘viewer’ Beans, beyond those expected of well-behaved Beans.

A viewer Bean that communicates directly with a Jakarta Activation DataHandler should implement the CommandObject interface. This interface is small and easy to implement. However, Beans can still use standard Serialization and Externalization methods available in the JDK.

Jakarta Activation expects applications and viewer Beans to implement storage tasks via the DataSource object. However; it is possible to use Externalization. An Activation-aware application can implement the following storage mechanism:

The basic format for packaging of the Viewer/Editors is the JAR file as described in the JavaBeans™ Specification. This format allows the convenient packaging of collections of files that are related to a particular Bean or applet. For more information concerning integration points, see Section 8.

Jakarta Activation is designed to be flexible enough to support the needs of a variety of applications. Jakarta Activation expects these applications to provide the appropriate containers and life cycle support for these Beans. Beans written for the framework should be compatible with the guidelines in the JavaBeans™ documentation and should be tested against the BDK BeanBox (and the JDK Appletviewer if they are subclassed from Applet).

In general Jakarta Activation expects that its viewer bean life cycle semantics are the same as those for all Beans. In the case of Beans that implement the CommandObject interface we encourage application developers to not parent Beans subclassed from java.awt.Component to an AWT container until after they have called the jakarta.activation.CommandObject.setCommandContext method.

The MailcapCommandMap implementation provides a mechanism that allows for an extensible set of command verbs. Applications using Jakarta Activation can query the system for commands available for a particular MIME type, and retrieve the Bean associated with that MIME type.

Suppose you’re building a new Wombat Editor product, with its corresponding Wombat file format. You’ve built the Wombat Editor as one big Bean. Your WombatBean can do anything and everything that you might want to do with a Wombat. It can edit, it can print, it can view, it can save Wombats to files, and it can read Wombats in from files. You’ve defined a language-independent Wombat file format. You consider the Wombat data and file formats to be proprietary so you have no need to offer programmatic interfaces to Wombats beyond what your WombatBean supports.

You’ve chosen the MIME type “application/x-wombat” to describe your Wombat file format, and you’ve chosen the filename extension “.wom” to be used by files containing Wombats.

To integrate with the framework, you’ll need some simple wrappers for your WombatBean for each command you want to implement. For example, for a Print command wrapper you can write the following code:

You will need to create a mailcap file that lists the MIME type “application/x-wombat” and user visible commands that are supported by your WombatBean. Your WombatBean wrappers will be listed as the objects supporting each of these commands.

You’ll also need to create a mime.types file with an entry:

All of these components are packaged in a JAR file:

Because everything is built into one Bean, and because no third party programmatic access to your Wombat objects is required, there’s no need for a DataContentHandler. Your WombatBean can therefore implement the Externalizable interface instead; and use its methods to read and write your Wombat files. The DataHandler can call the Externalizable methods when appropriate.

Your Wombat Editor product has really taken off, and you’re now adding significant new functionality and flexibility to your Wombat Editor. It’s no longer feasible to put everything into one giant Bean. Instead, you’ve broken the product into a number of Beans and other components:

In addition, customers have demanded to be able to programmatically manipulate Wombats, independently from the visual viewer or editor Beans. You’ll need to create a DataContentHandler that can convert a byte stream to and from a Wombat object. When reading, the WombatDataContentHandler reads a byte stream and returns a new Wombat object. When writing, the WombatDataContentHandler takes a Wombat object and produces a corresponding byte stream. You’ll need to publish the API to the Wombat class.

The WombatDataContentHandler is delivered as a class and is designated as a DataContentHandler that can operate on Wombats in the mailcap file included in your JAR file.

Your mailcap file changes to list the appropriate Wombat Beans, which implement user commands:

Your Wombat Beans can continue to implement the Externalizable interface, and thus read and write Wombat byte streams. They are more likely to simply operate on Wombat objects directly. To find the Wombat object they’re being invoked to operate on, they implement the CommandObject interface. The setCommandContext method refers them to the corresponding DataHandler, from which they can invoke the getContent method, which will return a Wombat object (produced by the WombatDataContentHandler).

All components are packaged in a JAR file.

The Wombat product has been wildly successful. The ViewAll Company has decided that it can produce a Wombat viewer that’s much faster than the WombatViewer Bean. Since they don’t want to depend on the presence of any Wombat components, their viewer must parse the Wombat file format, which they reverse engineered.

The ViewAll WombatViewerBean implements the Externalizable interface to read the Wombat data format.

ViewAll delivers an appropriate mailcap file:

and mime.types file:

All components are packaged in a JAR file.

Now that everyone is using Wombats, you’ve decided that it would be nice if you could notify people by email when new Wombats are created. You have designed a new WombatNotification class and a corresponding data format to be sent by email using the MIME type “application/x-wombat-notification”. Your server detects the presence of new Wombats, constructs a WombatNotification object, and constructs and sends an email message with the Wombat notification data as an attachment. Your customers run a program that scans their email INBOX for messages with Wombat notification attachments and use the WombatNotification class to notify their users of the new Wombats.

In addition to the server application and user application described, you’ll need a DataContentHandler to plug into the DataHandler infrastructure and construct the WombatNotification objects. The WombatNotification DataContentHandler is delivered as a class named WombatNotificationDataContentHandler and is delivered in a JAR file with the following mailcap file:

The server application creates DataHandlers for its WombatNotification objects. The email system uses the DataHandler to fetch a byte stream corresponding to the WombatNotification object. (The DataHandler uses the DataContentHandler to do this.)

The client application retrieves a DataHandler for the email attachment and uses the getContent method to get the corresponding WombatNotification object, which will then notify the user.

Jakarta Activation is implemented as a Standard Extension to the Java™ Platform. The following are some more details about the package:

interface DataSource: The DataSource interface provides Jakarta Activation with an abstraction of some arbitrary collection of data. It provides a type for that data as well as access to it in the form of InputStreams and OutputStreams where appropriate.

class DataHandler: The DataHandler class provides a consistent interface to data available in many different sources and formats. It manages simple stream to string conversions and related operations using DataContentHandlers. It provides access to commands that can operate on the data. The commands are found using a CommandMap.

interface DataContentHandler: The DataContentHandler interface is implemented by objects that can be used to extend the capabilities of the DataHandler’s implementation of the Transferable interface. Through DataContentHandlers the framework can be extended to convert streams in to objects, and to write objects to streams.

interface DataContentHandlerFactory: This interface defines a factory for DataContentHandlers. An implementation of this interface should map a MIME type into an instance of DataContentHandler. The design pattern for classes implementing this interface is the same as for the ContentHandler mechanism used in java.net.URL.

class CommandMap: The CommandMap class provides an interface to the registry of viewer, editor, print, etc. objects available in the system. Developers are expected to either use the CommandMap implementation included with this package (MailcapCommandMap) or develop their own. Note that some of the methods in this class are abstract.

interface CommandObject: Beans that are Activation aware implement this interface to find out which command verb they’re being asked to perform, and to obtain the DataHandler representing the data they should operate on. Beans that don’t implement this interface may be used as well. Such commands may obtain the data using the Externalizable interface, or using an application-specific method.

class CommandInfo: The CommandInfo class is used by CommandMap implementations to describe the results of command requests. It provides the requestor with both the verb requested, as well as an instance of the bean. There is also a method that will return the name of the class that implements the command but it is not guaranteed to return a valid value. The reason for this is to allow CommandMap implementations that subclass CommandInfo to provide special behavior. For example a CommandMap could dynamically generate Beans. In this case, it might not be possible to create an object with all the correct state information solely from the class name.

class FileDataSource: The FileDataSource class implements a simple DataSource object that encapsulates a file. It provides data typing services via a FileTypeMap object.

class FileTypeMap: The FileTypeMap is an abstract class that provides a data typing interface for files. Implementations of this class will implement the getContentType methods which will derive a content type from a file name or a File object. FileTypeMaps could use any scheme to determine the data type, from examining the file extension of a file (like the MimetypesFileTypeMap) to opening the file and trying to derive its type from the contents of the file. The FileDataSource class uses the default FileTypeMap (a MimetypesFileTypeMap unless changed) to determine the content type of files.

class MimetypesFileTypeMap: This class extends FileTypeMap and provides data typing of files via their file extension. It uses the .mime.types format.

class URLDataSource: The URLDataSource class provides an object that wraps a URL object in a DataSource interface. URLDataSource simplifies the handling of data described by URLs within Jakarta Activation because this class can be used to create new DataHandlers.

class MailcapCommandMap: MailcapCommandMap extends the CommandMap abstract class. It implements a CommandMap whose configuration is based on mailcap files (RFC 1524). The MailcapCommandMap can be configured both programmatically and via configuration files.

class ActivationDataFlavor: The ActivationDataFlavor is a special subclass of java.awt.datatransfer.DataFlavor. It allows Jakarta Activation to set all three values stored by the DataFlavor class via a new constructor as well as improved MIME parsing in the equals method. Except for the improved parsing, its semantics are identical to that of the JDK’s DataFlavor class.

class UnsupportedDataTypeException: Signals that requested operation does not support the requested data type.

class MimeType: A Multipurpose Internet Extension (MIME) type, as defined in RFC 2045 and 2046.

class com.sun.activation.viewers.*: A few simple example viewer Beans (text and image).