001 /*
002 * Copyright 1997-2005 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.activation;
027
028 import java.awt.datatransfer.DataFlavor;
029 import java.awt.datatransfer.UnsupportedFlavorException;
030 import java.io.InputStream;
031 import java.io.IOException;
032 import java.io.OutputStream;
033 import javax.activation.DataSource;
034
035 /**
036 * The DataContentHandler interface is implemented by objects that can
037 * be used to extend the capabilities of the DataHandler's implementation
038 * of the Transferable interface. Through <code>DataContentHandlers</code>
039 * the framework can be extended to convert streams in to objects, and
040 * to write objects to streams. <p>
041 *
042 * Applications don't generally call the methods in DataContentHandlers
043 * directly. Instead, an application calls the equivalent methods in
044 * DataHandler. The DataHandler will attempt to find an appropriate
045 * DataContentHandler that corresponds to its MIME type using the
046 * current DataContentHandlerFactory. The DataHandler then calls
047 * through to the methods in the DataContentHandler.
048 *
049 * @since 1.6
050 */
051
052 public interface DataContentHandler {
053 /**
054 * Returns an array of DataFlavor objects indicating the flavors the
055 * data can be provided in. The array should be ordered according to
056 * preference for providing the data (from most richly descriptive to
057 * least descriptive).
058 *
059 * @return The DataFlavors.
060 */
061 public DataFlavor[] getTransferDataFlavors();
062
063 /**
064 * Returns an object which represents the data to be transferred.
065 * The class of the object returned is defined by the representation class
066 * of the flavor.
067 *
068 * @param df The DataFlavor representing the requested type.
069 * @param ds The DataSource representing the data to be converted.
070 * @return The constructed Object.
071 * @exception UnsupportedFlavorException if the handler doesn't
072 * support the requested flavor
073 * @exception IOException if the data can't be accessed
074 */
075 public Object getTransferData(DataFlavor df, DataSource ds)
076 throws UnsupportedFlavorException, IOException;
077
078 /**
079 * Return an object representing the data in its most preferred form.
080 * Generally this will be the form described by the first DataFlavor
081 * returned by the <code>getTransferDataFlavors</code> method.
082 *
083 * @param ds The DataSource representing the data to be converted.
084 * @return The constructed Object.
085 * @exception IOException if the data can't be accessed
086 */
087 public Object getContent(DataSource ds) throws IOException;
088
089 /**
090 * Convert the object to a byte stream of the specified MIME type
091 * and write it to the output stream.
092 *
093 * @param obj The object to be converted.
094 * @param mimeType The requested MIME type of the resulting byte stream.
095 * @param os The output stream into which to write the converted
096 * byte stream.
097 * @exception IOException errors writing to the stream
098 */
099 public void writeTo(Object obj, String mimeType, OutputStream os)
100 throws IOException;
101 }
|