Package org.opencms.file

Class CmsProperty

java.lang.Object
org.opencms.file.CmsProperty
All Implemented Interfaces:
Serializable, Cloneable, Comparable<CmsProperty>
public class CmsProperty extends Object implements Serializable, Cloneable, Comparable<CmsProperty>
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
See Also:

  • Field Details

  • Constructor Details

    • 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 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(String name, String structureValue, 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 Details

    • get

      public static final CmsProperty get(String name, List<CmsProperty> 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

    • getLocaleSpecificPropertyValue

      public static String getLocaleSpecificPropertyValue(Map<String,CmsProperty> propertiesMap, String key, Locale locale)
      Returns the value for the best matching local-specific property version.
      Parameters:
      propertiesMap - the "raw" property map
      key - the name of the property to search for
      locale - the locale to search for
      Returns:
      the key for the best matching local-specific property version.

    • getLocalizedKey

      public static String getLocalizedKey(Map<String,?> propertiesMap, String key, Locale locale)
      Returns the key for the best matching local-specific property version.
      Parameters:
      propertiesMap - the "raw" property map
      key - the name of the property to search for
      locale - the locale to search for
      Returns:
      the key for the best matching local-specific property version.

    • getNullProperty

      public static final CmsProperty getNullProperty()
      Returns the null property object.

      Returns:
      the null property object

    • getPropertyMap

      public static Map<String,CmsProperty> getPropertyMap(List<CmsProperty> list)
      Transforms a list of CmsProperty objects with structure and resource values into a map with CmsProperty object values keyed by property keys.

      Parameters:
      list - a list of CmsProperty objects
      Returns:
      a map with CmsPropery object values keyed by property keys

    • setAutoCreatePropertyDefinitions

      public static final List<CmsProperty> setAutoCreatePropertyDefinitions(List<CmsProperty> 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:

    • setFrozen

      public static final List<CmsProperty> setFrozen(List<CmsProperty> 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:

    • toList

      public static List<CmsProperty> toList(Map<String,String> 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 Map<String,String> toMap(List<CmsProperty> 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)

    • toObjectMap

      public static Map<String,CmsProperty> toObjectMap(Iterable<CmsProperty> properties)
      Stores a collection of properties in a map, with the property names as keys.

      Parameters:
      properties - the properties to store in the map
      Returns:
      the map with the property names as keys and the property objects as values

    • wrapIfNull

      public static CmsProperty wrapIfNull(CmsProperty prop)
      Wraps a null value into a null property, and returns all other values unchanged.

      Parameters:
      prop - the value to wrap
      Returns:
      a wrapped null property, or the original prop if it wasn't null

    • 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 CmsProperty clone()
      Creates a clone of this property.

      Overrides:
      clone in class Object
      Returns:
      a clone of this property
      See Also:

    • 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(CmsProperty obj)
      Compares this property to another Object.

      Specified by:
      compareTo in interface Comparable<CmsProperty>
      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

    • equals

      public boolean equals(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 Object
      Parameters:
      obj - another object
      Returns:
      true, if the specified object is equal to this CmsProperty object
      See Also:

    • getName

      public String getName()
      Returns the name of this property.

      Returns:
      the name of this property

    • getOrigin

      public String getOrigin()
      Returns the root path of the resource from which the property was read.

      Returns:
      the root path of the resource from which the property was read

    • 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

    • getResourceValueList

      public List<String> 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 Map<String,String> 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 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 List<String> 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 Map<String,String> 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 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 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

    • getValueList

      public List<String> 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 List<String> getValueList(List<String> 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 Map<String,String> 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 Map<String,String> getValueMap(Map<String,String> 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 Object
      Returns:
      the hash code of the property
      See Also:

    • 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:

    • 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:

    • 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

    • setName

      public void setName(String name)
      Sets the name of this property.

      Parameters:
      name - the name to set

    • setOrigin

      public void setOrigin(String originRootPath)
      Sets the path of the resource from which the property was read.

      Parameters:
      originRootPath - the root path of the root path from which the property was read

    • 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

    • setResourceValueList

      public void setResourceValueList(List<String> 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(Map<String,String> 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(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(List<String> 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(Map<String,String> 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(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.

      Overrides:
      toString in class Object
      See Also: