Top Description Fields Constructors Methods
org.apache.poi.hpsf

public Class CustomProperties

extends Object
implements Map<String, Object>
Class Inheritance
All Implemented Interfaces
java.util.Map
Imports
java.io.UnsupportedEncodingException, java.math.BigInteger, java.nio.charset.Charset, java.util.ArrayList, .Collection, .Collections, .Date, .HashMap, .LinkedHashMap, .List, .Map, .Set, org.apache.commons.collections4.bidimap.TreeBidiMap, org.apache.logging.log4j.LogManager, .Logger, org.apache.poi.hpsf.wellknown.PropertyIDMap, org.apache.poi.util.CodePageUtil
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.

Field Summary

Modifier and TypeField and Description
private int
codepage

private final TreeBidiMap<Long, String>
dictionary

Maps property IDs to property names and vice versa.

private boolean
isPure

Tells whether this object is pure or not.

private static final Logger
LOG

private final HashMap<Long, CustomProperty>
props

The custom properties

Constructor Summary

AccessConstructor and Description
public
CustomProperties()

Method Summary

Modifier and TypeMethod and Description
private void
checkCodePage(String value)

public void
clear()

Implements java.util.Map.clear.

Removes all of the mappings from this map (optional operation).

public boolean
containsKey(Object
key whose presence in this map is to be tested
key)

Implements java.util.Map.containsKey.

Checks against both String Name and Long ID

public boolean
containsValue(Object
value whose presence in this map is to be tested
value)

Implements java.util.Map.containsValue.

Checks against both the property, and its values.

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

Implements java.util.Map.entrySet.

Returns a Set view of the mappings contained in this map.

public boolean
equals(Object
object to be compared for equality with this map
obj)

Overrides java.lang.Object.equals.

Implements java.util.Map.equals.

Compares the specified object with this map for equality.

public Object

Returns:

the value or null if a value with the specified name is not found in the custom properties.
get(final Object
the name of the value to get
key)

Implements java.util.Map.get.

Gets a named value from the custom properties - only works for keys of type String

public int

Returns:

the codepage or -1 if the codepage is undefined.
getCodepage()

Gets the codepage.

pack-priv Map<Long, String>

Returns:

the dictionary.
getDictionary()

Gets the dictionary which contains IDs and names of the named custom properties.

public int
hashCode()

Overrides java.lang.Object.hashCode.

Implements java.util.Map.hashCode.

Returns the hash code value for this map.

public Set<Long>

Returns:

a set of all the IDs of our custom properties
idSet()

Returns a set of all the IDs of our custom properties

public boolean
isEmpty()

Implements java.util.Map.isEmpty.

Returns true if this map contains no key-value mappings.

public boolean

Returns:

true if the CustomProperties is pure, else false.
isPure()

Tells whether this CustomProperties instance is pure or one or more properties of the underlying low-level property set has been dropped.

public Set<String>

Returns:

a set of all the names of our custom properties
keySet()

Implements java.util.Map.keySet.

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

public Set<String>

Returns:

a set of all the names of our custom properties
nameSet()

Returns a set of all the names of our custom properties

public List<CustomProperty>

Returns:

the list of properties
properties()

public CustomProperty

Returns:

the previous property stored under this name
put(final String
the property name
name, final CustomProperty
the property
cp)

Implements java.util.Map.put.

Puts a CustomProperty into this map.

public Object

Returns:

the property that was stored under the specified name before, or null if there was no such property before.
put(String
The property's name.
key, Object
The property's value.
value)

Implements java.util.Map.put.

Adds a named property.

private Object

Returns:

If there was already a property with the same name, the old property
put(final CustomProperty
The CustomProperty to add.
customProperty)

Puts a CustomProperty that has not yet a valid ID into this map.

public void
putAll(Map<? extends String, ?>
mappings to be stored in this map
m)

Implements java.util.Map.putAll.

Copies all of the mappings from the specified map to this map (optional operation).

public CustomProperty

Returns:

The removed property or null if the specified property was not found.
remove(Object
The name of the custom property to remove
key)

Implements java.util.Map.remove.

Removes a custom property - only works for keys of type String

public void
setCodepage(final int
the codepage
codepage)

Sets the codepage.

public void
setPure(final boolean
the purity
isPure)

Sets the purity of the custom property set.

public int
size()

Implements java.util.Map.size.

Returns the number of key-value mappings in this map.

public Collection<Object>

Returns:

the list of property values - use properties() for the wrapped values
values()

Implements java.util.Map.values.

Returns a Collection view of the values contained in this map.

Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAlltoStringwaitwaitwait

Field Detail

codepageback to summary
private int codepage
dictionaryback to summary
private final TreeBidiMap<Long, String> dictionary

Maps property IDs to property names and vice versa.

isPureback to summary
private boolean isPure

Tells whether this object is pure or not.

LOGback to summary
private static final Logger LOG
propsback to summary
private final HashMap<Long, CustomProperty> props

The custom properties

Constructor Detail

CustomPropertiesback to summary
public CustomProperties()

Method Detail

checkCodePageback to summary
private void checkCodePage(String value)
clearback to summary
public void clear()

Implements java.util.Map.clear.

Doc from java.util.Map.clear.

Removes all of the mappings from this map (optional operation). The map will be empty after this call returns.

Annotations
@Override
containsKeyback to summary
public boolean containsKey(Object key)

Implements java.util.Map.containsKey.

Checks against both String Name and Long ID

Parameters
key:Object

Doc from java.util.Map.containsKey.

key whose presence in this map is to be tested

Returns:boolean

Doc from java.util.Map.containsKey.

true if this map contains a mapping for the specified key

Annotations
@Override
containsValueback to summary
public boolean containsValue(Object value)

Implements java.util.Map.containsValue.

Checks against both the property, and its values.

Parameters
value:Object

Doc from java.util.Map.containsValue.

value whose presence in this map is to be tested

Returns:boolean

Doc from java.util.Map.containsValue.

true if this map maps one or more keys to the specified value

Annotations
@Override
entrySetback to summary
public Set<Map.Entry<String, Object>> entrySet()

Implements java.util.Map.entrySet.

Doc from java.util.Map.entrySet.

Returns a Set view of the mappings contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress (except through the iterator's own remove operation, or through the setValue operation on a map entry returned by the iterator) the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations.

Returns:Set<Map.Entry<String, Object>>

a set view of the mappings contained in this map

Annotations
@Override
equalsback to summary
public boolean equals(Object obj)

Overrides java.lang.Object.equals.

Implements java.util.Map.equals.

Doc from java.util.Map.equals.

Compares the specified object with this map for equality. Returns true if the given object is also a map and the two maps represent the same mappings. More formally, two maps m1 and m2 represent the same mappings if m1.entrySet().equals(m2.entrySet()). This ensures that the equals method works properly across different implementations of the Map interface.

Parameters
obj:Object

object to be compared for equality with this map

Returns:boolean

true if the specified object is equal to this map

Annotations
@Override
getback to summary
public Object get(final Object key)

Implements java.util.Map.get.

Gets a named value from the custom properties - only works for keys of type String

Parameters
key:Object

the name of the value to get

Returns:Object

the value or null if a value with the specified name is not found in the custom properties.

Annotations
@Override
getCodepageback to summary
public int getCodepage()

Gets the codepage.

Returns:int

the codepage or -1 if the codepage is undefined.

getDictionaryback to summary
pack-priv Map<Long, String> getDictionary()

Gets the dictionary which contains IDs and names of the named custom properties.

Returns:Map<Long, String>

the dictionary.

hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Implements java.util.Map.hashCode.

Doc from java.util.Map.hashCode.

Returns the hash code value for this map. The hash code of a map is defined to be the sum of the hash codes of each entry in the map's entrySet() view. This ensures that m1.equals(m2) implies that m1.hashCode()==m2.hashCode() for any two maps m1 and m2, as required by the general contract of Object#hashCode.

Returns:int

the hash code value for this map

Annotations
@Override
idSetback to summary
public Set<Long> idSet()

Returns a set of all the IDs of our custom properties

Returns:Set<Long>

a set of all the IDs of our custom properties

isEmptyback to summary
public boolean isEmpty()

Implements java.util.Map.isEmpty.

Doc from java.util.Map.isEmpty.

Returns true if this map contains no key-value mappings.

Returns:boolean

true if this map contains no key-value mappings

Annotations
@Override
isPureback to summary
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:boolean

true if the CustomProperties is pure, else false.

keySetback to summary
public Set<String> keySet()

Implements java.util.Map.keySet.

Returns a set of all the names of our custom properties. Equivalent to nameSet()

Returns:Set<String>

a set of all the names of our custom properties

Annotations
@Override
nameSetback to summary
public Set<String> nameSet()

Returns a set of all the names of our custom properties

Returns:Set<String>

a set of all the names of our custom properties

propertiesback to summary
public List<CustomProperty> properties()
Returns:List<CustomProperty>

the list of properties

putback to summary
public CustomProperty put(final String name, final CustomProperty cp)

Implements java.util.Map.put.

Puts a CustomProperty into this map. It is assumed that the CustomProperty already has a valid ID. Otherwise use put(CustomProperty).

Parameters
name:String

the property name

cp:CustomProperty

the property

Returns:CustomProperty

the previous property stored under this name

putback to summary
public Object put(String key, Object value)

Implements java.util.Map.put.

Adds a named property.

Parameters
key:String

The property's name.

value:Object

The property's value.

Returns:Object

the property that was stored under the specified name before, or null if there was no such property before.

Annotations
@Override
putback to summary
private Object put(final CustomProperty customProperty) throws ClassCastException

Puts a CustomProperty that has not yet a valid ID into this map. The method will allocate a suitable ID for the custom property:

  • If there is already a property with the same name, take the ID of that property.
  • Otherwise find the highest ID and use its value plus one.
Parameters
customProperty:CustomProperty

The CustomProperty to add.

Returns:Object

If there was already a property with the same name, the old property

putAllback to summary
public void putAll(Map<? extends String, ?> m)

Implements java.util.Map.putAll.

Doc from java.util.Map.putAll.

Copies all of the mappings from the specified map to this map (optional operation). The effect of this call is equivalent to that of calling put(k, v) on this map once for each mapping from key k to value v in the specified map. The behavior of this operation is undefined if the specified map is modified while the operation is in progress. If the specified map has a defined encounter order, processing of its mappings generally occurs in that order.

Parameters
m:Map<? extends String, ?>

mappings to be stored in this map

Annotations
@Override
removeback to summary
public CustomProperty remove(Object key)

Implements java.util.Map.remove.

Removes a custom property - only works for keys of type String

Parameters
key:Object

The name of the custom property to remove

Returns:CustomProperty

The removed property or null if the specified property was not found.

Annotations
@Override
setCodepageback to summary
public void setCodepage(final int codepage)

Sets the codepage.

Parameters
codepage:int

the codepage

setPureback to summary
public void setPure(final boolean isPure)

Sets the purity of the custom property set.

Parameters
isPure:boolean

the purity

sizeback to summary
public int size()

Implements java.util.Map.size.

Doc from java.util.Map.size.

Returns the number of key-value mappings in this map. If the map contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Returns:int

the number of key-value mappings in this map

Annotations
@Override
valuesback to summary
public Collection<Object> values()

Implements java.util.Map.values.

Doc from java.util.Map.values.

Returns a Collection view of the values contained in this map. The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. If the map is modified while an iteration over the collection is in progress (except through the iterator's own remove operation), the results of the iteration are undefined. The collection supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Collection.remove, removeAll, retainAll and clear operations. It does not support the add or addAll operations.

Returns:Collection<Object>

the list of property values - use properties() for the wrapped values

Annotations
@Override