org.opencms.file
Class CmsProperty

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

All Implemented Interfaces:

Cloneable, Comparable, Serializable

public class CmsProperty

extends Object

implements Serializable, Cloneable, 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.29 $

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 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 String	TYPE_INDIVIDUAL Key used for a individual (structure) property value.
static String	TYPE_SHARED Key used for a shared (resource) property value.

Constructor Summary

CmsProperty()
Creates a new CmsProperty object.

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

CmsProperty(String name, String structureValue, 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 should be created implicitly on any write operation if doesn't exist already.
Object	clone() Creates a clone of this property.
int	compareTo(Object obj) Compares this property to another Object.
boolean	deleteResourceValue() Checks if the resource value of this property should be deleted when this property object is written to the database.
boolean	deleteStructureValue() Checks if the structure value of this property should be deleted when this property object is written to the database.
boolean	equals(Object obj) Tests if a specified object is equal to this CmsProperty object.
static CmsProperty	get(String name, List list) Searches in a list for the first occurence of a Cms property object with the given name.
String	getKey() Deprecated. use getName() instead
String	getName() Returns the name of this property.
static CmsProperty	getNullProperty() Returns the null property object.
String	getResourceValue() Returns the value of this property attached to the resource record.
String	getStructureValue() Returns the value of this property attached to the structure record.
String	getValue() Returns the compound value of this property.
String	getValue(String defaultValue) Returns the compound value of this property, or a specified default value, if both the structure and resource values are null.
int	hashCode()
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 List	setAutoCreatePropertyDefinitions(List list, boolean value) Sets in each property object of a specified list a boolean value to decide if missing property definitions should be created implicitly or not if the property objects of the list are written to the database.
void	setKey(String name) Deprecated. use setName(String) instead
void	setName(String name) Sets the name of this property.
void	setResourceValue(String resourceValue) Sets the value of this property attached to the resource record.
void	setStructureValue(String structureValue) Sets the value of this property attached to the structure record.
void	setValue(String value, String type) Sets the value of this property as either shared or individual value.
static List	toList(Map map) Transforms a map with compound (String) values keyed by property names into a list of CmsProperty objects with structure values.
static Map	toMap(List list) Transforms a list of CmsProperty objects with structure and resource values into a map with compound (String) values keyed by property names.
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 String DELETE_VALUE

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

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 String TYPE_INDIVIDUAL

Key used for a individual (structure) property value.

See Also:

Constant Field Values

TYPE_SHARED

public static final String TYPE_SHARED

Key used for a shared (resource) property 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(String name,
                   String structureValue,
                   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 propery 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(String name,
                   String structureValue,
                   String resourceValue,
                   boolean autoCreatePropertyDefinition)

Creates a new CmsProperty object using the provided values.

Parameters:

name - the name of the property definition

structureValue - the value to write as structure property

resourceValue - the value to write as resource property

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

Method Detail

get

public static final CmsProperty get(String name,
                                    List list)

Searches in a list for the first occurence of a Cms property 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 Cms property objects

Returns:

the index of the first occurrence of the name in they specified list, or the "null-property" 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 List setAutoCreatePropertyDefinitions(List list,
                                                          boolean value)

Sets in each property object of a specified list a boolean value to decide if missing property definitions should be created implicitly or not if the property objects of the list are written to the database.

Parameters:

list - a list of property objects

value - boolean value

Returns:

the list which each property object set that missing property definitions should be created implicitly

See Also:

setAutoCreatePropertyDefinition(boolean)

toList

public static List toList(Map map)

Transforms a map with compound (String) values keyed by property names into a list of CmsProperty objects with structure values.

This method is to prevent issues with backward incompatibilities in older code. Use this method with caution, it might be removed without with being deprecated before.

Parameters:

map - a map with compound (String) values keyed by property names

Returns:

a list of CmsProperty objects

toMap

public static Map toMap(List list)

Transforms a list of CmsProperty objects with structure and resource values into a map with compound (String) values keyed by property names.

This method is to prevent issues with backward incompatibilities in older code. Use this method with caution, it might be removed without with being deprecated before.

Parameters:

list - a list of CmsProperty objects

Returns:

a map with compound (String) values keyed by property names

autoCreatePropertyDefinition

public boolean autoCreatePropertyDefinition()

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

Returns:

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

clone

public Object clone()

Creates a clone of this property.

Returns:

a clone of this property

compareTo

public int compareTo(Object obj)

Compares this property to another Object.

If the Object is a property, this method behaves like String.compareTo(java.lang.String). Otherwise, it throws a ClassCastException (as properties are comparable only to other properties).

Specified by:

compareTo in interface 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()

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

deleteStructureValue

public boolean deleteStructureValue()

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

equals

public boolean equals(Object obj)

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

Two property objecs are equal if their names are equal.

Parameters:

obj - another object

Returns:

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

getKey

public String getKey()

Deprecated. use getName() instead

Returns the name of this property.

Returns:

name of this property

getName

public String getName()

Returns the name of this property.

Returns:

the name of this property

getResourceValue

public String getResourceValue()

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

Returns:

the value of this property attached to the resource record

getStructureValue

public String getStructureValue()

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

Returns:

the value of this property attached to the structure record

getValue

public String getValue()

Returns the compound value of this property.

The value returned is the structure value, if only the structure value is set. Dito for the resource value, if only the resource value is set. If both values are set, the structure value is returned.

Returns:

the compound value of this property

getValue

public String getValue(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

hashCode

public int hashCode()

See Also:

Object.hashCode()

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

setKey

public void setKey(String name)

Deprecated. use setName(String) instead

Sets the name of this property.

Parameters:

name - the name of this property

setName

public void setName(String name)

Sets the name of this property.

Parameters:

name - the name to set

setResourceValue

public void setResourceValue(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

setStructureValue

public void setStructureValue(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

setValue

public void setValue(String value,
                     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 String toString()

Returns a string representation of this property object.

See Also:

Object.toString()