Java > Open Source Codes > java > awt > datatransfer > DataFlavor


1 /*
2  * @(#)DataFlavor.java 1.79 04/05/18
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package java.awt.datatransfer;
9
10 import java.awt.Toolkit ;
11 import java.io.*;
12 import java.nio.*;
13 import java.util.*;
14
15 import sun.awt.datatransfer.DataTransferer;
16
17 /**
18  * Each instance represents the opaque concept of a data format as would
19  * appear on a clipboard, during drag and drop, or in a file system.
20  * <p>
21  * <code>DataFlavor</code> objects are constant and never change once
22  * instantiated.
23  * <p>
24  * For information on using data transfer with Swing, see
25  * <a HREF="http://java.sun.com/docs/books/tutorial/uiswing/misc/dnd.html">
26  * How to Use Drag and Drop and Data Transfer</a>,
27  * a section in <em>The Java Tutorial</em>, for more information.
28  *
29  * @version 1.79, 05/18/04
30  * @author Blake Sullivan
31  * @author Laurence P. G. Cable
32  * @author Jeff Dunn
33  */
34 public class DataFlavor implements Externalizable, Cloneable {
35     
36     private static final long serialVersionUID = 8367026044764648243L;
37     private static final Class ioInputStreamClass = java.io.InputStream .class;
38
39     /**
40      * Tries to load a class from: the bootstrap loader, the system loader,
41      * the context loader (if one is present) and finally the loader specified.
42      *
43      * @param className the name of the class to be loaded
44      * @param fallback the fallback loader
45      * @return the class loaded
46      * @exception ClassNotFoundException if class is not found
47      */
48     protected final static Class <?> tryToLoadClass(String className,
49                            ClassLoader fallback)
50         throws ClassNotFoundException
51     {
52     ClassLoader systemClassLoader = (ClassLoader )
53         java.security.AccessController.doPrivileged(
54                 new java.security.PrivilegedAction () {
55             public Object run() {
56             ClassLoader cl = Thread.currentThread().
57                 getContextClassLoader();
58             return (cl != null)
59                 ? cl
60                 : ClassLoader.getSystemClassLoader();
61             }
62             });
63     
64     try {
65         return Class.forName(className, true, systemClassLoader);
66     } catch (ClassNotFoundException e2) {
67         if (fallback != null) {
68         return Class.forName(className, true, fallback);
69         } else {
70         throw new ClassNotFoundException (className);
71         }
72     }
73     }
74     
75     /*
76      * private initializer
77      */
78     static private DataFlavor createConstant(Class rc, String prn) {
79         try {
80             return new DataFlavor (rc, prn);
81         } catch (Exception e) {
82             return null;
83         }
84     }
85     
86     /*
87      * private initializer
88      */
89     static private DataFlavor createConstant(String mt, String prn) {
90         try {
91             return new DataFlavor (mt, prn);
92         } catch (Exception e) {
93             return null;
94         }
95     }
96     
97     /**
98      * The <code>DataFlavor</code> representing a Java Unicode String class,
99      * where:
100      * <pre>
101      * representationClass = java.lang.String
102      * mimeType = "application/x-java-serialized-object"
103      * </pre>
104      */
105     public static final DataFlavor stringFlavor = createConstant(java.lang.String .class, "Unicode String");
106     
107     /**
108      * The <code>DataFlavor</code> representing a Java Image class,
109      * where:
110      * <pre>
111      * representationClass = java.awt.Image
112      * mimeType = "image/x-java-image"
113      * </pre>
114      */
115     public static final DataFlavor imageFlavor = createConstant("image/x-java-image; class=java.awt.Image", "Image");
116     
117     /**
118      * The <code>DataFlavor</code> representing plain text with Unicode
119      * encoding, where:
120      * <pre>
121      * representationClass = InputStream
122      * mimeType = "text/plain; charset=unicode"
123      * </pre>
124      * This <code>DataFlavor</code> has been <b>deprecated</b> because
125      * (1) Its representation is an InputStream, an 8-bit based representation,
126      * while Unicode is a 16-bit character set; and (2) The charset "unicode"
127      * is not well-defined. "unicode" implies a particular platform's
128      * implementation of Unicode, not a cross-platform implementation.
129      *
130      * @deprecated as of 1.3. Use <code>DataFlavor.getReaderForText(Transferable)</code>
131      * instead of <code>Transferable.getTransferData(DataFlavor.plainTextFlavor)</code>.
132      */
133     @Deprecated
134     public static final DataFlavor plainTextFlavor = createConstant("text/plain; charset=unicode; class=java.io.InputStream", "Plain Text");
135     
136     /**
137      * A MIME Content-Type of application/x-java-serialized-object represents
138      * a graph of Java object(s) that have been made persistent.
139      *
140      * The representation class associated with this <code>DataFlavor</code>
141      * identifies the Java type of an object returned as a reference
142      * from an invocation <code>java.awt.datatransfer.getTransferData</code>.
143      */
144     public static final String javaSerializedObjectMimeType = "application/x-java-serialized-object";
145     
146     /**
147      * To transfer a list of files to/from Java (and the underlying
148      * platform) a <code>DataFlavor</code> of this type/subtype and
149      * representation class of <code>java.util.List</code> is used.
150      * Each element of the list is required/guaranteed to be of type
151      * <code>java.io.File</code>.
152      */
153     public static final DataFlavor javaFileListFlavor = createConstant("application/x-java-file-list;class=java.util.List", null);
154
155     /**
156      * To transfer a reference to an arbitrary Java object reference that
157      * has no associated MIME Content-type, across a <code>Transferable</code>
158      * interface WITHIN THE SAME JVM, a <code>DataFlavor</code>
159      * with this type/subtype is used, with a <code>representationClass</code>
160      * equal to the type of the class/interface being passed across the
161      * <code>Transferable</code>.
162      * <p>
163      * The object reference returned from
164      * <code>Transferable.getTransferData</code> for a <code>DataFlavor</code>
165      * with this MIME Content-Type is required to be
166      * an instance of the representation Class of the <code>DataFlavor</code>.
167      */
168     public static final String javaJVMLocalObjectMimeType = "application/x-java-jvm-local-objectref";
169     
170     /**
171      * In order to pass a live link to a Remote object via a Drag and Drop
172      * <code>ACTION_LINK</code> operation a Mime Content Type of
173      * application/x-java-remote-object should be used,
174      * where the representation class of the <code>DataFlavor</code>
175      * represents the type of the <code>Remote</code> interface to be
176      * transferred.
177      */
178     public static final String javaRemoteObjectMimeType = "application/x-java-remote-object";
179
180     /**
181      * Constructs a new <code>DataFlavor</code>. This constructor is
182      * provided only for the purpose of supporting the
183      * <code>Externalizable</code> interface. It is not
184      * intended for public (client) use.
185      *
186      * @since 1.2
187      */
188     public DataFlavor() {
189         super();
190     }
191
192     /**
193      * Constructs a fully specified <code>DataFlavor</code>.
194      *
195      * @exception NullPointerException if either <code>primaryType</code>,
196      * <code>subType</code> or <code>representationClass</code> is null
197      */
198     private DataFlavor(String primaryType, String subType, MimeTypeParameterList params, Class representationClass, String humanPresentableName) {
199         super();
200         if (primaryType == null) {
201             throw new NullPointerException ("primaryType");
202         }
203         if (subType == null) {
204             throw new NullPointerException ("subType");
205         }
206         if (representationClass == null) {
207             throw new NullPointerException ("representationClass");
208         }
209         
210         if (params == null) params = new MimeTypeParameterList ();
211         
212         params.set("class", representationClass.getName());
213         
214         if (humanPresentableName == null) {
215             humanPresentableName = (String )params.get("humanPresentableName");
216             
217             if (humanPresentableName == null)
218                 humanPresentableName = primaryType + "/" + subType;
219         }
220         
221         try {
222             mimeType = new MimeType (primaryType, subType, params);
223         } catch (MimeTypeParseException mtpe) {
224             throw new IllegalArgumentException ("MimeType Parse Exception: " + mtpe.getMessage());
225         }
226         
227         this.representationClass = representationClass;
228         this.humanPresentableName = humanPresentableName;
229         
230         mimeType.removeParameter("humanPresentableName");
231     }
232     
233     /**
234      * Constructs a <code>DataFlavor</code> that represents a Java class.
235      * <p>
236      * The returned <code>DataFlavor</code> will have the following
237      * characteristics:
238      * <pre>
239      * representationClass = representationClass
240      * mimeType = application/x-java-serialized-object
241      * </pre>
242      * @param representationClass the class used to transfer data in this flavor
243      * @param humanPresentableName the human-readable string used to identify
244      * this flavor; if this parameter is <code>null</code>
245      * then the value of the the MIME Content Type is used
246      * @exception NullPointerException if <code>representationClass</code> is null
247      */
248     public DataFlavor(Class <?> representationClass, String humanPresentableName) {
249         this("application", "x-java-serialized-object", null, representationClass, humanPresentableName);
250         if (representationClass == null) {
251             throw new NullPointerException ("representationClass");
252         }
253     }
254
255     /**
256      * Constructs a <code>DataFlavor</code> that represents a
257      * <code>MimeType</code>.
258      * <p>
259      * The returned <code>DataFlavor</code> will have the following
260      * characteristics:
261      * <p>
262      * If the <code>mimeType</code> is
263      * "application/x-java-serialized-object; class=&lt;representation class&gt;",
264      * the result is the same as calling
265      * <code>new DataFlavor(Class:forName(&lt;representation class&gt;)</code>.
266      * <p>
267      * Otherwise:
268      * <pre>
269      * representationClass = InputStream
270      * mimeType = mimeType
271      * </pre>
272      * @param mimeType the string used to identify the MIME type for this flavor;
273      * if the the <code>mimeType</code> does not specify a
274      * "class=" parameter, or if the class is not successfully
275      * loaded, then an <code>IllegalArgumentException</code>
276      * is thrown
277      * @param humanPresentableName the human-readable string used to identify
278      * this flavor; if this parameter is <code>null</code>
279      * then the value of the the MIME Content Type is used
280      * @exception IllegalArgumentException if <code>mimeType</code> is
281      * invalid or if the class is not successfully loaded
282      * @exception NullPointerException if <code>mimeType</code> is null
283      */
284     public DataFlavor(String mimeType, String humanPresentableName) {
285         super();
286         if (mimeType == null) {
287             throw new NullPointerException ("mimeType");
288         }
289         try {
290             initialize(mimeType, humanPresentableName, this.getClass().getClassLoader());
291         } catch (MimeTypeParseException mtpe) {
292             throw new IllegalArgumentException ("failed to parse:" + mimeType);
293         } catch (ClassNotFoundException cnfe) {
294             throw new IllegalArgumentException ("can't find specified class: " + cnfe.getMessage());
295         }
296     }
297     
298     /**
299      * Constructs a <code>DataFlavor</code> that represents a
300      * <code>MimeType</code>.
301      * <p>
302      * The returned <code>DataFlavor</code> will have the following
303      * characteristics:
304      * <p>
305      * If the mimeType is
306      * "application/x-java-serialized-object; class=&lt;representation class&gt;",
307      * the result is the same as calling
308      * <code>new DataFlavor(Class:forName(&lt;representation class&gt;)</code>.
309      * <p>
310      * Otherwise:
311      * <pre>
312      * representationClass = InputStream
313      * mimeType = mimeType
314      * </pre>
315      * @param mimeType the string used to identify the MIME type for this flavor
316      * @param humanPresentableName the human-readable string used to
317      * identify this flavor
318      * @param classLoader the class loader to use
319      * @exception ClassNotFoundException if the class is not loaded
320      * @exception IllegalArgumentException if <code>mimeType</code> is
321      * invalid
322      * @exception NullPointerException if <code>mimeType</code> is null
323      */
324     public DataFlavor(String mimeType, String humanPresentableName, ClassLoader classLoader) throws ClassNotFoundException {
325     super();
326         if (mimeType == null) {
327             throw new NullPointerException ("mimeType");
328         }
329     try {
330             initialize(mimeType, humanPresentableName, classLoader);
331         } catch (MimeTypeParseException mtpe) {
332             throw new IllegalArgumentException ("failed to parse:" + mimeType);
333         }
334     }
335     
336     /**
337      * Constructs a <code>DataFlavor</code> from a <code>mimeType</code> string.
338      * The string can specify a "class=<fully specified Java class name>"
339      * parameter to create a <code>DataFlavor</code> with the desired
340      * representation class. If the string does not contain "class=" parameter,
341      * <code>java.io.InputStream</code> is used as default.
342      *
343      * @param mimeType the string used to identify the MIME type for this flavor;
344      * if the class specified by "class=" parameter is not
345      * successfully loaded, then an
346      * <code>ClassNotFoundException</code> is thrown
347      * @exception ClassNotFoundException if the class is not loaded
348      * @exception IllegalArgumentException if <code>mimeType</code> is
349      * invalid
350      * @exception NullPointerException if <code>mimeType</code> is null
351      */
352     public DataFlavor(String mimeType) throws ClassNotFoundException {
353         super();
354         if (mimeType == null) {
355             throw new NullPointerException ("mimeType");
356         }
357         try {
358             initialize(mimeType, null, this.getClass().getClassLoader());
359         } catch (MimeTypeParseException mtpe) {
360             throw new IllegalArgumentException ("failed to parse:" + mimeType);
361         }
362     }
363
364    /**
365     * Common initialization code called from various constructors.
366     *
367     * @param mimeType the MIME Content Type (must have a class= param)
368     * @param humanPresentableName the human Presentable Name or
369     * <code>null</code>
370     * @param classLoader the fallback class loader to resolve against
371     *
372     * @throws MimeTypeParseException
373     * @throws ClassNotFoundException
374     * @throws NullPointerException if <code>mimeType</code> is null
375     *
376     * @see tryToLoadClass
377     */
378     private void initialize(String mimeType, String humanPresentableName, ClassLoader classLoader) throws MimeTypeParseException , ClassNotFoundException {
379         if (mimeType == null) {
380             throw new NullPointerException ("mimeType");
381         }
382         
383         this.mimeType = new MimeType (mimeType); // throws
384
385     String rcn = getParameter("class");
386     
387     if (rcn == null) {
388             if ("application/x-java-serialized-object".equals(this.mimeType.getBaseType()))
389             
390                 throw new IllegalArgumentException ("no representation class specified for:" + mimeType);
391             else
392                 representationClass = java.io.InputStream .class; // default
393 } else { // got a class name
394 representationClass = DataFlavor.tryToLoadClass(rcn, classLoader);
395         }
396         
397         this.mimeType.setParameter("class", representationClass.getName());
398         
399         if (humanPresentableName == null) {
400             humanPresentableName = this.mimeType.getParameter("humanPresentableName");
401             if (humanPresentableName == null)
402                 humanPresentableName = this.mimeType.getPrimaryType() + "/" + this.mimeType.getSubType();
403         }
404         
405         this.humanPresentableName = humanPresentableName; // set it.
406
407         this.mimeType.removeParameter("humanPresentableName"); // just in case
408 }
409
410     /**
411      * String representation of this <code>DataFlavor</code> and its
412      * parameters. The resulting <code>String</code> contains the name of
413      * the <code>DataFlavor</code> class, this flavor's MIME type, and its
414      * representation class. If this flavor has a primary MIME type of "text",
415      * supports the charset parameter, and has an encoded representation, the
416      * flavor's charset is also included. See <code>selectBestTextFlavor</code>
417      * for a list of text flavors which support the charset parameter.
418      *
419      * @return string representation of this <code>DataFlavor</code>
420      * @see #selectBestTextFlavor
421      */
422     public String toString() {
423         String string = getClass().getName();
424         string += "["+paramString()+"]";
425         return string;
426     }
427     
428     private String paramString() {
429         String params = "";
430         params += "mimetype=";
431         if (mimeType == null) {
432             params += "null";
433         } else {
434             params += mimeType.getBaseType();
435         }
436         params += ";representationclass=";
437         if (representationClass == null) {
438            params += "null";
439         } else {
440            params += representationClass.getName();
441         }
442         if (DataTransferer.isFlavorCharsetTextType(this) &&
443             (isRepresentationClassInputStream() ||
444              isRepresentationClassByteBuffer() ||
445              DataTransferer.byteArrayClass.equals(representationClass)))
446         {
447             params += ";charset=" + DataTransferer.getTextCharset(this);
448         }
449         return params;
450     }
451
452     /**
453      * Returns a <code>DataFlavor</code> representing plain text with Unicode
454      * encoding, where:
455      * <pre>
456      * representationClass = java.io.InputStream
457      * mimeType = "text/plain;
458      * charset=&lt;platform default Unicode encoding&gt;"
459      * </pre>
460      * Sun's implementation for Microsoft Windows uses the encoding <code>utf-16le</code>.
461      * Sun's implementation for Solaris and Linux uses the encoding
462      * <code>iso-10646-ucs-2</code>.
463      *
464      * @return a <code>DataFlavor</code> representing plain text
465      * with Unicode encoding
466      */
467     public static final DataFlavor getTextPlainUnicodeFlavor() {
468     String encoding = null;
469     DataTransferer transferer = DataTransferer.getInstance();
470     if (transferer != null) {
471         encoding = transferer.getDefaultUnicodeEncoding();
472     }
473     return new DataFlavor (
474         "text/plain;charset="+encoding
475         +";class=java.io.InputStream", "Plain Text");
476     }
477
478     /**
479      * Selects the best text <code>DataFlavor</code> from an array of <code>
480      * DataFlavor</code>s. Only <code>DataFlavor.stringFlavor</code>, and
481      * equivalent flavors, and flavors that have a primary MIME type of "text",
482      * are considered for selection.
483      * <p>
484      * Flavors are first sorted by their MIME types in the following order:
485      * <ul>
486      * <li>"text/sgml"
487      * <li>"text/xml"
488      * <li>"text/html"
489      * <li>"text/rtf"
490      * <li>"text/enriched"
491      * <li>"text/richtext"
492      * <li>"text/uri-list"
493      * <li>"text/tab-separated-values"
494      * <li>"text/t140"
495      * <li>"text/rfc822-headers"
496      * <li>"text/parityfec"
497      * <li>"text/directory"
498      * <li>"text/css"
499      * <li>"text/calendar"
500      * <li>"application/x-java-serialized-object"
501      * <li>"text/plain"
502      * <li>"text/&lt;other&gt;"
503      * </ul>
504      * <p>For example, "text/sgml" will be selected over
505      * "text/html", and <code>DataFlavor.stringFlavor</code> will be chosen
506      * over <code>DataFlavor.plainTextFlavor</code>.
507      * <p>
508      * If two or more flavors share the best MIME type in the array, then that
509      * MIME type will be checked to see if it supports the charset parameter.
510      * <p>
511      * The following MIME types support, or are treated as though they support,
512      * the charset parameter:
513      * <ul>
514      * <li>"text/sgml"
515      * <li>"text/xml"
516      * <li>"text/html"
517      * <li>"text/enriched"
518      * <li>"text/richtext"
519      * <li>"text/uri-list"
520      * <li>"text/directory"
521      * <li>"text/css"
522      * <li>"text/calendar"
523      * <li>"application/x-java-serialized-object"
524      * <li>"text/plain"
525      * </ul>
526      * The following MIME types do not support, or are treated as though they
527      * do not support, the charset parameter:
528      * <ul>
529      * <li>"text/rtf"
530      * <li>"text/tab-separated-values"
531      * <li>"text/t140"
532      * <li>"text/rfc822-headers"
533      * <li>"text/parityfec"
534      * </ul>
535      * For "text/&lt;other&gt;" MIME types, the first time the JRE needs to
536      * determine whether the MIME type supports the charset parameter, it will
537      * check whether the parameter is explicitly listed in an arbitrarily
538      * chosen <code>DataFlavor</code> which uses that MIME type. If so, the JRE
539      * will assume from that point on that the MIME type supports the charset
540      * parameter and will not check again. If the parameter is not explicitly
541      * listed, the JRE will assume from that point on that the MIME type does
542      * not support the charset parameter and will not check again. Because
543      * this check is performed on an arbitrarily chosen
544      * <code>DataFlavor</code>, developers must ensure that all
545      * <code>DataFlavor</code>s with a "text/&lt;other&gt;" MIME type specify
546      * the charset parameter if it is supported by that MIME type. Developers
547      * should never rely on the JRE to substitute the platform's default
548      * charset for a "text/&lt;other&gt;" DataFlavor. Failure to adhere to this
549      * restriction will lead to undefined behavior.
550      * <p>
551      * If the best MIME type in the array does not support the charset
552      * parameter, the flavors which share that MIME type will then be sorted by
553      * their representation classes in the following order:
554      * <code>java.io.InputStream</code>, <code>java.nio.ByteBuffer</code>,
555      * <code>[B</code>, &lt;all others&gt;.
556      * <p>
557      * If two or more flavors share the best representation class, or if no
558      * flavor has one of the three specified representations, then one of those
559      * flavors will be chosen non-deterministically.
560      * <p>
561      * If the best MIME type in the array does support the charset parameter,
562      * the flavors which share that MIME type will then be sorted by their
563      * representation classes in the following order:
564      * <code>java.io.Reader</code>, <code>java.lang.String</code>,
565      * <code>java.nio.CharBuffer</code>, <code>[C</code>, &lt;all others&gt;.
566      * <p>
567      * If two or more flavors share the best representation class, and that
568      * representation is one of the four explicitly listed, then one of those
569      * flavors will be chosen non-deterministically. If, however, no flavor has
570      * one of the four specified representations, the flavors will then be
571      * sorted by their charsets. Unicode charsets, such as "UTF-16", "UTF-8",
572      * "UTF-16BE", "UTF-16LE", and their aliases, are considered best. After
573      * them, the platform default charset and its aliases are selected.
574      * "US-ASCII" and its aliases are worst. All other charsets are chosen in
575      * alphabetical order, but only charsets supported by this implementation
576      * of the Java platform will be considered.
577      * <p>
578      * If two or more flavors share the best charset, the flavors will then
579      * again be sorted by their representation classes in the following order:
580      * <code>java.io.InputStream</code>, <code>java.nio.ByteBuffer</code>,
581      * <code>[B</code>, &lt;all others&gt;.
582      * <p>
583      * If two or more flavors share the best representation class, or if no
584      * flavor has one of the three specified representations, then one of those
585      * flavors will be chosen non-deterministically.
586      *
587      * @param availableFlavors an array of available <code>DataFlavor</code>s
588      * @return the best (highest fidelity) flavor according to the rules
589      * specified above, or <code>null</code>,
590      * if <code>availableFlavors</code> is <code>null</code>,
591      * has zero length, or contains no text flavors
592      * @since 1.3
593      */
594     public static final DataFlavor selectBestTextFlavor(
595                                        DataFlavor [] availableFlavors) {
596         if (availableFlavors == null || availableFlavors.length == 0) {
597             return null;
598         }
599
600         if (textFlavorComparator == null) {
601             textFlavorComparator = new TextFlavorComparator();
602         }
603
604         DataFlavor bestFlavor =
605             (DataFlavor )Collections.max(Arrays.asList(availableFlavors),
606                                         textFlavorComparator);
607
608         if (!bestFlavor.isFlavorTextType()) {
609             return null;
610         }
611         
612         return bestFlavor;
613     }
614
615     private static Comparator textFlavorComparator;
616
617     static class TextFlavorComparator
618         extends DataTransferer.DataFlavorComparator {
619
620         /**
621          * Compares two <code>DataFlavor</code> objects. Returns a negative
622      * integer, zero, or a positive integer as the first
623      * <code>DataFlavor</code> is worse than, equal to, or better than the
624      * second.
625          * <p>
626          * <code>DataFlavor</code>s are ordered according to the rules outlined
627      * for <code>selectBestTextFlavor</code>.
628      *
629          * @param obj1 the first <code>DataFlavor</code> to be compared
630          * @param obj2 the second <code>DataFlavor</code> to be compared
631          * @return a negative integer, zero, or a positive integer as the first
632          * argument is worse, equal to, or better than the second
633          * @throws ClassCastException if either of the arguments is not an
634          * instance of <code>DataFlavor</code>
635          * @throws NullPointerException if either of the arguments is
636          * <code>null</code>
637      *
638      * @see #selectBestTextFlavor
639          */
640         public int compare(Object obj1, Object obj2) {
641             DataFlavor flavor1 = (DataFlavor )obj1;
642             DataFlavor flavor2 = (DataFlavor )obj2;
643
644             if (flavor1.isFlavorTextType()) {
645                 if (flavor2.isFlavorTextType()) {
646                     return super.compare(obj1, obj2);
647                 } else {
648                     return 1;
649                 }
650             } else if (flavor2.isFlavorTextType()) {
651                 return -1;
652             } else {
653                 return 0;
654             }
655         }
656     }
657
658     /**
659      * Gets a Reader for a text flavor, decoded, if necessary, for the expected
660      * charset (encoding). The supported representation classes are
661      * <code>java.io.Reader</code>, <code>java.lang.String</code>,
662      * <code>java.nio.CharBuffer</code>, <code>[C</code>,
663      * <code>java.io.InputStream</code>, <code>java.nio.ByteBuffer</code>,
664      * and <code>[B</code>.
665      * <p>
666      * Because text flavors which do not support the charset parameter are
667      * encoded in a non-standard format, this method should not be called for
668      * such flavors. However, in order to maintain backward-compatibility,
669      * if this method is called for such a flavor, this method will treat the
670      * flavor as though it supports the charset parameter and attempt to
671      * decode it accordingly. See <code>selectBestTextFlavor</code> for a list
672      * of text flavors which do not support the charset parameter.
673      *
674      * @param transferable the <code>Transferable</code> whose data will be
675      * requested in this flavor
676      *
677      * @return a <code>Reader</code> to read the <code>Transferable</code>'s
678      * data
679      *
680      * @exception IllegalArgumentException if the representation class
681      * is not one of the seven listed above
682      * @exception IllegalArgumentException if the <code>Transferable</code>
683      * has <code>null</code> data
684      * @exception NullPointerException if the <code>Transferable</code> is
685      * <code>null</code>
686      * @exception UnsupportedEncodingException if this flavor's representation
687      * is <code>java.io.InputStream</code>,
688      * <code>java.nio.ByteBuffer</code>, or <code>[B</code> and
689      * this flavor's encoding is not supported by this
690      * implementation of the Java platform
691      * @exception UnsupportedFlavorException if the <code>Transferable</code>
692      * does not support this flavor
693      * @exception IOException if the data cannot be read because of an
694      * I/O error
695      * @see #selectBestTextFlavor
696      * @since 1.3
697      */
698     public Reader getReaderForText(Transferable transferable)
699     throws UnsupportedFlavorException , IOException
700     {
701     Object transferObject = transferable.getTransferData(this);
702     if (transferObject == null) {
703         throw new IllegalArgumentException
704         ("getTransferData() returned null");
705     }
706
707     if (transferObject instanceof Reader) {
708         return (Reader)transferObject;
709     } else if (transferObject instanceof String ) {
710         return new StringReader((String )transferObject);
711         } else if (transferObject instanceof CharBuffer) {
712             CharBuffer buffer = (CharBuffer)transferObject;
713             int size = buffer.remaining();
714             char[] chars = new char[size];
715             buffer.get(chars, 0, size);
716             return new CharArrayReader(chars);
717     } else if (transferObject instanceof char[]) {
718         return new CharArrayReader((char[])transferObject);
719     }
720
721     InputStream stream = null;
722
723     if (transferObject instanceof InputStream) {
724         stream = (InputStream)transferObject;
725         } else if (transferObject instanceof ByteBuffer) {
726             ByteBuffer buffer = (ByteBuffer)transferObject;
727             int size = buffer.remaining();
728             byte[] bytes = new byte[size];
729             buffer.get(bytes, 0, size);
730             stream = new ByteArrayInputStream(bytes);
731     } else if (transferObject instanceof byte[]) {
732         stream = new ByteArrayInputStream((byte[])transferObject);
733     }
734
735     if (stream == null) {
736             throw new IllegalArgumentException ("transfer data is not Reader, String, CharBuffer, char array, InputStream, ByteBuffer, or byte array");
737     }
738
739     String encoding = getParameter("charset");
740     return (encoding == null)
741         ? new InputStreamReader(stream)
742         : new InputStreamReader(stream, encoding);
743     }
744     
745     /**
746      * Returns the MIME type string for this <code>DataFlavor</code>.
747      * @return the MIME type string for this flavor
748      */
749     public String getMimeType() {
750         return (mimeType != null) ? mimeType.toString() : null;
751     }
752     
753     /**
754      * Returns the <code>Class</code> which objects supporting this
755      * <code>DataFlavor</code> will return when this <code>DataFlavor</code>
756      * is requested.
757      * @return the <code>Class</code> which objects supporting this
758      * <code>DataFlavor</code> will return when this <code>DataFlavor</code>
759      * is requested
760      */
761     public Class <?> getRepresentationClass() {
762         return representationClass;
763     }
764     
765     /**
766      * Returns the human presentable name for the data format that this
767      * <code>DataFlavor</code> represents. This name would be localized
768      * for different countries.
769      * @return the human presentable name for the data format that this
770      * <code>DataFlavor</code> represents
771      */
772     public String getHumanPresentableName() {
773         return humanPresentableName;
774     }
775     
776     /**
777      * Returns the primary MIME type for this <code>DataFlavor</code>.
778      * @return the primary MIME type of this <code>DataFlavor</code>
779      */
780     public String getPrimaryType() {
781         return (mimeType != null) ? mimeType.getPrimaryType() : null;
782     }
783     
784     /**
785      * Returns the sub MIME type of this <code>DataFlavor</code>.
786      * @return the Sub MIME type of this <code>DataFlavor</code>
787      */
788     public String getSubType() {
789         return (mimeType != null) ? mimeType.getSubType() : null;
790     }
791     
792     /**
793      * Returns the human presentable name for this <code>DataFlavor</code>
794      * if <code>paramName</code> equals "humanPresentableName". Otherwise
795      * returns the MIME type value associated with <code>paramName</code>.
796      *
797      * @param paramName the parameter name requested
798      * @return the value of the name parameter, or <code>null</code>
799      * if there is no associated value
800      */
801     public String getParameter(String paramName) {
802         if (paramName.equals("humanPresentableName")) {
803             return humanPresentableName;
804         } else {
805             return (mimeType != null)
806                 ? mimeType.getParameter(paramName) : null;
807         }
808     }
809     
810     /**
811      * Sets the human presentable name for the data format that this
812      * <code>DataFlavor</code> represents. This name would be localized
813      * for different countries.
814      * @param humanPresentableName the new human presentable name
815      */
816     public void setHumanPresentableName(String humanPresentableName) {
817         this.humanPresentableName = humanPresentableName;
818     }
819     
820     /**
821      * Tests an arbitrary <code>Object</code> to this <code>DataFlavor</code>
822      * for equality. Two <code>DataFlavor</code>s are considered equal if and
823      * only if their MIME primary type and subtype and representation class are
824      * equal. Additionally, if the primary type is "text", the subtype denotes
825      * a text flavor which supports the charset parameter, and the
826      * representation class is not <code>java.io.Reader</code>,
827      * <code>java.lang.String</code>, <code>java.nio.CharBuffer</code>, or
828      * <code>[C</code>, the <code>charset</code> parameter must also be equal.
829      * If a charset is not explicitly specified for one or both
830      * <code>DataFlavor</code>s, the platform default encoding is assumed. See
831      * <code>selectBestTextFlavor</code> for a list of text flavors which
832      * support the charset parameter.
833      *
834      * @param o the <code>Object</code> to compare with <code>this</code>
835      * @return <code>true</code> if <code>that</code> is equivalent to this
836      * <code>DataFlavor</code>; <code>false</code> otherwise
837      * @see #selectBestTextFlavor
838      */
839     public boolean equals(Object o) {
840         return ((o instanceof DataFlavor ) && equals((DataFlavor )o));
841     }
842
843     /**
844      * Tests a <code>DataFlavor</code> to this <code>DataFlavor</code> for
845      * equality. Two <code>DataFlavor</code>s are considered equal if and only
846      * if their MIME primary type and subtype and representation class are
847      * equal. Additionally, if the primary type is "text", the subtype denotes
848      * a text flavor which supports the charset parameter, and the
849      * representation class is not <code>java.io.Reader</code>,
850      * <code>java.lang.String</code>, <code>java.nio.CharBuffer</code>, or
851      * <code>[C</code>, the <code>charset</code> parameter must also be equal.
852      * If a charset is not explicitly specified for one or both
853      * <code>DataFlavor</code>s, the platform default encoding is assumed. See
854      * <code>selectBestTextFlavor</code> for a list of text flavors which
855      * support the charset parameter.
856      *
857      * @param that the <code>DataFlavor</code> to compare with
858      * <code>this</code>
859      * @return <code>true</code> if <code>that</code> is equivalent to this
860      * <code>DataFlavor</code>; <code>false</code> otherwise
861      * @see #selectBestTextFlavor
862      */
863     public boolean equals(DataFlavor that) {
864         if (that == null) {
865             return false;
866         }
867         if (this == that) {
868             return true;
869         }
870
871         if (representationClass == null) {
872             if (that.getRepresentationClass() != null) {
873                 return false;
874             }
875         } else {
876             if (!representationClass.equals(that.getRepresentationClass())) {
877                 return false;
878             }
879         }
880
881         if (mimeType == null) {
882             if (that.mimeType != null) {
883                 return false;
884             }
885         } else {
886             if (!mimeType.match(that.mimeType)) {
887                 return false;
888             }
889
890             if ("text".equals(getPrimaryType()) &&
891                 DataTransferer.doesSubtypeSupportCharset(this) &&
892         representationClass != null &&
893         !(isRepresentationClassReader() ||
894           String .class.equals(representationClass) ||
895                   isRepresentationClassCharBuffer() ||
896           DataTransferer.charArrayClass.equals(representationClass)))
897         {
898                 String thisCharset =
899             DataTransferer.canonicalName(getParameter("charset"));
900                 String thatCharset =
901             DataTransferer.canonicalName(that.getParameter("charset"));
902                 if (thisCharset == null) {
903                     if (thatCharset != null) {
904                         return false;
905                     }
906                 } else {
907                     if (!thisCharset.equals(thatCharset)) {
908                         return false;
909                     }
910                 }
911             }
912         }
913
914         return true;
915     }
916     
917     /**
918      * Compares only the <code>mimeType</code> against the passed in
919      * <code>String</code> and <code>representationClass</code> is
920      * not considered in the comparison.
921      * If <code>representationClass</code> needs to be compared, then
922      * <code>equals(new DataFlavor(s))</code> may be used.
923      *
924      * @deprecated As inconsistent with <code>hashCode()</code> contract,
925      * use <code>isMimeTypeEqual(String)</code> instead.
926      * @return true if the String (MimeType) is equal
927      */
928     @Deprecated
929     public boolean equals(String s) {
930         if (s == null || mimeType == null)
931             return false;
932         return isMimeTypeEqual(s);
933     }
934     
935     /**
936      * Returns hash code for this <code>DataFlavor</code>.
937      * For two equal <code>DataFlavor</code>s, hash codes are equal.
938      * For the <code>String</code>
939      * that matches <code>DataFlavor.equals(String)</code>, it is not
940      * guaranteed that <code>DataFlavor</code>'s hash code is equal
941      * to the hash code of the <code>String</code>.
942      *
943      * @return a hash code for this <code>DataFlavor</code>
944      */
945     public int hashCode() {
946         int total = 0;
947
948         if (representationClass != null) {
949             total += representationClass.hashCode();
950         }
951
952         if (mimeType != null) {
953             String primaryType = mimeType.getPrimaryType();
954             if (primaryType != null) {
955                 total += primaryType.hashCode();
956             }
957
958             // Do not add subType.hashCode() to the total. equals uses
959 // MimeType.match which reports a match if one or both of the
960 // subTypes is '*', regardless of the other subType.
961
962             if ("text".equals(primaryType) &&
963                 DataTransferer.doesSubtypeSupportCharset(this) &&
964                 representationClass != null &&
965                 !(isRepresentationClassReader() ||
966                   String .class.equals(representationClass) ||
967                   isRepresentationClassCharBuffer() ||
968                   DataTransferer.charArrayClass.equals
969                   (representationClass)))
970             {
971                 String charset =
972                     DataTransferer.canonicalName(getParameter("charset"));
973                 if (charset != null) {
974                     total += charset.hashCode();
975                 }
976             }
977         }
978
979         return total;
980     }
981
982     /**
983      * Tests a <code>DataFlavor</code> to this <code>DataFlavor</code> for
984      * equality. Two <code>DataFlavor</code>s are considered equal if and only
985      * if their MIME primary type and subtype and representation class are
986      * equal. Additionally, if the primary type is "text", the subtype denotes
987      * a text flavor which supports the charset parameter, and the
988      * representation class is not <code>java.io.Reader</code>,
989      * <code>java.lang.String</code>, <code>java.nio.CharBuffer</code>, or
990      * <code>[C</code>, the <code>charset</code> parameter must also be equal.
991      * If a charset is not explicitly specified for one or both
992      * <code>DataFlavor</code>s, the platform default encoding is assumed. See
993      * <code>selectBestTextFlavor</code> for a list of text flavors which
994      * support the charset parameter.
995      *
996      * @param that the <code>DataFlavor</code> to compare with
997      * <code>this</code>
998      * @return <code>true</code> if <code>that</code> is equivalent to this
999      * <code>DataFlavor</code>; <code>false</code> otherwise
1000     * @see #selectBestTextFlavor
1001     */
1002    public boolean match(DataFlavor that) {
1003    return equals(that);
1004    }
1005    
1006    /**
1007     * Returns whether the string representation of the MIME type passed in
1008     * is equivalent to the MIME type of this <code>DataFlavor</code>.
1009     * Parameters are not included in the comparison.
1010     *
1011     * @param mimeType the string representation of the MIME type
1012     * @return true if the string representation of the MIME type passed in is
1013     * equivalent to the MIME type of this <code>DataFlavor</code>;
1014     * false otherwise
1015     * @throws NullPointerException if mimeType is <code>null</code>
1016     */
1017    public boolean isMimeTypeEqual(String mimeType) {
1018    // JCK Test DataFlavor0117: if 'mimeType' is null, throw NPE
1019 if (mimeType == null) {
1020        throw new NullPointerException ("mimeType");
1021    }
1022        if (this.mimeType == null) {
1023            return false;
1024        }
1025        try {
1026            return this.mimeType.match(new MimeType (mimeType));
1027        } catch (MimeTypeParseException mtpe) {
1028            return false;
1029        }
1030    }
1031    
1032    /**
1033     * Compares the <code>mimeType</code> of two <code>DataFlavor</code>
1034     * objects. No parameters are considered.
1035     *
1036     * @param dataFlavor the <code>DataFlavor</code> to be compared
1037     * @return true if the <code>MimeType</code>s are equal,
1038     * otherwise false
1039     */
1040    
1041    public final boolean isMimeTypeEqual(DataFlavor dataFlavor) {
1042        return isMimeTypeEqual(dataFlavor.mimeType);
1043    }
1044    
1045    /**
1046     * Compares the <code>mimeType</code> of two <code>DataFlavor</code>
1047     * objects. No parameters are considered.
1048     *
1049     * @return true if the <code>MimeType</code>s are equal,
1050     * otherwise false
1051     */
1052    
1053    private boolean isMimeTypeEqual(MimeType mtype) {
1054        if (this.mimeType == null) {
1055            return (mtype == null);
1056        }
1057        return mimeType.match(mtype);
1058    }
1059
1060   /**
1061    * Does the <code>DataFlavor</code> represent a serialized object?
1062    */
1063
1064    public boolean isMimeTypeSerializedObject() {
1065        return isMimeTypeEqual(javaSerializedObjectMimeType);
1066    }
1067
1068    public final Class <?> getDefaultRepresentationClass() {
1069        return ioInputStreamClass;
1070    }
1071
1072    public final String getDefaultRepresentationClassAsString() {
1073        return getDefaultRepresentationClass().getName();
1074    }
1075
1076   /**
1077    * Does the <code>DataFlavor</code> represent a
1078    * <code>java.io.InputStream</code>?
1079    */
1080
1081    public boolean isRepresentationClassInputStream() {
1082        return ioInputStreamClass.isAssignableFrom(representationClass);
1083    }
1084
1085    /**
1086     * Returns whether the representation class for this
1087     * <code>DataFlavor</code> is <code>java.io.Reader</code> or a subclass
1088     * thereof.
1089     *
1090     * @since 1.4
1091     */
1092    public boolean isRepresentationClassReader() {
1093    return java.io.Reader .class.isAssignableFrom(representationClass);
1094    }
1095
1096    /**
1097     * Returns whether the representation class for this
1098     * <code>DataFlavor</code> is <code>java.nio.CharBuffer</code> or a
1099     * subclass thereof.
1100     *
1101     * @since 1.4
1102     */
1103    public boolean isRepresentationClassCharBuffer() {
1104        return java.nio.CharBuffer .class.isAssignableFrom(representationClass);
1105    }
1106
1107    /**
1108     * Returns whether the representation class for this
1109     * <code>DataFlavor</code> is <code>java.nio.ByteBuffer</code> or a
1110     * subclass thereof.
1111     *
1112     * @since 1.4
1113     */
1114    public boolean isRepresentationClassByteBuffer() {
1115        return java.nio.ByteBuffer .class.isAssignableFrom(representationClass);
1116    }
1117
1118   /**
1119    * Returns true if the representation class can be serialized.
1120    * @return true if the representation class can be serialized
1121    */
1122
1123    public boolean isRepresentationClassSerializable() {
1124        return java.io.Serializable .class.isAssignableFrom(representationClass);
1125    }
1126
1127   /**
1128    * Returns true if the representation class is <code>Remote</code>.
1129    * @return true if the representation class is <code>Remote</code>
1130    */
1131
1132    public boolean isRepresentationClassRemote() {
1133        return java.rmi.Remote .class.isAssignableFrom(representationClass);
1134    }
1135
1136   /**
1137    * Returns true if the <code>DataFlavor</code> specified represents
1138    * a serialized object.
1139    * @return true if the <code>DataFlavor</code> specified represents
1140    * a Serialized Object
1141    */
1142
1143    public boolean isFlavorSerializedObjectType() {
1144        return isRepresentationClassSerializable() && isMimeTypeEqual(javaSerializedObjectMimeType);
1145    }
1146
1147    /**
1148     * Returns true if the <code>DataFlavor</code> specified represents
1149     * a remote object.
1150     * @return true if the <code>DataFlavor</code> specified represents
1151     * a Remote Object
1152     */
1153  
1154    public boolean isFlavorRemoteObjectType() {
1155        return isRepresentationClassRemote()
1156            && isRepresentationClassSerializable()
1157            && isMimeTypeEqual(javaRemoteObjectMimeType);
1158    }
1159
1160  
1161   /**
1162    * Returns true if the <code>DataFlavor</code> specified represents
1163    * a list of file objects.
1164    * @return true if the <code>DataFlavor</code> specified represents
1165    * a List of File objects
1166    */
1167
1168   public boolean isFlavorJavaFileListType() {
1169        if (mimeType == null || representationClass == null)
1170            return false;
1171        return java.util.List .class.isAssignableFrom(representationClass) &&
1172               mimeType.match(javaFileListFlavor.mimeType);
1173
1174   }
1175
1176    /**
1177     * Returns whether this <code>DataFlavor</code> is a valid text flavor for
1178     * this implementation of the Java platform. Only flavors equivalent to
1179     * <code>DataFlavor.stringFlavor</code> and <code>DataFlavor</code>s with
1180     * a primary MIME type of "text" can be valid text flavors.
1181     * <p>
1182     * If this flavor supports the charset parameter, it must be equivalent to
1183     * <code>DataFlavor.stringFlavor</code>, or its representation must be
1184     * <code>java.io.Reader</code>, <code>java.lang.String</code>,
1185     * <code>java.nio.CharBuffer</code>, <code>[C</code>,
1186     * <code>java.io.InputStream</code>, <code>java.nio.ByteBuffer</code>, or
1187     * <code>[B</code>. If the representation is
1188     * <code>java.io.InputStream</code>, <code>java.nio.ByteBuffer</code>, or
1189     * <code>[B</code>, then this flavor's <code>charset</code> parameter must
1190     * be supported by this implementation of the Java platform. If a charset
1191     * is not specified, then the platform default charset, which is always
1192     * supported, is assumed.
1193     * <p>
1194     * If this flavor does not support the charset parameter, its
1195     * representation must be <code>java.io.InputStream</code>,
1196     * <code>java.nio.ByteBuffer</code>, or <code>[B</code>.
1197     * <p>
1198     * See <code>selectBestTextFlavor</code> for a list of text flavors which
1199     * support the charset parameter.
1200     *
1201     * @return <code>true</code> if this <code>DataFlavor</code> is a valid
1202     * text flavor as described above; <code>false</code> otherwise
1203     * @see #selectBestTextFlavor
1204     * @since 1.4
1205     */
1206    public boolean isFlavorTextType() {
1207        return (DataTransferer.isFlavorCharsetTextType(this) ||
1208                DataTransferer.isFlavorNoncharsetTextType(this));
1209    }
1210
1211   /**
1212    * Serializes this <code>DataFlavor</code>.
1213    */
1214
1215   public synchronized void writeExternal(ObjectOutput os) throws IOException {
1216       if (mimeType != null) {
1217           mimeType.setParameter("humanPresentableName", humanPresentableName);
1218           os.writeObject(mimeType);
1219           mimeType.removeParameter("humanPresentableName");
1220       } else {
1221           os.writeObject(null);
1222       }
1223       
1224       os.writeObject(representationClass);
1225   }
1226
1227   /**
1228    * Restores this <code>DataFlavor</code> from a Serialized state.
1229    */
1230
1231   public synchronized void readExternal(ObjectInput is) throws IOException , ClassNotFoundException {
1232       String rcn = null;
1233        mimeType = (MimeType )is.readObject();
1234
1235        if (mimeType != null) {
1236            humanPresentableName =
1237                mimeType.getParameter("humanPresentableName");
1238            mimeType.removeParameter("humanPresentableName");
1239            rcn = mimeType.getParameter("class");
1240            if (rcn == null) {
1241                throw new IOException("no class parameter specified in: " +
1242                                      mimeType);
1243            }
1244        }
1245
1246        try {
1247            representationClass = (Class )is.readObject();
1248        } catch (OptionalDataException ode) {
1249            if (!ode.eof || ode.length != 0) {
1250                throw ode;
1251            }
1252            // Ensure backward compatibility.
1253 // Old versions didn't write the representation class to the stream.
1254 if (rcn != null) {
1255                representationClass =
1256                    DataFlavor.tryToLoadClass(rcn, getClass().getClassLoader());
1257            }
1258        }
1259   }
1260
1261   /**
1262    * Returns a clone of this <code>DataFlavor</code>.
1263    * @return a clone of this <code>DataFlavor</code>
1264    */
1265
1266    public Object clone() throws CloneNotSupportedException {
1267    Object newObj = super.clone();
1268    if (mimeType != null) {
1269        ((DataFlavor )newObj).mimeType = (MimeType )mimeType.clone();
1270    }
1271    return newObj;
1272    } // clone()
1273
1274   /**
1275    * Called on <code>DataFlavor</code> for every MIME Type parameter
1276    * to allow <code>DataFlavor</code> subclasses to handle special
1277    * parameters like the text/plain <code>charset</code>
1278    * parameters, whose values are case insensitive. (MIME type parameter
1279    * values are supposed to be case sensitive.
1280    * <p>
1281    * This method is called for each parameter name/value pair and should
1282    * return the normalized representation of the <code>parameterValue</code>.
1283    *
1284    * This method is never invoked by this implementation from 1.1 onwards.
1285    *
1286    * @deprecated
1287    */
1288    @Deprecated
1289    protected String normalizeMimeTypeParameter(String parameterName, String parameterValue) {
1290        return parameterValue;
1291    }
1292  
1293   /**
1294    * Called for each MIME type string to give <code>DataFlavor</code> subtypes
1295    * the opportunity to change how the normalization of MIME types is
1296    * accomplished. One possible use would be to add default
1297    * parameter/value pairs in cases where none are present in the MIME
1298    * type string passed in.
1299    *
1300    * This method is never invoked by this implementation from 1.1 onwards.
1301    *
1302    * @deprecated
1303    */
1304    @Deprecated
1305    protected String normalizeMimeType(String mimeType) {
1306        return mimeType;
1307    }
1308
1309    /*
1310     * fields
1311     */
1312
1313    /* placeholder for caching any platform-specific data for flavor */
1314
1315    transient int atom;
1316  
1317    /* Mime Type of DataFlavor */
1318
1319    MimeType mimeType;
1320
1321    private String humanPresentableName;
1322  
1323    /** Java class of objects this DataFlavor represents **/
1324
1325    private Class representationClass;
1326
1327} // class DataFlavor
1328

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags