DataHandler (Java SE 9 & JDK 9 )
Keywords: javax.activation.DataHandler class

Module java.activation
Package javax.activation

## Class DataHandler

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

- All Implemented Interfaces:
    `Transferable`

      public class DataHandler
      extends Object
      implements Transferable

  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.

  Since:
    1.6
  See Also:
    `CommandMap`, `DataContentHandler`, `DataSource`, `URLDataSource`

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DataHandler​(Object obj, String mimeType)` | Create a `DataHandler` instance representing an object of this MIME type.
    `DataHandler​(URL url)` | Create a `DataHandler` instance referencing a URL.
    `DataHandler​(DataSource ds)` | Create a `DataHandler` instance referencing the specified DataSource.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `CommandInfo[]` | `getAllCommands​()` | Return all the commands for this type of data.
    `Object` | `getBean​(CommandInfo cmdinfo)` | A convenience method that takes a CommandInfo object and instantiates the corresponding command, usually a JavaBean component.
    `CommandInfo` | `getCommand​(String cmdName)` | Get the command cmdName.
    `Object` | `getContent​()` | Return the data in its preferred Object form.
    `String` | `getContentType​()` | Return the MIME type of this object as retrieved from the source object.
    `DataSource` | `getDataSource​()` | Return the DataSource associated with this instance of DataHandler.
    `InputStream` | `getInputStream​()` | Get the InputStream for this object.
    `String` | `getName​()` | Return the name of the data object.
    `OutputStream` | `getOutputStream​()` | Get an OutputStream for this DataHandler to allow overwriting the underlying data.
    `CommandInfo[]` | `getPreferredCommands​()` | Return the preferred commands for this type of data.
    `Object` | `getTransferData​(DataFlavor flavor)` | Returns an object that represents the data to be transferred.
    `DataFlavor[]` | `getTransferDataFlavors​()` | Return the DataFlavors in which this data is available.
    `boolean` | `isDataFlavorSupported​(DataFlavor flavor)` | Returns whether the specified data flavor is supported for this object.
    `void` | `setCommandMap​(CommandMap commandMap)` | Set the CommandMap for use by this DataHandler.
    `static void` | `setDataContentHandlerFactory​(DataContentHandlerFactory newFactory)` | Sets the DataContentHandlerFactory.
    `void` | `writeTo​(OutputStream os)` | Write the data to an `OutputStream`.

    - ### 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)

      Create a `DataHandler` instance referencing the specified DataSource. The data exists in a byte stream form. The DataSource will provide an InputStream to access the data.
      Parameters:
        `ds` - the DataSource

    - #### DataHandler

          public DataHandler​(Object obj,
                             String mimeType)

      Create a `DataHandler` instance representing 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​(URL url)

      Create a `DataHandler` instance referencing a URL. The DataHandler internally creates a `URLDataSource` instance to represent the URL.
      Parameters:
        `url` - a URL object

  - ### Method Detail

    - #### getDataSource

          public DataSource getDataSource​()

      Return 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

    - #### getName

          public 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 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 InputStream getInputStream​()
                                     throws IOException

      Get the InputStream for this object.

      For DataHandlers instantiated with a DataSource, the DataHandler calls the `DataSource.getInputStream` method and returns the result 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 and a thread. The thread uses the DataContentHandler's `writeTo` method to write the stream data into one end of the pipe. The other end of the pipe is returned to the caller. 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:
        `IOException` - if an I/O error occurs
      See Also:
        `DataContentHandler.writeTo(java.lang.Object, java.lang.String, java.io.OutputStream)`, `UnsupportedDataTypeException`

    - #### writeTo

          public void writeTo​(OutputStream os)
                       throws IOException

      Write the data to an `OutputStream`.

      If the DataHandler was created with a DataSource, writeTo retrieves the InputStream and copies 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:
        `IOException` - if an I/O error occurs

    - #### getOutputStream

          public OutputStream getOutputStream​()
                                       throws IOException

      Get an OutputStream for this DataHandler to allow overwriting the underlying data. If the DataHandler was created with a DataSource, the DataSource's `getOutputStream` method is called. Otherwise, `null` is returned.
      Returns:
        the OutputStream
      Throws:
        `IOException` - for failures creating the OutputStream
      See Also:
        `DataSource.getOutputStream()`, `URLDataSource`

    - #### getTransferDataFlavors

          public 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 richly 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 this object's MIME type and the `java.io.InputStream` class. If the DataHandler was created with an object and a MIME type, getTransferDataFlavors returns one DataFlavor that represents this object's MIME type and the object's class.

      Specified by:
        `getTransferDataFlavors` in interface `Transferable`
      Returns:
        an array of data flavors in which this data can be transferred
      See Also:
        `DataContentHandler.getTransferDataFlavors()`

    - #### isDataFlavorSupported

          public boolean isDataFlavorSupported​(DataFlavor flavor)

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

      This method iterates through the DataFlavors returned from `getTransferDataFlavors`, comparing each with the specified flavor.

      Specified by:
        `isDataFlavorSupported` in interface `Transferable`
      Parameters:
        `flavor` - the requested flavor for the data
      Returns:
        true if the data flavor is supported
      See Also:
        `getTransferDataFlavors()`

    - #### getTransferData

          public Object getTransferData​(DataFlavor flavor)
                                 throws UnsupportedFlavorException,
                                        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 data are passed to its `getTransferData` method. If the DataHandler fails to locate a DataContentHandler and the flavor specifies this object's MIME type and the `java.io.InputStream` class, this object's InputStream is returned. Otherwise it throws an UnsupportedFlavorException.

      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 data are passed to its getTransferData method. If the DataHandler fails to locate a DataContentHandler and the flavor specifies this object's MIME type and its class, this DataHandler's referenced object is returned. Otherwise it throws an UnsupportedFlavorException.

      Specified by:
        `getTransferData` in interface `Transferable`
      Parameters:
        `flavor` - the requested flavor for the data
      Returns:
        the object
      Throws:
        `UnsupportedFlavorException` - if the data could not be converted to the requested flavor
        `IOException` - if an I/O error occurs
      See Also:
        `ActivationDataFlavor`

    - #### setCommandMap

          public void setCommandMap​(CommandMap commandMap)

      Set the CommandMap for use by this DataHandler. Setting it to `null` causes the CommandMap to revert to the CommandMap returned by the `CommandMap.getDefaultCommandMap` method. Changing the CommandMap, or setting it to `null`, clears out any data cached from the previous CommandMap.
      Parameters:
        `commandMap` - the CommandMap to use in this DataHandler
      See Also:
        `CommandMap.setDefaultCommandMap(javax.activation.CommandMap)`

    - #### getPreferredCommands

          public CommandInfo[] getPreferredCommands​()

      Return the preferred commands for this type of data. This method calls the `getPreferredCommands` method in the CommandMap associated with 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:
        `CommandMap.getPreferredCommands(java.lang.String)`

    - #### getAllCommands

          public CommandInfo[] getAllCommands​()

      Return all the commands for this type of data. This method returns an array containing all commands for the type of data represented by this DataHandler. The MIME type for the underlying data represented by this DataHandler is used to call through to the `getAllCommands` method of the CommandMap associated with this DataHandler.
      Returns:
        the CommandInfo objects representing all the commands
      See Also:
        `CommandMap.getAllCommands(java.lang.String)`

    - #### getCommand

          public CommandInfo getCommand​(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 CommandMap associated with this DataHandler.
      Parameters:
        `cmdName` - the command name
      Returns:
        the CommandInfo corresponding to the command
      See Also:
        `CommandMap.getCommand(java.lang.String, java.lang.String)`

    - #### getContent

          public Object getContent​()
                            throws 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 returns an InputStream for the data.

      Returns:
        the content.
      Throws:
        `IOException` - if an IOException occurs during this operation.

    - #### getBean

          public 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 CommandInfo's `getCommandObject` method with the `ClassLoader` used to load the `javax.activation.DataHandler` class itself.

      Parameters:
        `cmdinfo` - the CommandInfo corresponding to a command
      Returns:
        the instantiated command object

    - #### setDataContentHandlerFactory

          public static void setDataContentHandlerFactory​(DataContentHandlerFactory newFactory)

      Sets the DataContentHandlerFactory. The DataContentHandlerFactory is called first to find DataContentHandlers. The DataContentHandlerFactory can only be set once.

      If the DataContentHandlerFactory has already been set, this method throws an Error.

      Parameters:
        `newFactory` - the DataContentHandlerFactory
      Throws:
        `Error` - if the factory has already been defined.
      See Also:
        `DataContentHandlerFactory`