DataHandler (Java EE 5)

DataHandler 和 Transferable 接口

DataHandler 实现 Transferable 接口，以便数据能够用于 AWT 数据传输操作，比如，剪切、粘贴和拖放操作。Transferable 接口的实现依赖于已安装的 DataContentHandler 对象的可用性，该 DataContentHandler 对象与 DataHandler 的特定实例中所表示的数据的 MIME 类型相对应。

DataHandler 和 CommandMap

DataHandler 跟踪当前 CommandMap，它用于命令（getCommand、getAllCommands、getPreferredCommands）的服务请求。使用 setCommandMap 方法，DataHandler 的每个实例都可以有一个与其相关的 CommandMap。如果没有设置 CommandMap，则 DataHandler 调用 CommandMap 中的 getDefaultCommandMap 方法，并使用其返回值。有关更多信息，请参见 CommandMap。

DataHandler 和 URL

当用 URL 构造 DataHandler 时，当前 DataHandler 实现创建一个 URLDataSource 的私有实例。

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.

See Also:

CommandMap, DataContentHandler, DataSource, URLDataSource

public DataHandler(DataSource ds)
创建引用指定 DataSource 的 DataHandler 实例。数据以字节流的形式存在。DataSource 将提供一个 InputStream 来访问数据。

ds	DataSource

英文文档：

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

public DataHandler(Object obj, String mimeType)
创建表示此 MIME 类型对象的 DataHandler 实例。当应用程序已经有 Java Object 形式的数据内存表示形式 (in-memory representation) 时，使用此构造方法。

obj	Java Object
mimeType	对象的 MIME 类型

英文文档：

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

public DataHandler(java.net.URL url)
创建引用 URL 的 DataHandler 实例。DataHandler 在内部创建一个 URLDataSource 实例来表示 URL。

url

URL 对象

英文文档：

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

public DataSource getDataSource()
返回与此 DataHandler 实例关联的 DataSource。

对于已经用 DataSource 实例化的 DataHandler，此方法返回用来创建该 DataHandler 对象的 DataSource。在其他情况下，DataHandler 根据用来构造 DataHandler 的数据构造 DataSource。对于没有用 DataSource 实例化的 DataHandler，为其创建的 DataSource 将被缓存，以提高性能。

return

对此 DataHandler 有效的 DataSource 对象

英文文档：

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

public String getName()
返回数据对象的名称。如果此 DataHandler 是用 DataSource 创建的，则此方法直接调用 DataSource.getName 方法；否则返回 null。

return

对象的名称

英文文档：

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

public String getContentType()
返回从源对象中获取的此对象的 MIME 类型。注意，这是带有参数的完整 类型。

return

MIME 类型

英文文档：

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

public java.io.InputStream getInputStream() throws java.io.IOException
获取此对象的 InputSteam。

对于用 DataSource 实例化的 DataHandler，该 DataHandler 调用 DataSource.getInputStream 方法，并将结果返回给调用者。

对于用 Object 实例化的 DataHandler，该 DataHandler 首先尝试找到 Object 的 DataContentHandler。如果 DataHandler 找不到此 MIME 类型的 DataContentHandler，则抛出 UnsupportedDataTypeException。如果能够找到，则它将创建一个管道和一个线程。该线程使用 DataContentHandler 的 writeTo 方法将流数据写入管道的一端。管道的另一端返回给调用者。由于为复制数据创建了一个线程，所以在复制过程中发生的 IOException 不能传送回调用者。结果将是一个空流。

return	表示此数据的 InputStream
Throws	java.io.IOException: 如果发生 I/O * 错误
See also	writeTo, javax.activation.UnsupportedDataTypeException

英文文档：

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

public void writeTo(java.io.OutputStream os) throws java.io.IOException
将数据写入 OutputStream。

如果 DataHandler 是用 DataSource 创建的，那么 writeTo 获取 InputStream 并将字节从 Inputstream 复制到传入的 Outputstream。

如果 DataHandler 是用 Object 创建的，则 writeTo 获取对象类型的 DataContentHandler。如果找到了 DataContentHandler，则它对 DataContentHandler 调用 writeTo 方法。

os	要写入的 OutputStream
Throws	java.io.IOException: 如果发生 I/O * 错误

英文文档：

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

public java.io.OutputStream getOutputStream() throws java.io.IOException
获取此 DataHandler 的 OutputStream，以允许重写底层数据。如果 DataHandler 是用 DataSource 创建的，则调用 DataSource 的 getOutputStream 方法。否则，返回 null。

return	OutputStream
See also	getOutputStream, javax.activation.URLDataSource

英文文档：

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

See Also:

DataSource.getOutputStream(), URLDataSource

public java.awt.datatransfer.DataFlavor[] getTransferDataFlavors()
返回此数据在其中可用的 DataFlavor。

返回能够提供数据的 flavor 的 DataFlavor 对象所组成的数组。该数组通常根据提供数据的首选项来排序（从描述最多的到描述最少的）。

DataHandler 尝试查找与数据的 MIME 类型对应的 DataContentHandler。如果找到，则该 DataHandler 调用 DataContentHandler 的 getTransferDataFlavors 方法。

如果不 能找到 DataContentHandler，并且 DataHandler 是用 DataSource （或 URL）创建的，则返回一个表示此对象 MIME 类型和 java.io.InputStream 类的 DataFlavor。如果 DataHandler 是用对象和 MIME 类型创建的，则 getTransferDataFlavors 返回一个表示此对象 MIME 类型和对象类的 DataFlavor。

return	数据 flavor 的数组，使用它来传输此数据
See also	getTransferDataFlavors

英文文档：

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

public boolean isDataFlavorSupported(java.awt.datatransfer.DataFlavor flavor)
返回此对象是否支持指定的数据 flavor。

此方法迭代 getTransferDataFlavors 返回的 DataFlavor，将每个 DataFlavor 与指定 flavor 进行比较。

flavor	数据所请求的 flavor
return	如果支持该数据 flavor，则返回 true
See also	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()

public Object getTransferData(java.awt.datatransfer.DataFlavor flavor) throws java.awt.datatransfer.UnsupportedFlavorException, java.io.IOException
返回一个对象，该对象表示要传输的数据。返回对象的类是由该数据 flavor 的表示形式类定义的。

对于用 DataSource 或 URL 创建的 DataHandler：

DataHandler 尝试为此 MIME 类型查找一个 DataContentHandler。如果找到，则将传入的 DataFlavor 和数据的类型传递给其 getTransferData 方法。如果 DataHandler 没有找到 DataContentHandler，并且 flavor 指定了此对象的 MIME 类型和 java.io.InputStream 类，则返回此对象的 InputStream。否则，抛出 UnsupportedFlavorException。

对于用 Object 创建的 DataHandler：

DataHandler 尝试为此 MIME 类型查找一个 DataContentHandler。如果找到，则将传入的 DataFlavor 和数据的类型传递给其 getTransferData 方法。如果 DataHandler 没有找到 DataContentHandler，并且 flavor 指定了此对象的 MIME 类型和它的类，则返回此 DataHandler 的引用对象。否则，抛出 UnsupportedFlavorException。

flavor	数据所请求的 flavor
return	对象
Throws	java.awt.datatransfer.UnsupportedFlavorException: 如果不能将该数据转换为所请求的 flavor
Throws	java.io.IOException: 如果发生 I/O * 错误
See also	javax.activation.ActivationDataFlavor

英文文档：

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

public void setCommandMap(CommandMap commandMap)
设置此 DataHandler 使用的 CommandMap。将其设置为 null 会使该 CommandMap 还原为 CommandMap.getDefaultCommandMap 方法所返回的 CommandMap。更改该 CommandMap 或将其设置为 null 将清除以前的 CommandMap 所缓存的所有数据。

commandMap	此 DataHandler 中使用的 CommandMap
See also	setDefaultCommandMap

英文文档：

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)

public CommandInfo[] getPreferredCommands()
返回此数据类型的首选 命令。此方法调用 CommandMap 中与此 DataHandler 实例关联的 getPreferredCommands 方法。此方法返回一个表示可用命令子集的数组。如果存在由此 DataHandler 表示的 MIME 类型的多个命令，则已安装的 CommandMap 将选择适当的命令。

return	表示首选命令的 CommandInfo 对象
See also	getPreferredCommands

英文文档：

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)

public CommandInfo[] getAllCommands()
返回此数据类型的所有命令。此方法返回一个数组，此数组包含此 DataHandler 所表示的数据类型的所有命令。此 DataHandler 所表示的底层数据的 MIME 类型用于调用与此 DataHandler 关联的 CommandMap 的 getAllCommands 方法。

return	表示所有命令的 CommandInfo 对象
See also	getAllCommands

英文文档：

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)

public CommandInfo getCommand(String cmdName)
获取命令 cmdName。使用此 DataHandler 中已安装的 CommandMap 所定义的搜索语义。此 DataHandler 所表示的底层数据的 MIME 类型用于调用与此 DataHandler 关联的 CommandMap 的 getCommand 方法。

cmdName	命令名
return	与命令对应的 CommandInfo
See also	getCommand

英文文档：

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)

public Object getContent() throws java.io.IOException
以其首选 Object 的形式返回数据。

如果 DataHandler 是用一个对象实例化的，则返回该对象。

如果 DataHandler 是用 DataSource 实例化的，则此方法使用 DataContentHandler 返回此 DataHandler 所表示数据的内容对象。如果找不到此数据类型的 DataContentHandler，则 DataHandler 返回数据的 InputStream。

return	内容。
Throws	java.io.IOException: 如果此操作中发生 IOException。

英文文档：

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.

public Object getBean(CommandInfo cmdinfo)
一个便捷方法，它接受 CommandInfo 对象并且实例化相应的命令，通常是 JavaBean 组件。

此方法调用 CommandInfo 的 getCommandObject 方法，带有用于加载 javax.activation.DataHandler 类本身的 ClassLoader。

cmdinfo	与命令对应的 CommandInfo
return	已实例化的命令对象

英文文档：

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

public static void setDataContentHandlerFactory(DataContentHandlerFactory newFactory)
设置 DataContentHandlerFactory。首先调用 DataContentHandlerFactory 来查找 DataContentHandler。DataContentHandlerFactory 只能被设置一次。

如果 DataContentHandlerFactory 已经被设置，则此方法抛出 Error。

newFactory	DataContentHandlerFactory
Throws	Error: 如果已经定义该工厂。
See also	javax.activation.DataContentHandlerFactory

英文文档：

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

Copyright 2007 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.