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

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
implmentations that subclass CommandInfo to provide special
behavior. For example a CommandMap could dynamically generate
JavaBeans. In this case, it might not be possible to create an
object with all the correct state information solely from the class
name.

The CommandMap class provides an interface to a registry of
command 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.

JavaBeans components that are Activation Framework 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.  JavaBeans 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.

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.

Applications don't generally call the methods in DataContentHandlers
directly. Instead, an application calls the equivalent methods in
DataHandler. The DataHandler will attempt to find an appropriate
DataContentHandler that corresponds to its MIME type using the
current DataContentHandlerFactory. The DataHandler then calls
through to the methods in the DataContentHandler.

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.

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.

DataHandler and the Transferable Interface
DataHandler implements the Transferable interface so that data can
be used in AWT data transfer operations, such as cut and paste and
drag and drop. The implementation of the Transferable interface
relies on the availability of an installed DataContentHandler
object corresponding to the MIME type of the data represented in
the specific instance of the DataHandler.

DataHandler and CommandMaps
The DataHandler keeps track of the current CommandMap that it uses to
service requests for commands (getCommand,
getAllCommands, getPreferredCommands).
Each instance of a DataHandler may have a CommandMap associated with
it using the setCommandMap method.  If a CommandMap was
not set, DataHandler calls the getDefaultCommandMap
method in CommandMap and uses the value it returns. See
CommandMap for more information.

DataHandler and URLs
The current DataHandler implementation creates a private
instance of URLDataSource when it is constructed with a URL.

The DataSource interface provides the JavaBeans Activation Framework
with an abstraction of an 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.

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

FileDataSource Typing Semantics

The FileDataSource class delegates data typing of files
to an object subclassed from the FileTypeMap class.
The setFileTypeMap method can be used to explicitly
set the FileTypeMap for an instance of FileDataSource. If no
FileTypeMap is set, the FileDataSource will call the FileTypeMap's
getDefaultFileTypeMap method to get the System's default 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.

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.

Mailcap file search order:
The MailcapCommandMap looks in various places in the user's
system for mailcap file entries. When requests are made
to search for commands in the MailcapCommandMap, it searches
mailcap files in the following order:


 Programatically added entries to the MailcapCommandMap instance.
 The file .mailcap in the user's home directory.
 The file <java.home>/lib/mailcap.
 The file or resources named META-INF/mailcap.
 The file or resource named META-INF/mailcap.default
(usually found only in the activation.jar file).


Mailcap file format:

Mailcap files must conform to the mailcap
file specification (RFC 1524, A User Agent Configuration Mechanism
For Multimedia Mail Format Information).
The file format consists of entries corresponding to
particular MIME types. In general, the specification
specifies applications for clients to use when they
themselves cannot operate on the specified MIME type. The
MailcapCommandMap extends this specification by using a parameter mechanism
in mailcap files that allows JavaBeans(tm) components to be specified as
corresponding to particular commands for a MIME type.

When a mailcap file is
parsed, the MailcapCommandMap recognizes certain parameter signatures,
specifically those parameter names that begin with x-java-.
The MailcapCommandMap uses this signature to find
command entries for inclusion into its registries.
Parameter names with the form x-java-<name>
are read by the MailcapCommandMap as identifying a command
with the name name. When the name is
content-handler the MailcapCommandMap recognizes the class
signified by this parameter as a DataContentHandler.
All other commands are handled generically regardless of command
name. The command implementation is specified by a fully qualified
class name of a JavaBean(tm) component. For example; a command for viewing
some data can be specified as: x-java-view=com.foo.ViewBean.

When the command name is fallback-entry, the value of
the command may be true or false.  An
entry for a MIME type that includes a parameter of
x-java-fallback-entry=true defines fallback commands
for that MIME type that will only be used if no non-fallback entry
can be found.  For example, an entry of the form text/*; ;
x-java-fallback-entry=true; x-java-view=com.sun.TextViewer
specifies a view command to be used for any text MIME type.  This
view command would only be used if a non-fallback view command for
the MIME type could not be found.

MailcapCommandMap aware mailcap files have the
following general form:

# Comments begin with a '#' and continue to the end of the line.
<mime type>; ; <parameter list>
# Where a parameter list consists of one or more parameters,
# where parameters look like: x-java-view=com.sun.TextViewer
# and a parameter list looks like:
text/plain; ; x-java-view=com.sun.TextViewer; x-java-edit=com.sun.TextEdit

# Note that mailcap entries that do not contain 'x-java' parameters
# and comply to RFC 1524 are simply ignored:
image/gif; /usr/dt/bin/sdtimage %s

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

A parameter list of a MimeType
as defined in RFC 2045 and 2046. The Primary type of the
object must already be stripped off.

A class to encapsulate MimeType parsing related exceptions.

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

MIME types file search order:
The MimetypesFileTypeMap looks in various places in the user's
system for MIME types file entries. When requests are made
to search for MIME types in the MimetypesFileTypeMap, it searches
MIME types files in the following order:


 Programmatically added entries to the MimetypesFileTypeMap instance.
 The file .mime.types in the user's home directory.
 The file <java.home>/lib/mime.types.
 The file or resources named META-INF/mime.types.
 The file or resource named META-INF/mimetypes.default
(usually found only in the activation.jar file).


MIME types file format:


# comments begin with a '#'
# the format is <mime type> <space separated file extensions>
# for example:
text/plain    txt text TXT
# this would map file.txt, file.text, and file.TXT to
# the mime type `text/plain`

Signals that the requested operation does not support the
requested data type.

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 the JavaBeans Activation Framework
because this class can be used to create new DataHandlers. NOTE: The
DataHandler object creates a URLDataSource internally,
when it is constructed with a URL.