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