org.opencms.file
Class CmsProperty

java.lang.Object
  org.opencms.file.CmsProperty

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.lang.Comparable

public class CmsProperty
extends java.lang.Object
implements java.io.Serializable, java.lang.Cloneable, java.lang.Comparable

Represents a property (meta-information) mapped to a VFS resource.

A property is an object that contains three string values: a name, a property value which is mapped to the structure record of a resource, and a property value which is mapped to the resource record of a resource. A property object is valid if it has both values or just one value set. Each property needs at least a name and one value set.

A property value mapped to the structure record of a resource is significant for a single resource (sibling). A property value mapped to the resource record of a resource is significant for all siblings of a resource record. This is possible by getting the "compound value" (see getValue()) of a property in case a property object has both values set. The compound value of a property object is the value mapped to the structure record, because it's structure value is more significant than it's resource value. This allows to set a property only one time on the resource record, and the property takes effect on all siblings of this resource record.

The ID of the structure or resource record where a property value is mapped to is represented by the "PROPERTY_MAPPING_ID" table attribute in the database. The "PROPERTY_MAPPING_TYPE" table attribute (see STRUCTURE_RECORD_MAPPING and RESOURCE_RECORD_MAPPING) determines whether the value of the "PROPERTY_MAPPING_ID" attribute of the current row is a structure or resource record ID.

Property objects are written to the database using CmsObject.writePropertyObject(String, CmsProperty) or CmsObject.writePropertyObjects(String, List), no matter whether you want to save a new (non-existing) property, update an existing property, or delete an existing property. To delete a property you would write a property object with either the structure and/or resource record values set to DELETE_VALUE to indicate that a property value should be deleted in the database. Set property values to null if they should remain unchanged in the database when a property object is written. As for example you want to update just the structure value of a property, you would set the structure value to the new string, and the resource value to null (which is already the case by default).

Use setAutoCreatePropertyDefinition(boolean) to set a boolean flag whether a missing property definition should be created implicitly for a resource type when a property is written to the database. The default value for this flag is false. Thus, you receive a CmsException if you try to write a property of a resource with a resource type which lacks a property definition for this resource type. It is not a good style to set setAutoCreatePropertyDefinition(boolean) on true to make writing properties to the database work in any case, because then you will loose control about which resource types support which property definitions.

Since:

6.0.0

Version:

$Revision: 1.42 $

Author:

Thomas Weckert

See Also:

Serialized Form

Field Summary

static int	DELETE_OPTION_DELETE_RESOURCE_VALUES Signals that the resource property values of a resource should be deleted using deleteAllProperties.
static int	DELETE_OPTION_DELETE_STRUCTURE_AND_RESOURCE_VALUES Signals that both the structure and resource property values of a resource should be deleted using deleteAllProperties.
static int	DELETE_OPTION_DELETE_STRUCTURE_VALUES Signals that the structure property values of a resource should be deleted using deleteAllProperties.
static java.lang.String	DELETE_VALUE An empty string to decide that a property value should be deleted when this property object is written to the database.
static int	RESOURCE_RECORD_MAPPING Value of the "mapping-type" database attribute to indicate that a property value is mapped to a resource record.
static int	STRUCTURE_RECORD_MAPPING Value of the "mapping-type" database attribute to indicate that a property value is mapped to a structure record.
static java.lang.String	TYPE_INDIVIDUAL Key used for a individual (structure) property value.
static java.lang.String	TYPE_SHARED Key used for a shared (resource) property value.
static char	VALUE_LIST_DELIMITER The delimiter value for separating values in a list, per default this is the | char.
static java.lang.String	VALUE_LIST_DELIMITER_REPLACEMENT The list delimiter replacement String used if the delimiter itself is contained in a String value.
static char	VALUE_MAP_DELIMITER The delimiter value for separating values in a map, per default this is the = char.
static java.lang.String	VALUE_MAP_DELIMITER_REPLACEMENT The map delimiter replacement String used if the delimiter itself is contained in a String value.

Constructor Summary

CmsProperty()
Creates a new CmsProperty object.

CmsProperty(java.lang.String name, java.lang.String structureValue, java.lang.String resourceValue)
Creates a new CmsProperty object using the provided values.

CmsProperty(java.lang.String name, java.lang.String structureValue, java.lang.String resourceValue, boolean autoCreatePropertyDefinition)
Creates a new CmsProperty object using the provided values.

Method Summary

boolean	autoCreatePropertyDefinition() Checks if the property definition for this property will be created implicitly on any write operation if doesn't already exist.
java.lang.Object	clone() Creates a clone of this property.
CmsProperty	cloneAsProperty() Creates a clone of this property that already is of type CmsProperty.
int	compareTo(java.lang.Object obj) Compares this property to another Object.
boolean	deleteResourceValue() Deprecated. use isDeleteResourceValue() instead
boolean	deleteStructureValue() Deprecated. use isDeleteStructureValue() instead
boolean	equals(java.lang.Object obj) Tests if a specified object is equal to this CmsProperty object.
static CmsProperty	get(java.lang.String name, java.util.List list) Searches in a list for the first occurrence of a CmsProperty object with the given name.
java.lang.String	getKey() Deprecated. use getName() instead
java.lang.String	getName() Returns the name of this property.
static CmsProperty	getNullProperty() Returns the null property object.
java.lang.String	getResourceValue() Returns the value of this property attached to the resource record.
java.util.List	getResourceValueList() Returns the value of this property attached to the resource record, split as a list.
java.util.Map	getResourceValueMap() Returns the value of this property attached to the resource record as a map.
java.lang.String	getStructureValue() Returns the value of this property attached to the structure record.
java.util.List	getStructureValueList() Returns the value of this property attached to the structure record, split as a list.
java.util.Map	getStructureValueMap() Returns the value of this property attached to the structure record as a map.
java.lang.String	getValue() Returns the compound value of this property.
java.lang.String	getValue(java.lang.String defaultValue) Returns the compound value of this property, or a specified default value, if both the structure and resource values are null.
java.util.List	getValueList() Returns the compound value of this property, split as a list.
java.util.List	getValueList(java.util.List defaultValue) Returns the compound value of this property, split as a list, or a specified default value list, if both the structure and resource values are null.
java.util.Map	getValueMap() Returns the compound value of this property as a map.
java.util.Map	getValueMap(java.util.Map defaultValue) Returns the compound value of this property as a map, or a specified default value map, if both the structure and resource values are null.
int	hashCode() Returns the hash code of the property, which is based only on the property name, not on the values.
boolean	isDeleteResourceValue() Checks if the resource value of this property should be deleted when this property object is written to the database.
boolean	isDeleteStructureValue() Checks if the structure value of this property should be deleted when this property object is written to the database.
boolean	isFrozen() Returns true if this property is frozen, that is read only.
boolean	isIdentical(CmsProperty property) Tests if a given CmsProperty is identical to this CmsProperty object.
boolean	isNullProperty() Checks if this property object is the null property object.
void	setAutoCreatePropertyDefinition(boolean value) Sets the boolean flag to decide if the property definition for this property should be created implicitly on any write operation if doesn't exist already.
static java.util.List	setAutoCreatePropertyDefinitions(java.util.List list, boolean value) Calls setAutoCreatePropertyDefinition(boolean) for each property object in the given List with the given value parameter.
void	setFrozen(boolean frozen) Sets the frozen state of the property, if set to true then this property is read only.
static java.util.List	setFrozen(java.util.List list) Calls setFrozen(boolean) for each CmsProperty object in the given List if it is not already frozen.
void	setKey(java.lang.String name) Deprecated. use setName(String) instead
void	setName(java.lang.String name) Sets the name of this property.
void	setResourceValue(java.lang.String resourceValue) Sets the value of this property attached to the resource record.
void	setResourceValueList(java.util.List valueList) Sets the value of this property attached to the resource record from the given list of Strings.
void	setResourceValueMap(java.util.Map valueMap) Sets the value of this property attached to the resource record from the given map of Strings.
void	setStructureValue(java.lang.String structureValue) Sets the value of this property attached to the structure record.
void	setStructureValueList(java.util.List valueList) Sets the value of this property attached to the structure record from the given list of Strings.
void	setStructureValueMap(java.util.Map valueMap) Sets the value of this property attached to the structure record from the given map of Strings.
void	setValue(java.lang.String value, java.lang.String type) Sets the value of this property as either shared or individual value.
static java.util.List	toList(java.util.Map map) Transforms a Map of String values into a list of CmsProperty objects with the property name set from the Map key, and the structure value set from the Map value.
static java.util.Map	toMap(java.util.List list) Transforms a list of CmsProperty objects into a Map which uses the property name as Map key (String), and the property value as Map value (String).
java.lang.String	toString() Returns a string representation of this property object.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

DELETE_OPTION_DELETE_RESOURCE_VALUES

public static final int DELETE_OPTION_DELETE_RESOURCE_VALUES

Signals that the resource property values of a resource should be deleted using deleteAllProperties.

See Also:

Constant Field Values

DELETE_OPTION_DELETE_STRUCTURE_AND_RESOURCE_VALUES

public static final int DELETE_OPTION_DELETE_STRUCTURE_AND_RESOURCE_VALUES

Signals that both the structure and resource property values of a resource should be deleted using deleteAllProperties.

See Also:

Constant Field Values

DELETE_OPTION_DELETE_STRUCTURE_VALUES

public static final int DELETE_OPTION_DELETE_STRUCTURE_VALUES

Signals that the structure property values of a resource should be deleted using deleteAllProperties.

See Also:

Constant Field Values

DELETE_VALUE

public static final java.lang.String DELETE_VALUE

An empty string to decide that a property value should be deleted when this property object is written to the database.

See Also:

Constant Field Values

RESOURCE_RECORD_MAPPING

public static final int RESOURCE_RECORD_MAPPING

Value of the "mapping-type" database attribute to indicate that a property value is mapped to a resource record.

See Also:

Constant Field Values

STRUCTURE_RECORD_MAPPING

public static final int STRUCTURE_RECORD_MAPPING

Value of the "mapping-type" database attribute to indicate that a property value is mapped to a structure record.

See Also:

Constant Field Values

TYPE_INDIVIDUAL

public static final java.lang.String TYPE_INDIVIDUAL

Key used for a individual (structure) property value.

See Also:

Constant Field Values

TYPE_SHARED

public static final java.lang.String TYPE_SHARED

Key used for a shared (resource) property value.

See Also:

Constant Field Values

VALUE_LIST_DELIMITER

public static final char VALUE_LIST_DELIMITER

The delimiter value for separating values in a list, per default this is the | char.

See Also:

Constant Field Values

VALUE_LIST_DELIMITER_REPLACEMENT

public static final java.lang.String VALUE_LIST_DELIMITER_REPLACEMENT

The list delimiter replacement String used if the delimiter itself is contained in a String value.

See Also:

Constant Field Values

VALUE_MAP_DELIMITER

public static final char VALUE_MAP_DELIMITER

The delimiter value for separating values in a map, per default this is the = char.

See Also:

Constant Field Values

VALUE_MAP_DELIMITER_REPLACEMENT

public static final java.lang.String VALUE_MAP_DELIMITER_REPLACEMENT

The map delimiter replacement String used if the delimiter itself is contained in a String value.

See Also:

Constant Field Values

Constructor Detail

CmsProperty

public CmsProperty()

Creates a new CmsProperty object.

The structure and resource property values are initialized to null. The structure and resource IDs are initialized to CmsUUID.getNullUUID().

CmsProperty

public CmsProperty(java.lang.String name,
                   java.lang.String structureValue,
                   java.lang.String resourceValue)

Creates a new CmsProperty object using the provided values.

If the property definition does not exist for the resource type it is automatically created when this property is written.

Parameters:

name - the name of the property definition

structureValue - the value to write as structure property

resourceValue - the value to write as resource property

CmsProperty

public CmsProperty(java.lang.String name,
                   java.lang.String structureValue,
                   java.lang.String resourceValue,
                   boolean autoCreatePropertyDefinition)

Creates a new CmsProperty object using the provided values.

If null is supplied for the resource or structure value, this value will not be available for this property.

Parameters:

name - the name of the property definition

structureValue - the value to write as structure property, or null

resourceValue - the value to write as resource property , or null

autoCreatePropertyDefinition - if true, the property definition for this property will be created implicitly on any write operation if it doesn't exist already

Method Detail

get

public static final CmsProperty get(java.lang.String name,
                                    java.util.List list)

Searches in a list for the first occurrence of a CmsProperty object with the given name.

To check if the "null property" has been returned if a property was not found, use isNullProperty() on the result.

Parameters:

name - a property name

list - a list of CmsProperty objects

Returns:

the index of the first occurrence of the name in they specified list, or getNullProperty() if the name is not found

getNullProperty

public static final CmsProperty getNullProperty()

Returns the null property object.

Returns:

the null property object

setAutoCreatePropertyDefinitions

public static final java.util.List setAutoCreatePropertyDefinitions(java.util.List list,
                                                                    boolean value)

Calls setAutoCreatePropertyDefinition(boolean) for each property object in the given List with the given value parameter.

This method will modify the objects in the input list directly.

Parameters:

list - a list of CmsProperty objects to modify

value - boolean value

Returns:

the modified list of CmsProperty objects

See Also:

setAutoCreatePropertyDefinition(boolean)

setFrozen

public static final java.util.List setFrozen(java.util.List list)

Calls setFrozen(boolean) for each CmsProperty object in the given List if it is not already frozen.

This method will modify the objects in the input list directly.

Parameters:

list - a list of CmsProperty objects

Returns:

the modified list of properties

See Also:

setFrozen(boolean)

toList

public static java.util.List toList(java.util.Map map)

Transforms a Map of String values into a list of CmsProperty objects with the property name set from the Map key, and the structure value set from the Map value.

Parameters:

map - a Map with String keys and String values

Returns:

a list of CmsProperty objects

toMap

public static java.util.Map toMap(java.util.List list)

Transforms a list of CmsProperty objects into a Map which uses the property name as Map key (String), and the property value as Map value (String).

Parameters:

list - a list of CmsProperty objects

Returns:

a Map which uses the property names as Map keys (String), and the property values as Map values (String)

autoCreatePropertyDefinition

public boolean autoCreatePropertyDefinition()

Checks if the property definition for this property will be created implicitly on any write operation if doesn't already exist.

Returns:

true, if the property definition for this property will be created implicitly on any write operation

clone

public java.lang.Object clone()

Creates a clone of this property.

Overrides:

clone in class java.lang.Object

Returns:

a clone of this property

See Also:

cloneAsProperty()

cloneAsProperty

public CmsProperty cloneAsProperty()

Creates a clone of this property that already is of type CmsProperty.

The cloned property will not be frozen.

Returns:

a clone of this property that already is of type CmsProperty

compareTo

public int compareTo(java.lang.Object obj)

Compares this property to another Object.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

obj - the other object to be compared

Returns:

if the argument is a property object, returns zero if the name of the argument is equal to the name of this property object, a value less than zero if the name of this property is lexicographically less than the name of the argument, or a value greater than zero if the name of this property is lexicographically greater than the name of the argument

deleteResourceValue

public boolean deleteResourceValue()

Deprecated. use isDeleteResourceValue() instead

Checks if the resource value of this property should be deleted when this property object is written to the database.

Returns:

true, if the resource value of this property should be deleted

deleteStructureValue

public boolean deleteStructureValue()

Deprecated. use isDeleteStructureValue() instead

Checks if the structure value of this property should be deleted when this property object is written to the database.

Returns:

true, if the structure value of this property should be deleted

equals

public boolean equals(java.lang.Object obj)

Tests if a specified object is equal to this CmsProperty object.

Two property objects are equal if their names are equal.

In case you want to compare the values as well as the name, use isIdentical(CmsProperty) instead.

Overrides:

equals in class java.lang.Object

Parameters:

obj - another object

Returns:

true, if the specified object is equal to this CmsProperty object

See Also:

isIdentical(CmsProperty)

getKey

public java.lang.String getKey()

Deprecated. use getName() instead

Returns the name of this property.

Returns:

name of this property

getName

public java.lang.String getName()

Returns the name of this property.

Returns:

the name of this property

getResourceValue

public java.lang.String getResourceValue()

Returns the value of this property attached to the resource record.

Returns:

the value of this property attached to the resource record

getResourceValueList

public java.util.List getResourceValueList()

Returns the value of this property attached to the resource record, split as a list.

This list is build form the resource value, which is split into separate values using the | char as delimiter. If the delimiter is not found, then the list will contain one entry which is equal to getResourceValue().

Returns:

the value of this property attached to the resource record, split as a (unmodifiable) list of Strings

getResourceValueMap

public java.util.Map getResourceValueMap()

Returns the value of this property attached to the resource record as a map.

This map is build from the used value, which is split into separate key/value pairs using the | char as delimiter. If the delimiter is not found, then the map will contain one entry.

The key/value pairs are separated with the =.

Returns:

the value of this property attached to the resource record, as an (unmodifiable) map of Strings

getStructureValue

public java.lang.String getStructureValue()

Returns the value of this property attached to the structure record.

Returns:

the value of this property attached to the structure record

getStructureValueList

public java.util.List getStructureValueList()

Returns the value of this property attached to the structure record, split as a list.

This list is build form the structure value, which is split into separate values using the | char as delimiter. If the delimiter is not found, then the list will contain one entry which is equal to getStructureValue().

Returns:

the value of this property attached to the structure record, split as a (unmodifiable) list of Strings

getStructureValueMap

public java.util.Map getStructureValueMap()

Returns the value of this property attached to the structure record as a map.

This map is build from the used value, which is split into separate key/value pairs using the | char as delimiter. If the delimiter is not found, then the map will contain one entry.

The key/value pairs are separated with the =.

Returns:

the value of this property attached to the structure record, as an (unmodifiable) map of Strings

getValue

public java.lang.String getValue()

Returns the compound value of this property.

The value returned is the value of getStructureValue(), if it is not null. Otherwise the value if getResourceValue() is returned (which may also be null).

Returns:

the compound value of this property

getValue

public java.lang.String getValue(java.lang.String defaultValue)

Returns the compound value of this property, or a specified default value, if both the structure and resource values are null.

In other words, this method returns the defaultValue if this property object is the null property (see getNullProperty()).

Parameters:

defaultValue - a default value which is returned if both the structure and resource values are null

Returns:

the compound value of this property, or the default value

getValueList

public java.util.List getValueList()

Returns the compound value of this property, split as a list.

This list is build form the used value, which is split into separate values using the | char as delimiter. If the delimiter is not found, then the list will contain one entry.

The value returned is the value of getStructureValueList(), if it is not null. Otherwise the value of getResourceValueList() is returned (which may also be null).

Returns:

the compound value of this property, split as a (unmodifiable) list of Strings

getValueList

public java.util.List getValueList(java.util.List defaultValue)

Returns the compound value of this property, split as a list, or a specified default value list, if both the structure and resource values are null.

In other words, this method returns the defaultValue if this property object is the null property (see getNullProperty()).

Parameters:

defaultValue - a default value list which is returned if both the structure and resource values are null

Returns:

the compound value of this property, split as a (unmodifiable) list of Strings

getValueMap

public java.util.Map getValueMap()

Returns the compound value of this property as a map.

This map is build from the used value, which is split into separate key/value pairs using the | char as delimiter. If the delimiter is not found, then the map will contain one entry.

The key/value pairs are separated with the =.

The value returned is the value of getStructureValueMap(), if it is not null. Otherwise the value of getResourceValueMap() is returned (which may also be null).

Returns:

the compound value of this property as a (unmodifiable) map of Strings

getValueMap

public java.util.Map getValueMap(java.util.Map defaultValue)

Returns the compound value of this property as a map, or a specified default value map, if both the structure and resource values are null.

In other words, this method returns the defaultValue if this property object is the null property (see getNullProperty()).

Parameters:

defaultValue - a default value map which is returned if both the structure and resource values are null

Returns:

the compound value of this property as a (unmodifiable) map of Strings

hashCode

public int hashCode()

Returns the hash code of the property, which is based only on the property name, not on the values.

The resource and structure values are not taken into consideration for the hashcode generation because the equals(Object) implementation also does not take these into consideration.

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code of the property

See Also:

Object.hashCode()

isDeleteResourceValue

public boolean isDeleteResourceValue()

Checks if the resource value of this property should be deleted when this property object is written to the database.

Returns:

true, if the resource value of this property should be deleted

See Also:

DELETE_VALUE

isDeleteStructureValue

public boolean isDeleteStructureValue()

Checks if the structure value of this property should be deleted when this property object is written to the database.

Returns:

true, if the structure value of this property should be deleted

See Also:

DELETE_VALUE

isFrozen

public boolean isFrozen()

Returns true if this property is frozen, that is read only.

Returns:

true if this property is frozen, that is read only

isIdentical

public boolean isIdentical(CmsProperty property)

Tests if a given CmsProperty is identical to this CmsProperty object.

The property object are identical if their name, structure and resource values are all equals.

Parameters:

property - another property object

Returns:

true, if the specified object is equal to this CmsProperty object

isNullProperty

public boolean isNullProperty()

Checks if this property object is the null property object.

Returns:

true if this property object is the null property object

setAutoCreatePropertyDefinition

public void setAutoCreatePropertyDefinition(boolean value)

Sets the boolean flag to decide if the property definition for this property should be created implicitly on any write operation if doesn't exist already.

Parameters:

value - true, if the property definition for this property should be created implicitly on any write operation

setFrozen

public void setFrozen(boolean frozen)

Sets the frozen state of the property, if set to true then this property is read only.

If the property is already frozen, then setting the frozen state to true again is allowed, but setting the value to false causes a CmsRuntimeException.

Parameters:

frozen - the frozen state to set

setKey

public void setKey(java.lang.String name)

Deprecated. use setName(String) instead

Sets the name of this property.

Parameters:

name - the name of this property

setName

public void setName(java.lang.String name)

Sets the name of this property.

Parameters:

name - the name to set

setResourceValue

public void setResourceValue(java.lang.String resourceValue)

Sets the value of this property attached to the resource record.

Parameters:

resourceValue - the value of this property attached to the resource record

setResourceValueList

public void setResourceValueList(java.util.List valueList)

Sets the value of this property attached to the resource record from the given list of Strings.

The value will be created from the individual values of the given list, which are appended using the | char as delimiter.

Parameters:

valueList - the list of value (Strings) to attach to the resource record

setResourceValueMap

public void setResourceValueMap(java.util.Map valueMap)

Sets the value of this property attached to the resource record from the given map of Strings.

The value will be created from the individual values of the given map, which are appended using the | char as delimiter, the map keys and values are separated by a =.

Parameters:

valueMap - the map of key/value (Strings) to attach to the resource record

setStructureValue

public void setStructureValue(java.lang.String structureValue)

Sets the value of this property attached to the structure record.

Parameters:

structureValue - the value of this property attached to the structure record

setStructureValueList

public void setStructureValueList(java.util.List valueList)

Sets the value of this property attached to the structure record from the given list of Strings.

The value will be created from the individual values of the given list, which are appended using the | char as delimiter.

Parameters:

valueList - the list of value (Strings) to attach to the structure record

setStructureValueMap

public void setStructureValueMap(java.util.Map valueMap)

Sets the value of this property attached to the structure record from the given map of Strings.

The value will be created from the individual values of the given map, which are appended using the | char as delimiter, the map keys and values are separated by a =.

Parameters:

valueMap - the map of key/value (Strings) to attach to the structure record

setValue

public void setValue(java.lang.String value,
                     java.lang.String type)

Sets the value of this property as either shared or individual value.

If the given type equals TYPE_SHARED then the value is set as a shared (resource) value, otherwise it is set as individual (structure) value.

Parameters:

value - the value to set

type - the value type to set

toString

public java.lang.String toString()

Returns a string representation of this property object.

Overrides:

toString in class java.lang.Object

See Also:

Object.toString()