1 /*
2 * Copyright (c) 1997, 2015, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.activation;
27
28 import java.awt.datatransfer.DataFlavor;
29 import java.awt.datatransfer.UnsupportedFlavorException;
30 import java.io.InputStream;
31 import java.io.IOException;
32 import java.io.OutputStream;
33 import javax.activation.DataSource;
34
35 /**
36 * <p>The DataContentHandler interface is implemented by objects that can
37 * be used to extend the capabilities of the DataHandler's implementation
38 * of the Transferable interface. Through <code>DataContentHandlers</code>
39 * the framework can be extended to convert streams in to objects, and
40 * to write objects to streams.</p>
41 *
42 * <p>An implementation of DataContentHandler should be a public class
43 * with a public no-arg constructor. If the implementation class is in
44 * a named module then it should be in an API package that is exported
45 * to the module {@code java.activation}.</p>
46 *
47 * <p>Applications don't generally call the methods in DataContentHandlers
48 * directly. Instead, an application calls the equivalent methods in
49 * DataHandler. The DataHandler will attempt to find an appropriate
50 * DataContentHandler that corresponds to its MIME type using the
51 * current DataContentHandlerFactory. The DataHandler then calls
52 * through to the methods in the DataContentHandler.</p>
53 *
54 * @since 1.6
55 */
56
57 public interface DataContentHandler {
58 /**
59 * Returns an array of DataFlavor objects indicating the flavors the
60 * data can be provided in. The array should be ordered according to
61 * preference for providing the data (from most richly descriptive to
62 * least descriptive).
63 *
64 * @return The DataFlavors.
65 */
66 public DataFlavor[] getTransferDataFlavors();
67
68 /**
69 * Returns an object which represents the data to be transferred.
70 * The class of the object returned is defined by the representation class
71 * of the flavor.
72 *
73 * @param df The DataFlavor representing the requested type.
74 * @param ds The DataSource representing the data to be converted.
75 * @return The constructed Object.
76 * @exception UnsupportedFlavorException if the handler doesn't
77 * support the requested flavor
78 * @exception IOException if the data can't be accessed
79 */
80 public Object getTransferData(DataFlavor df, DataSource ds)
81 throws UnsupportedFlavorException, IOException;
82
83 /**
84 * Return an object representing the data in its most preferred form.
85 * Generally this will be the form described by the first DataFlavor
86 * returned by the <code>getTransferDataFlavors</code> method.
87 *
88 * @param ds The DataSource representing the data to be converted.
89 * @return The constructed Object.
90 * @exception IOException if the data can't be accessed
91 */
92 public Object getContent(DataSource ds) throws IOException;
93
94 /**
95 * Convert the object to a byte stream of the specified MIME type
96 * and write it to the output stream.
97 *
98 * @param obj The object to be converted.
99 * @param mimeType The requested MIME type of the resulting byte stream.
100 * @param os The output stream into which to write the converted
101 * byte stream.
102 * @exception IOException errors writing to the stream
103 */
104 public void writeTo(Object obj, String mimeType, OutputStream os)
105 throws IOException;
106 }