Class javax.activation.DataHandler

java.lang.Object
    |
    +----javax.activation.DataHandler

public class DataHandler

extends java.lang.Object

implements java.awt.datatransfer.Transferable

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 respresented 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). When it makes a call to one of the Command methods, the DataHandler checks to determine that a CommandMap has been explictly set via its setCommandMap method. If it has, it uses that CommandMap. 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.

See Also:

CommandMap, DataContentHandler, DataSource, URLDataSource

Constructor Summary

DataHandler(DataSource ds) Creates a DataHandler instance with the specified DataSource.

DataHandler(java.lang.Object obj, java.lang.String mimeType) Initializes the DataHandler class with an object of this MIME type.

DataHandler(java.net.URL url) Initializes the DataHandler class with a URL.

 

Method Summary
CommandInfo[]	getAllCommands() This method returns an array containing all commands for the type of data represented in the DataHandler.
java.lang.Object	getBean(CommandInfo cmdinfo) A convenience method that takes a CommandInfo object and instantiates the corresponding command, usually a JavaBean component.
CommandInfo	getCommand(java.lang.String cmdName) Get the command cmdName.
java.lang.Object	getContent() Return the data in its preferred Object form.
java.lang.String	getContentType() Return the MIME type of this object as retrieved from the source object.
DataSource	getDataSource() Returns the DataSource associated with this instance of DataHandler.
java.io.InputStream	getInputStream() Get the InputStream for this object.
java.lang.String	getName() Return the name of the data object.
java.io.OutputStream	getOutputStream() Get the OutputStream for this DataHandler.
CommandInfo[]	getPreferredCommands() This method calls the getPreferredCommands method in the commandMap installed in this instance of DataHandler.
java.lang.Object	getTransferData(java.awt.datatransfer.DataFlavor flavor) Returns an object that represents the data to be transferred.
java.awt.datatransfer.DataFlavor[]	getTransferDataFlavors() Return the DataFlavors in which this data is available.
boolean	isDataFlavorSupported(java.awt.datatransfer.DataFlavor flavor) Returns whether the specified data flavor is supported for this object. This method iterates through the DataFlavors available from this object, which was the result of a call to this.getTransferDataFlavors.
void	setCommandMap(CommandMap commandMap) This method overrides the current CommandMap in this DataHandler.
static void	setDataContentHandlerFactory(DataContentHandlerFactory newFactory) Sets the DataContentHandlerFactory.
void	writeTo(java.io.OutputStream os) Write the data to an OutputStream. If the DataHandler was created with a DataSource, writeTo retrieves the InputStream and writes the bytes from the InputStream to the OutputStream passed in.

 

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

 

Constructor Detail

DataHandler

public DataHandler(DataSource ds)

Creates a DataHandler instance with the specified DataSource.

Parameters:

ds - the DataSource

DataHandler

public DataHandler(java.lang.Object obj,
                   java.lang.String mimeType)

Initializes the DataHandler class with an object of this MIME type. This constructor is used when the application already has an in-memory representation of the data in the form of a Java Object.

Parameters:

obj - the Java Object

mimeType - the MIME type of the object

DataHandler

public DataHandler(java.net.URL url)

Initializes the DataHandler class with a URL. The DataHandler internally creates a URLDataSource instance to represent the URL.

Parameters:

url - a URL object

getDataSource

public DataSource getDataSource()

Returns the DataSource associated with this instance of DataHandler.

For DataHandlers that have been instantiated with a DataSource, this method returns the DataSource that was used to create the DataHandler object. In other cases the DataHandler constructs a DataSource from the data used to construct the DataHandler. DataSources created for DataHandlers not instantiated with a DataSource are cached for performance reasons.

Returns:

A valid DataSource object for this DataHandler.

Throws:

java.io.IOException - if an I/O error occurs

getName

public java.lang.String getName()

Return the name of the data object. If this DataHandler was created with a DataSource, this method calls through to the DataSource.getName method, otherwise it returns null.

Returns:

the name of the object

getContentType

public java.lang.String getContentType()

Return the MIME type of this object as retrieved from the source object. Note that this is the full type with parameters.

Returns:

the MIME type

getInputStream

public java.io.InputStream getInputStream() throws java.io.IOException

Get the InputStream for this object.

For DataHandlers instantiated with a DataSource. the DataHandler calls the DataSource.getInputStream method The result returned to the caller.

For DataHandlers instantiated with an Object, the DataHandler first attempts to find a DataContentHandler for the Object. If the DataHandler can not find a DataContentHandler for this MIME type, it throws an UnsupportedDataTypeException. If it is successful, it creates a pipe between the returned InputStream and DataContentHandler's writeTo method, which is called with the object's data. It creates a thread that allows this operation to complete asynchonously. However, because a thread is created to copy the data, IOExceptions that may occur during the copy can not be propagated back to the caller. The result is an empty stream.

Returns:

the InputStream representing this data

Throws:

java.io.IOException - if an I/O error occurs

See Also:

writeTo, UnsupportedDataTypeException

writeTo

public void writeTo(java.io.OutputStream os) throws java.io.IOException

Write the data to an OutputStream.

If the DataHandler was created with a DataSource, writeTo retrieves the InputStream and writes the bytes from the InputStream to the OutputStream passed in.

If the DataHandler was created with an object, writeTo retrieves the DataContentHandler for the object's type. If the DataContentHandler was found, it calls the writeTo method on the DataContentHandler.

Parameters:

os - the OutputStream to write to

Throws:

java.io.IOException - if an I/O error occurs

getOutputStream

public java.io.OutputStream getOutputStream() throws java.io.IOException

Get the OutputStream for this DataHandler. This method attempts to return a valid OutputStream in DataHandlers not created with the DataHandler(Object, String) constructor (in which case it returns null). In other cases, it returns a valid OutputStream unless either the DataSource used to construct this DataHandler can not provide an valid OutputStream, or the URL used to construct this object can not return a valid OutputStream.

Returns:

the OutputStream

See Also:

getOutputStream, URLDataSource

getTransferDataFlavors

public java.awt.datatransfer.DataFlavor[] getTransferDataFlavors()

Return the DataFlavors in which this data is available.

Returns an array of DataFlavor objects indicating the flavors the data can be provided in. The array is usually ordered according to preference for providing the data,from most richly descriptive to least descriptive.

The DataHandler attempts to find a DataContentHandler that corresponds to the MIME type of the data. If one is located, the DataHandler calls the DataContentHandler's getTransferDataFlavors method. If a DataContentHandler can not be located, and if the DataHandler was created with a DataSource (or URL); one DataFlavor is returned that represents the natural type and format of the data (generally this.getContentType/InputStream). If the DataHandler was created with an object and a MIME type; getTransferDataFlavors returns one DataFlavor that represents the this.getContentType/InputStream.

Implements:

getTransferDataFlavors in interface java.awt.datatransfer.Transferable

Returns:

an array of data flavors in which this data can be transferred

See Also:

getTransferDataFlavors

isDataFlavorSupported

public boolean isDataFlavorSupported(java.awt.datatransfer.DataFlavor flavor)

Returns whether the specified data flavor is supported for this object.

This method iterates through the DataFlavors available from this object, which was the result of a call to this.getTransferDataFlavors.

Implements:

isDataFlavorSupported in interface java.awt.datatransfer.Transferable

Parameters:

flavor - the requested flavor for the data

Returns:

true if the data flavor is supported

See Also:

getTransferDataFlavors

getTransferData

public java.lang.Object getTransferData(java.awt.datatransfer.DataFlavor flavor) throws java.awt.datatransfer.UnsupportedFlavorException, java.io.IOException

Returns an object that represents the data to be transferred. The class of the object returned is defined by the representation class of the data flavor.

For DataHandler's created with DataSources or URLs:

The DataHandler attempts to locate a DataContentHandler for this MIME type. If one is found, the passed in DataFlavor and the type of the date are passed to it's getTransferData method. If the DataHandler fails to locate a DataContentHandler the default behavior is to see if the DataFlavor requested matches the natural type and representation class of of the data and return it. Otherwise null is returned.

For DataHandler's created with Objects:

The DataHandler attempts to locate a DataContentHandler for this MIME type. If one is found, the passed in DataFlavor and the type of the date are passed to it's getTransferData method. If the DataHandler fails to locate a DataContentHandler the default behavior is to see if the DataFlavor requested matches the natural type and representation class of of the data and return it. Otherwise it throws an UnsupportedFlavorException.

Implements:

getTransferData in interface java.awt.datatransfer.Transferable

Parameters:

flavor - the requested flavor for the data

Returns:

the object

Throws:

java.awt.datatransfer.UnsupportedFlavorException - if the data could not be converted to the requested flavor

java.io.IOException - if an I/O error occurs

See Also:

ActivationDataFlavor

setCommandMap

public void setCommandMap(CommandMap commandMap)

This method overrides the current CommandMap in this DataHandler. Setting it to null causes the CommandMap to revert to the CommandMap returned by the CommandMap.getDefaultCommandMap method.

Parameters:

commandMap - the CommandMap to use in this DataHandler

See Also:

setDefaultCommandMap

getPreferredCommands

public CommandInfo[] getPreferredCommands()

This method calls the getPreferredCommands method in the commandMap installed in this instance of DataHandler. This method returns an array that represents a subset of available commands. In cases where multiple commands for the MIME type represented by this DataHandler are present, the installed CommandMap chooses the appropriate commands.

Returns:

the CommandInfo objects representing the preferred commands

See Also:

getPreferredCommands

getAllCommands

public CommandInfo[] getAllCommands()

This method returns an array containing all commands for the type of data represented in the DataHandler. The MIME Type for the underlying data represented by this DataHandler is used to call through to the getAllCommands method of the currently installed CommandMap.

Returns:

the CommandInfo objects representing all the commands

See Also:

getAllCommands

getCommand

public CommandInfo getCommand(java.lang.String cmdName)

Get the command cmdName. Use the search semantics as defined by the CommandMap installed in this DataHandler. The MIME type for the underlying data represented by this DataHandler is used to call through to the getCommand method of the currently installed CommandMap.

Returns:

the CommandInfo corresponding to the command

See Also:

getCommand

getContent

public java.lang.Object getContent() throws java.io.IOException

Return the data in its preferred Object form.

If the DataHandler was instantiated with an object, return the object.

If the DataHandler was instantiated with a DataSource, this method uses a DataContentHandler to return the content object for the data represented by this DataHandler. If no DataContentHandler can be found for the the type of this data, the DataHandler throws an UnsupportedDataTypeException exception.

Returns:

the content.

Throws:

java.io.IOException - if an IOException occurs during this operation.

getBean

public java.lang.Object getBean(CommandInfo cmdinfo)

A convenience method that takes a CommandInfo object and instantiates the corresponding command, usually a JavaBean component.

This method calls the cmdInfo's getCommandObject method with the ClassLoader used to load this object.

Returns:

the instantiated command object

setDataContentHandlerFactory

public static void setDataContentHandlerFactory(DataContentHandlerFactory newFactory)

Sets the DataContentHandlerFactory. This overrides all other places in the system where the DataHandler might potentially look for DataContentHandlers. The DataContentHandler factory can only be set once.

If the DataContentHandlerFactory has already been set, this method throws an Error. The design pattern is same a java.net.URLConnection.setContentHandler.

Parameters:

factory - the DataContentHandlerFactory

See Also:

DataContentHandlerFactory