org.apache.poi.hpsf

## Class CustomProperties

- java.lang.Object
- - org.apache.poi.hpsf.CustomProperties

- All Implemented Interfaces:
    java.util.Map<java.lang.String,java.lang.Object>

      public class CustomProperties
      extends java.lang.Object
      implements java.util.Map<java.lang.String,java.lang.Object>

  Maintains the instances of `CustomProperty` that belong to a `DocumentSummaryInformation`. The class maintains the names of the custom properties in a dictionary. It implements the `Map` interface and by this provides a simplified view on custom properties: A property's name is the key that maps to a typed value. This implementation hides property IDs from the developer and regards the property names as keys to typed values.

  While this class provides a simple API to custom properties, it ignores the fact that not names, but IDs are the real keys to properties. Under the hood this class maintains a 1:1 relationship between IDs and names. Therefore you should not use this class to process property sets with several IDs mapping to the same name or with properties without a name: the result will contain only a subset of the original properties. If you really need to deal such property sets, use HPSF's low-level access methods.

  An application can call the `isPure` method to check whether a property set parsed by `CustomProperties` is still pure (i.e. unmodified) or whether one or more properties have been dropped.

  This class is not thread-safe; concurrent access to instances of this class must be synchronized.

  While this class is roughly HashMap<Long,CustomProperty>, that's the internal representation. To external calls, it should appear as HashMap<String,Object> mapping between Names and Custom Property Values.

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface java.util.Map

      `java.util.Map.Entry<K,V>`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CustomProperties()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clear()`
    `boolean` | `containsKey(java.lang.Object key)` Checks against both String Name and Long ID
    `boolean` | `containsValue(java.lang.Object value)` Checks against both the property, and its values.
    `java.util.Set<java.util.Map.Entry<java.lang.String,java.lang.Object>>` | `entrySet()`
    `boolean` | `equals(java.lang.Object obj)`
    `java.lang.Object` | `get(java.lang.Object key)` Gets a named value from the custom properties - only works for keys of type String
    `int` | `getCodepage()` Gets the codepage.
    `int` | `hashCode()`
    `java.util.Set<java.lang.Long>` | `idSet()` Returns a set of all the IDs of our custom properties
    `boolean` | `isEmpty()`
    `boolean` | `isPure()` Tells whether this `CustomProperties` instance is pure or one or more properties of the underlying low-level property set has been dropped.
    `java.util.Set` | `keySet()` Returns a set of all the names of our custom properties.
    `java.util.Set<java.lang.String>` | `nameSet()` Returns a set of all the names of our custom properties
    `java.util.List<CustomProperty>` | `properties()`
    `CustomProperty` | `put(java.lang.String name, CustomProperty cp)` Puts a `CustomProperty` into this map.
    `java.lang.Object` | `put(java.lang.String key, java.lang.Object value)` Adds a named property.
    `void` | `putAll(java.util.Map<? extends java.lang.String,?> m)`
    `CustomProperty` | `remove(java.lang.Object key)` Removes a custom property - only works for keys of type String
    `void` | `setCodepage(int codepage)` Sets the codepage.
    `void` | `setPure(boolean isPure)` Sets the purity of the custom property set.
    `int` | `size()`
    `java.util.Collection<java.lang.Object>` | `values()`

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

      `clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface java.util.Map

      `compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll`

- - ### Constructor Detail

    - #### CustomProperties

          public CustomProperties()

  - ### Method Detail

    - #### put

          public CustomProperty put(java.lang.String name,
                                    CustomProperty cp)

      Puts a `CustomProperty` into this map. It is assumed that the `CustomProperty` already has a valid ID. Otherwise use `put(CustomProperty)`.
      Parameters:
        `name` - the property name
        `cp` - the property
      Returns:
        the previous property stored under this name

    - #### put

          public java.lang.Object put(java.lang.String key,
                                      java.lang.Object value)

      Adds a named property.
      Specified by:
        `put` in interface `java.util.Map<java.lang.String,java.lang.Object>`
      Parameters:
        `key` - The property's name.
        `value` - The property's value.
      Returns:
        the property that was stored under the specified name before, or `null` if there was no such property before.

    - #### get

          public java.lang.Object get(java.lang.Object key)

      Gets a named value from the custom properties - only works for keys of type String
      Specified by:
        `get` in interface `java.util.Map<java.lang.String,java.lang.Object>`
      Parameters:
        `key` - the name of the value to get
      Returns:
        the value or `null` if a value with the specified name is not found in the custom properties.

    - #### remove

          public CustomProperty remove(java.lang.Object key)

      Removes a custom property - only works for keys of type String
      Specified by:
        `remove` in interface `java.util.Map<java.lang.String,java.lang.Object>`
      Parameters:
        `key` - The name of the custom property to remove
      Returns:
        The removed property or `null` if the specified property was not found.

    - #### size

          public int size()

      Specified by:
        `size` in interface `java.util.Map<java.lang.String,java.lang.Object>`

    - #### isEmpty

          public boolean isEmpty()

      Specified by:
        `isEmpty` in interface `java.util.Map<java.lang.String,java.lang.Object>`

    - #### clear

          public void clear()

      Specified by:
        `clear` in interface `java.util.Map<java.lang.String,java.lang.Object>`

    - #### hashCode

          public int hashCode()

      Specified by:
        `hashCode` in interface `java.util.Map<java.lang.String,java.lang.Object>`
      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### equals

          public boolean equals(java.lang.Object obj)

      Specified by:
        `equals` in interface `java.util.Map<java.lang.String,java.lang.Object>`
      Overrides:
        `equals` in class `java.lang.Object`

    - #### putAll

          public void putAll(java.util.Map<? extends java.lang.String,?> m)

      Specified by:
        `putAll` in interface `java.util.Map<java.lang.String,java.lang.Object>`

    - #### properties

          public java.util.List<CustomProperty> properties()

      Returns:
        the list of properties

    - #### values

          public java.util.Collection<java.lang.Object> values()

      Specified by:
        `values` in interface `java.util.Map<java.lang.String,java.lang.Object>`
      Returns:
        the list of property values - use `properties()` for the wrapped values

    - #### entrySet

          public java.util.Set<java.util.Map.Entry<java.lang.String,java.lang.Object>> entrySet()

      Specified by:
        `entrySet` in interface `java.util.Map<java.lang.String,java.lang.Object>`

    - #### keySet

          public java.util.Set keySet()

      Returns a set of all the names of our custom properties. Equivalent to `nameSet()`
      Specified by:
        `keySet` in interface `java.util.Map<java.lang.String,java.lang.Object>`
      Returns:
        a set of all the names of our custom properties

    - #### nameSet

          public java.util.Set<java.lang.String> nameSet()

      Returns a set of all the names of our custom properties
      Returns:
        a set of all the names of our custom properties

    - #### idSet

          public java.util.Set<java.lang.Long> idSet()

      Returns a set of all the IDs of our custom properties
      Returns:
        a set of all the IDs of our custom properties

    - #### setCodepage

          public void setCodepage(int codepage)

      Sets the codepage.
      Parameters:
        `codepage` - the codepage

    - #### getCodepage

          public int getCodepage()

      Gets the codepage.
      Returns:
        the codepage or -1 if the codepage is undefined.

    - #### containsKey

          public boolean containsKey(java.lang.Object key)

      Checks against both String Name and Long ID
      Specified by:
        `containsKey` in interface `java.util.Map<java.lang.String,java.lang.Object>`

    - #### containsValue

          public boolean containsValue(java.lang.Object value)

      Checks against both the property, and its values.
      Specified by:
        `containsValue` in interface `java.util.Map<java.lang.String,java.lang.Object>`

    - #### isPure

          public boolean isPure()

      Tells whether this `CustomProperties` instance is pure or one or more properties of the underlying low-level property set has been dropped.
      Returns:
        `true` if the `CustomProperties` is pure, else `false`.

    - #### setPure

          public void setPure(boolean isPure)

      Sets the purity of the custom property set.
      Parameters:
        `isPure` - the purity

Copyright 2020 The Apache Software Foundation or its licensors, as applicable.