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