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