java.awt.datatransfer
Class SystemFlavorMap

java.lang.Object
  extended byjava.awt.datatransfer.SystemFlavorMap
All Implemented Interfaces:
FlavorMap, FlavorTable

public final class SystemFlavorMap
extends Object
implements FlavorMap, FlavorTable

The SystemFlavorMap is a configurable map between "natives" (Strings), which correspond to platform-specific data formats, and "flavors" (DataFlavors), which correspond to platform-independent MIME types. This mapping is used by the data transfer subsystem to transfer data between Java and native applications, and between Java applications in separate VMs.

In the Sun reference implementation, the default SystemFlavorMap is initialized by the file jre/lib/flavormap.properties and the contents of the URL referenced by the AWT property AWT.DnD.flavorMapFileURL. See flavormap.properties for details.

Since:
1.2

Field Summary
private  Set disabledMappingGenerationKeys
          Dynamic mapping generation used for text mappings should not be applied to the DataFlavors and String natives for which the mappings have been explicitly specified with setFlavorsForNative() or setNativesForFlavor().
private static String[] ENCODED_TEXT_CLASSES
          The list of valid, encoded text flavor representation classes, in order from best to worst.
private static WeakHashMap flavorMaps
          System singleton which maps a thread's ClassLoader to a SystemFlavorMap.
private  Map flavorToNative
          Maps DataFlavors (or base type Strings for text DataFlavors) to Lists of native Strings.
private  Map getFlavorsForNativeCache
          Caches the result getFlavorsForNative().
private  Map getNativesForFlavorCache
          Caches the result of getNativesForFlavor().
private static String JavaMIME
          Constant prefix used to tag Java types converted to native platform type.
private static String keyValueSeparators
          Copied from java.util.Properties.
private  Map nativeToFlavor
          Maps native Strings to Lists of DataFlavors (or base type Strings for text DataFlavors).
private static String strictKeyValueSeparators
           
private static boolean SYNTHESIZE_IF_NOT_FOUND
          This constant is passed to flavorToNativeLookup() to indicate that a a native should be synthesized, stored, and returned by encoding the DataFlavor's MIME type in case if the DataFlavor is not found in 'flavorToNative' map.
private static String TEXT_PLAIN_BASE_TYPE
          A String representing text/plain MIME type.
private static String[] UNICODE_TEXT_CLASSES
          The list of valid, decoded text flavor representation classes, in order from best to worst.
private static String whiteSpaceChars
           
 
Constructor Summary
private SystemFlavorMap()
          Constructs a SystemFlavorMap by reading flavormap.properties and AWT.DnD.flavorMapFileURL.
 
Method Summary
 void addFlavorForUnencodedNative(String nat, DataFlavor flav)
          Adds a mapping from a single String native to a single DataFlavor.
 void addUnencodedNativeForFlavor(DataFlavor flav, String nat)
          Adds a mapping from the specified DataFlavor (and all DataFlavors equal to the specified DataFlavor) to the specified String native.
private  boolean continueLine(String line)
          Copied from java.util.Properties.
static DataFlavor decodeDataFlavor(String nat)
          Decodes a String native for use as a DataFlavor.
static String decodeJavaMIMEType(String nat)
          Decodes a String native for use as a Java MIME type.
static String encodeDataFlavor(DataFlavor flav)
          Encodes a DataFlavor for use as a String native.
static String encodeJavaMIMEType(String mimeType)
          Encodes a MIME type for use as a String native.
private  List flavorToNativeLookup(DataFlavor flav, boolean synthesize)
          Semantically equivalent to 'flavorToNative.get(flav)'.
static FlavorMap getDefaultFlavorMap()
          Returns the default FlavorMap for this thread's ClassLoader.
 List getFlavorsForNative(String nat)
          Returns a List of DataFlavors to which the specified String native can be translated by the data transfer subsystem.
 Map getFlavorsForNatives(String[] natives)
          Returns a Map of the specified String natives to their most preferred DataFlavor.
 List getNativesForFlavor(DataFlavor flav)
          Returns a List of String natives to which the specified DataFlavor can be translated by the data transfer subsystem.
 Map getNativesForFlavors(DataFlavor[] flavors)
          Returns a Map of the specified DataFlavors to their most preferred String native.
static boolean isJavaMIMEType(String str)
          Returns whether the specified String is an encoded Java MIME type.
private  String loadConvert(String theString)
          Copied from java.util.Properties.
private  List nativeToFlavorLookup(String nat)
          Semantically equivalent to 'nativeToFlavor.get(nat)'.
private  void parseAndStoreReader(BufferedReader in)
          Copied code from java.util.Properties.
 void setFlavorsForNative(String nat, DataFlavor[] flavors)
          Discards the current mappings for the specified String native, and creates new mappings to the specified DataFlavors.
 void setNativesForFlavor(DataFlavor flav, String[] natives)
          Discards the current mappings for the specified DataFlavor and all DataFlavors equal to the specified DataFlavor, and creates new mappings to the specified String natives.
private  void store(Object hashed, Object listed, Map map)
          Stores the listed object under the specified hash key in map.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

JavaMIME

private static String JavaMIME
Constant prefix used to tag Java types converted to native platform type.


flavorMaps

private static final WeakHashMap flavorMaps
System singleton which maps a thread's ClassLoader to a SystemFlavorMap.


keyValueSeparators

private static final String keyValueSeparators
Copied from java.util.Properties.

See Also:
Constant Field Values

strictKeyValueSeparators

private static final String strictKeyValueSeparators
See Also:
Constant Field Values

whiteSpaceChars

private static final String whiteSpaceChars
See Also:
Constant Field Values

UNICODE_TEXT_CLASSES

private static final String[] UNICODE_TEXT_CLASSES
The list of valid, decoded text flavor representation classes, in order from best to worst.


ENCODED_TEXT_CLASSES

private static final String[] ENCODED_TEXT_CLASSES
The list of valid, encoded text flavor representation classes, in order from best to worst.


TEXT_PLAIN_BASE_TYPE

private static final String TEXT_PLAIN_BASE_TYPE
A String representing text/plain MIME type.

See Also:
Constant Field Values

SYNTHESIZE_IF_NOT_FOUND

private static final boolean SYNTHESIZE_IF_NOT_FOUND
This constant is passed to flavorToNativeLookup() to indicate that a a native should be synthesized, stored, and returned by encoding the DataFlavor's MIME type in case if the DataFlavor is not found in 'flavorToNative' map.

See Also:
Constant Field Values

nativeToFlavor

private Map nativeToFlavor
Maps native Strings to Lists of DataFlavors (or base type Strings for text DataFlavors).


flavorToNative

private Map flavorToNative
Maps DataFlavors (or base type Strings for text DataFlavors) to Lists of native Strings.


getNativesForFlavorCache

private Map getNativesForFlavorCache
Caches the result of getNativesForFlavor(). Maps DataFlavors to SoftReferences which reference Lists of String natives.


getFlavorsForNativeCache

private Map getFlavorsForNativeCache
Caches the result getFlavorsForNative(). Maps String natives to SoftReferences which reference Lists of DataFlavors.


disabledMappingGenerationKeys

private Set disabledMappingGenerationKeys
Dynamic mapping generation used for text mappings should not be applied to the DataFlavors and String natives for which the mappings have been explicitly specified with setFlavorsForNative() or setNativesForFlavor(). This keeps all such keys.

Constructor Detail

SystemFlavorMap

private SystemFlavorMap()
Constructs a SystemFlavorMap by reading flavormap.properties and AWT.DnD.flavorMapFileURL.

Method Detail

getDefaultFlavorMap

public static FlavorMap getDefaultFlavorMap()
Returns the default FlavorMap for this thread's ClassLoader.


parseAndStoreReader

private void parseAndStoreReader(BufferedReader in)
                          throws IOException
Copied code from java.util.Properties. Parsing the data ourselves is the only way to handle duplicate keys and values.

Throws:
IOException

continueLine

private boolean continueLine(String line)
Copied from java.util.Properties.


loadConvert

private String loadConvert(String theString)
Copied from java.util.Properties.


store

private void store(Object hashed,
                   Object listed,
                   Map map)
Stores the listed object under the specified hash key in map. Unlike a standard map, the listed object will not replace any object already at the appropriate Map location, but rather will be appended to a List stored in that location.


nativeToFlavorLookup

private List nativeToFlavorLookup(String nat)
Semantically equivalent to 'nativeToFlavor.get(nat)'. This method handles the case where 'nat' is not found in 'nativeToFlavor'. In that case, a new DataFlavor is synthesized, stored, and returned, if and only if the specified native is encoded as a Java MIME type.


flavorToNativeLookup

private List flavorToNativeLookup(DataFlavor flav,
                                  boolean synthesize)
Semantically equivalent to 'flavorToNative.get(flav)'. This method handles the case where 'flav' is not found in 'flavorToNative' depending on the value of passes 'synthesize' parameter. If 'synthesize' is SYNTHESIZE_IF_NOT_FOUND a native is synthesized, stored, and returned by encoding the DataFlavor's MIME type. Otherwise an empty List is returned and 'flavorToNative' remains unaffected.


getNativesForFlavor

public List getNativesForFlavor(DataFlavor flav)
Returns a List of String natives to which the specified DataFlavor can be translated by the data transfer subsystem. The List will be sorted from best native to worst. That is, the first native will best reflect data in the specified flavor to the underlying native platform.

If the specified DataFlavor is previously unknown to the data transfer subsystem, then invoking this method will establish a mapping in both directions between the specified DataFlavor and an encoded version of its MIME type as its native.

Specified by:
getNativesForFlavor in interface FlavorTable
Parameters:
flav - the DataFlavor whose corresponding natives should be returned. If null is specified, all natives currently known to the data transfer subsystem are returned in a non-deterministic order.
Returns:
a java.util.List of java.lang.String objects which are platform-specific representations of platform- specific data formats
Since:
1.4
See Also:
encodeDataFlavor(java.awt.datatransfer.DataFlavor)

getFlavorsForNative

public List getFlavorsForNative(String nat)
Returns a List of DataFlavors to which the specified String native can be translated by the data transfer subsystem. The List will be sorted from best DataFlavor to worst. That is, the first DataFlavor will best reflect data in the specified native to a Java application.

If the specified native is previously unknown to the data transfer subsystem, and that native has been properly encoded, then invoking this method will establish a mapping in both directions between the specified native and a DataFlavor whose MIME type is a decoded version of the native.

Specified by:
getFlavorsForNative in interface FlavorTable
Parameters:
nat - the native whose corresponding DataFlavors should be returned. If null is specified, all DataFlavors currently known to the data transfer subsystem are returned in a non-deterministic order.
Returns:
a java.util.List of DataFlavor objects into which platform-specific data in the specified, platform-specific native can be translated
Since:
1.4
See Also:
encodeJavaMIMEType(java.lang.String)

getNativesForFlavors

public Map getNativesForFlavors(DataFlavor[] flavors)
Returns a Map of the specified DataFlavors to their most preferred String native. Each native value will be the same as the first native in the List returned by getNativesForFlavor for the specified flavor.

If a specified DataFlavor is previously unknown to the data transfer subsystem, then invoking this method will establish a mapping in both directions between the specified DataFlavor and an encoded version of its MIME type as its native.

Specified by:
getNativesForFlavors in interface FlavorMap
Parameters:
flavors - an array of DataFlavors which will be the key set of the returned Map. If null is specified, a mapping of all DataFlavors known to the data transfer subsystem to their most preferred String natives will be returned.
Returns:
a java.util.Map of DataFlavors to String natives
See Also:
getNativesForFlavor(java.awt.datatransfer.DataFlavor), encodeDataFlavor(java.awt.datatransfer.DataFlavor)

getFlavorsForNatives

public Map getFlavorsForNatives(String[] natives)
Returns a Map of the specified String natives to their most preferred DataFlavor. Each DataFlavor value will be the same as the first DataFlavor in the List returned by getFlavorsForNative for the specified native.

If a specified native is previously unknown to the data transfer subsystem, and that native has been properly encoded, then invoking this method will establish a mapping in both directions between the specified native and a DataFlavor whose MIME type is a decoded version of the native.

Specified by:
getFlavorsForNatives in interface FlavorMap
Parameters:
natives - an array of Strings which will be the key set of the returned Map. If null is specified, a mapping of all supported String natives to their most preferred DataFlavors will be returned.
Returns:
a java.util.Map of String natives to DataFlavors
See Also:
getFlavorsForNative(java.lang.String), encodeJavaMIMEType(java.lang.String)

addUnencodedNativeForFlavor

public void addUnencodedNativeForFlavor(DataFlavor flav,
                                        String nat)
Adds a mapping from the specified DataFlavor (and all DataFlavors equal to the specified DataFlavor) to the specified String native. Unlike getNativesForFlavor, the mapping will only be established in one direction, and the native will not be encoded. To establish a two-way mapping, call addFlavorForUnencodedNative as well. The new mapping will be of lower priority than any existing mapping. This method has no effect if a mapping from the specified or equal DataFlavor to the specified String native already exists.

Parameters:
flav - the DataFlavor key for the mapping
nat - the String native value for the mapping
Throws:
NullPointerException - if flav or nat is null
Since:
1.4
See Also:
addFlavorForUnencodedNative(java.lang.String, java.awt.datatransfer.DataFlavor)

setNativesForFlavor

public void setNativesForFlavor(DataFlavor flav,
                                String[] natives)
Discards the current mappings for the specified DataFlavor and all DataFlavors equal to the specified DataFlavor, and creates new mappings to the specified String natives. Unlike getNativesForFlavor, the mappings will only be established in one direction, and the natives will not be encoded. To establish two-way mappings, call setFlavorsForNative as well. The first native in the array will represent the highest priority mapping. Subsequent natives will represent mappings of decreasing priority.

If the array contains several elements that reference equal String natives, this method will establish new mappings for the first of those elements and ignore the rest of them.

It is recommended that client code not reset mappings established by the data transfer subsystem. This method should only be used for application-level mappings.

Parameters:
flav - the DataFlavor key for the mappings
natives - the String native values for the mappings
Throws:
NullPointerException - if flav or natives is null or if natives contains null elements
Since:
1.4
See Also:
setFlavorsForNative(java.lang.String, java.awt.datatransfer.DataFlavor[])

addFlavorForUnencodedNative

public void addFlavorForUnencodedNative(String nat,
                                        DataFlavor flav)
Adds a mapping from a single String native to a single DataFlavor. Unlike getFlavorsForNative, the mapping will only be established in one direction, and the native will not be encoded. To establish a two-way mapping, call addUnencodedNativeForFlavor as well. The new mapping will be of lower priority than any existing mapping. This method has no effect if a mapping from the specified String native to the specified or equal DataFlavor already exists.

Parameters:
nat - the String native key for the mapping
flav - the DataFlavor value for the mapping
Throws:
NullPointerException - if nat or flav is null
Since:
1.4
See Also:
addUnencodedNativeForFlavor(java.awt.datatransfer.DataFlavor, java.lang.String)

setFlavorsForNative

public void setFlavorsForNative(String nat,
                                DataFlavor[] flavors)
Discards the current mappings for the specified String native, and creates new mappings to the specified DataFlavors. Unlike getFlavorsForNative, the mappings will only be established in one direction, and the natives need not be encoded. To establish two-way mappings, call setNativesForFlavor as well. The first DataFlavor in the array will represent the highest priority mapping. Subsequent DataFlavors will represent mappings of decreasing priority.

If the array contains several elements that reference equal DataFlavors, this method will establish new mappings for the first of those elements and ignore the rest of them.

It is recommended that client code not reset mappings established by the data transfer subsystem. This method should only be used for application-level mappings.

Parameters:
nat - the String native key for the mappings
flavors - the DataFlavor values for the mappings
Throws:
NullPointerException - if nat or flavors is null or if flavors contains null elements
Since:
1.4
See Also:
setNativesForFlavor(java.awt.datatransfer.DataFlavor, java.lang.String[])

encodeJavaMIMEType

public static String encodeJavaMIMEType(String mimeType)
Encodes a MIME type for use as a String native. The format of an encoded representation of a MIME type is implementation-dependent. The only restrictions are:

Sun's reference implementation of this method returns the specified MIME type String prefixed with JAVA_DATAFLAVOR:.

Parameters:
mimeType - the MIME type to encode
Returns:
the encoded String, or null if mimeType is null

encodeDataFlavor

public static String encodeDataFlavor(DataFlavor flav)
Encodes a DataFlavor for use as a String native. The format of an encoded DataFlavor is implementation-dependent. The only restrictions are:

Sun's reference implementation of this method returns the MIME type String of the specified DataFlavor prefixed with JAVA_DATAFLAVOR:.

Parameters:
flav - the DataFlavor to encode
Returns:
the encoded String, or null if flav is null or has a null MIME type

isJavaMIMEType

public static boolean isJavaMIMEType(String str)
Returns whether the specified String is an encoded Java MIME type.

Parameters:
str - the String to test
Returns:
true if the String is encoded; false otherwise

decodeJavaMIMEType

public static String decodeJavaMIMEType(String nat)
Decodes a String native for use as a Java MIME type.

Parameters:
nat - the String to decode
Returns:
the decoded Java MIME type, or null if nat is not an encoded String native

decodeDataFlavor

public static DataFlavor decodeDataFlavor(String nat)
                                   throws ClassNotFoundException
Decodes a String native for use as a DataFlavor.

Parameters:
nat - the String to decode
Returns:
the decoded DataFlavor, or null if nat is not an encoded String native
Throws:
ClassNotFoundException