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
26package javax.activation;
27
28import java.awt.datatransfer.DataFlavor;
29import java.awt.datatransfer.UnsupportedFlavorException;
30import java.io.InputStream;
31import java.io.IOException;
32import java.io.OutputStream;
33import 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
57public 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}
107