com.mapinfo.midev.metadata

## Class Metadata

- java.lang.Object
- - com.mapinfo.midev.metadata.Metadata

All Implemented Interfaces:
  Serializable, Iterable

    public class Metadata
    extends Object
    implements Serializable, Iterable

Manages a tree-structured collection of key-value metadata strings.

See Also:
  Serialized Form

### Field Summary

Fields
`static String` `DELIMITER` Denotes the character used to delimit the components of a metadata key.

### Constructor Summary

Constructors
Constructor and Description
`Metadata()` Constructs a new Metadata node with an empty string for a key and an empty string for a value.
`Metadata(String key)` Constructs a new Metadata node with the specified key.
`Metadata(String key, String value)` Constructs a new Metadata node with the specified key and value.

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`void` `clear()` Removes all child metadata nodes from this metadata node.
`boolean` `contains(String key)` Determines if this metadata contains a child with the specified key.
`static boolean` `containsDelimiter(String key)` Tests a key to see if it contains a `DELIMITER`.
`void` `delete(Metadata child)` Removes the specified child node from this metadata node.
`void` `delete(String key)` Removes a child node from this metadata node.
`boolean` `equals(Object o)` Indicates whether some other object is "equal to" this one.
`Metadata` `get(String key)` Retrieves a child node specified by a key.
`Metadata` `getCopy()` Creates a deep copy of this metadata node.
`Iterator` `getDictionaryIterator()` Returns an iterator over the entire set of metadata mappings between keys and values represented by this metadata node.
`Iterator` `getDictionaryIterator(boolean bAllMappings)` Returns an iterator over the entire set of metadata mappings between keys and values represented by this metadata node.
`String` `getKey()` Returns the key for this metadata node.
`Iterator` `getMetadataIterator()` Returns an iterator over the child metadata nodes in this metadata node.
`int` `getNumberChildren()` Indicates the number of child nodes this metadata node has.
`Metadata` `getUnmodifiableMetadata()` Returns a read-only Metadata instance for this object.
`String` `getValue()` Returns the value for this metadata node.
`int` `hashCode()` Returns a hash code value for the object.
`Iterator` `iterator()` Returns an iterator over the child metadata nodes in this metadata node.
`void` `put(Metadata value)` Adds the specified metadata to the current node's list of child nodes.
`void` `put(String key, Metadata value)` Associates the specified metadata node with the specified key in this metadata.
`String` `put(String key, String value)` Associates the specified value with the specified key in this metadata.
`void` `putAll(Metadata metadata)` Adds copies of all of the child metadata nodes of the supplied metadata as children of this metadata node.
`void` `setKey(String key)` Sets the key for this metadata node.
`void` `setValue(String value)` Sets the value for this metadata node.
`static String[]` `tokenizeKey(String key)` Parses a key into a collection of component keys using `DELIMITER` as the delimiter character.
`String` `toString()`

### Methods inherited from class java.lang.Object

`getClass, notify, notifyAll, wait, wait, wait`

### Methods inherited from interface java.lang.Iterable

`forEach, spliterator`

### Field Detail

#### DELIMITER

    public static final String DELIMITER

Denotes the character used to delimit the components of a metadata key.

See Also:
  Constant Field Values

### Constructor Detail

#### Metadata

    public Metadata()

Constructs a new Metadata node with an empty string for a key and an empty string for a value.

#### Metadata

    public Metadata(String key)

Constructs a new Metadata node with the specified key. The node has an empty string for a value.

Parameters:
  `key` - is the key to associate with this new metadata node.
Throws:
  `IllegalArgumentException` - if the key is null.

#### Metadata

    public Metadata(String key,
                    String value)

Constructs a new Metadata node with the specified key and value.

Parameters:
  `key` - is the key to associate with this new metadata node.
  `value` - is the value to associate with this new metadata node.
Throws:
  `IllegalArgumentException` - if the key is null.

### Method Detail

#### equals

    public boolean equals(Object o)

Indicates whether some other object is "equal to" this one.

Overrides:
  `equals` in class `Object`
Parameters:
  `o` - the reference object with which to compare.
Returns:
  `true` if this object equals the parameter object; `false` otherwise;

#### hashCode

    public int hashCode()

Returns a hash code value for the object.

Overrides:
  `hashCode` in class `Object`
Returns:
  a hash code value for this object.

#### toString

    public String toString()

Overrides:
  `toString` in class `Object`

#### tokenizeKey

    public static String[] tokenizeKey(String key)

Parses a key into a collection of component keys using `DELIMITER` as the delimiter character. The component keys will be returned as an array of strings. Leading and trailing delimiters will be stripped off and ignored. Multiple, consecutive occurrences of the delimiter within the key will be treated as a single delimiter. A key specified as `null` or the empty string ("") will return an array of length zero. See `Package Summary` for more details.

Parameters:
  `key` - is the string to be parsed.
Returns:
  a string array containing the key parsed into component keys.

#### containsDelimiter

    public static boolean containsDelimiter(String key)

Tests a key to see if it contains a `DELIMITER`. If the key is null or the empty string, then `false` is returned.

Parameters:
  `key` - is the string to test.
Returns:
  `true` if the key contains a delimiter, `false` if not.

#### getUnmodifiableMetadata

    public Metadata getUnmodifiableMetadata()

Returns a read-only Metadata instance for this object.

Returns:
  a read-only Metadata instance for this object.

#### getKey

    public String getKey()

Returns the key for this metadata node. The key cannot be null but may be empty.

Returns:
  the key for this node.

#### getValue

    public String getValue()

Returns the value for this metadata node. The value cannot be null but may be empty.

Returns:
  the value for this node.

#### setKey

    public void setKey(String key)

Sets the key for this metadata node. The key must be assignable as a key for a single metadata node; the key must not contain a `DELIMITER`. The key cannot be null but may be empty.

Parameters:
  `key` - is the new key to associate with this metadata.
Throws:
  `IllegalArgumentException` - if the key is `null` or contains a delimiter.

#### setValue

    public void setValue(String value)

Sets the value for this metadata node. The value cannot be null but may be empty. If the value is specified as `null`, the metadata value will be set to an empty string ("").

Parameters:
  `value` - is the new value to associate with this metadata.

#### contains

    public boolean contains(String key)

Determines if this metadata contains a child with the specified key. The key may be a composite key in which case a suitable child metadata node will be located. If the key does not start with a `DELIMITER`, then the test does not consider `this` node's key. If the key parameter does start with a delimiter, then the first component key in the parameter must match the key for `this` metadata node.

Consider a Metadata hierarchy shown in the `Package Description`.

>      // The following calls all return true.
>      metadata.contains("Use Constraints");
>      metadata.contains("\\Identification\\Use Constraints");
>      metadata.contains("Keywords\\Theme\\Geography");

>      // The following calls return false.
>      metadata.contains("\\Use Constraints");
>      metadata.contains("Theme\\Geography");

Parameters:
  `key` - is the key to test.
Returns:
  `true` if the key is found; `false` otherwise.

#### getNumberChildren

    public int getNumberChildren()

Indicates the number of child nodes this metadata node has.

Returns:
  the number of child nodes this metadata node has.

#### get

    public Metadata get(String key)

Retrieves a child node specified by a key. The key may be a composite key, in which case the key will be parsed into component keys and the specified ancestor node will be returned (if found).

Parameters:
  `key` - the key that indicates the node to return.
Returns:
  the Metadata node specified by the key. If the key is not found, no exception is thrown and `null` is returned.

#### put

    public String put(String key,
                      String value)

Associates the specified value with the specified key in this metadata. If the metadata previously contained a mapping for this key, the old value is replaced by the specified value and the old value is returned.

If the key is a composite key (such as "Theme\\Geography\\Region") and a metadata node does not exist for the key, nodes will be added to represent the key and the associated value.

Parameters:
  `key` - key with which the specified value is to be associated.
  `value` - value to be associated with the specified key.
Returns:
  previous value associated with specified key, or `null` if there was no mapping for key.
Throws:
  `IllegalArgumentException` - if the key is null or empty.

#### put

    public void put(String key,
                    Metadata value)

Associates the specified metadata node with the specified key in this metadata. If the key is a composite key (such as "Theme\\Geography\\Region") and a metadata node does not exist for the key, nodes will be added to represent the key and the associated metadata value.

Parameters:
  `key` - key with which the specified value is to be associated.
  `value` - metadata to be associated with the specified key.
Throws:
  `IllegalArgumentException` - if the key is null or empty or if value is null.

#### put

    public void put(Metadata value)

Adds the specified metadata to the current node's list of child nodes.

Parameters:
  `value` - the metadata to add.
Throws:
  `IllegalArgumentException` - if value is null.

#### putAll

    public void putAll(Metadata metadata)

Adds copies of all of the child metadata nodes of the supplied metadata as children of this metadata node.

Parameters:
  `metadata` - Parent of the metadata nodes to be copied and stored as child nodes of this node.

#### delete

    public void delete(Metadata child)

Removes the specified child node from this metadata node.

Parameters:
  `child` - the Metadata child to remove from this node's list of child nodes.

#### delete

    public void delete(String key)

Removes a child node from this metadata node. The key argument may be a composite key (for example, "Theme\\Geography").

Parameters:
  `key` - specifies the child metadata node to remove.
Throws:
  `IllegalArgumentException` - if the key is null or othewrwise malformed.

#### clear

    public void clear()

Removes all child metadata nodes from this metadata node.

#### getCopy

    public Metadata getCopy()

Creates a deep copy of this metadata node.

Returns:
  a new metadata node that is a duplicate of this node.

#### iterator

    public Iterator iterator()

Returns an iterator over the child metadata nodes in this metadata node. This method is equivalent to `getMetadataIterator()`.

Specified by:
  `iterator` in interface `Iterable`
Returns:
  an iterator over this metadata's child nodes.

#### getMetadataIterator

    public Iterator getMetadataIterator()

Returns an iterator over the child metadata nodes in this metadata node.

Returns:
  an iterator over this metadata's child nodes.

#### getDictionaryIterator

    public Iterator getDictionaryIterator()

Returns an iterator over the entire set of metadata mappings between keys and values represented by this metadata node. Only mappings with non-empty values will be returned by this iterator. This method is equivalent to `getDictionaryIterator(false)`.

Returns:
  an iterator over this metadata's key-value mappings.

#### getDictionaryIterator

    public Iterator getDictionaryIterator(boolean bAllMappings)

Returns an iterator over the entire set of metadata mappings between keys and values represented by this metadata node.

Consider a Metadata hierarchy shown in the `Package Description`. The following block of code:

     iterator = metadata.getDictionaryIterator(true);
     while (iterator.hasNext()){
        Map.Entry<String,String> entry = iterator.next();
        System.out.println("\""+entry.getKey()+"\" = \""+entry.getValue()+"\"");
     }

produces the following output:

     "\Identification" = ""
     "\Identification\Use Constraints" = "For use with MapXtreme"
     "\Identification\Description" = ""
     "\Identification\Description\Memo" = "Edited India boundaries - 3/10/1999"
     "\Identification\Time Period" = ""
     "\Identification\Time Period\Currentness" = "1995"
     "\Identification\Keywords" = ""
     "\Identification\Keywords\Theme" = ""
     "\Identification\Keywords\Theme\Geography" = "World"

If the bAllMappings parameter supplied to getDictionaryIterator in the call above is changed from `true` to `false`, the following output would be generated:

     "\Identification\Use Constraints" = "For use with MapXtreme"
     "\Identification\Description\Memo" = "Edited India boundaries - 3/10/1999"
     "\Identification\Time Period\Currentness" = "1995"
     "\Identification\Keywords\Theme\Geography" = "World"

Parameters:
  `bAllMappings` - `true` indicates that all key mappings, including those with empty values, will be returned by the iterator; `false` indicates that only mappings with non-empty values will be returned.
Returns:
  an iterator over this metadata's key-value mappings.