Class CmsProperty

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<CmsProperty>

    public class CmsProperty
    extends java.lang.Object
    implements java.io.Serializable, java.lang.Cloneable, java.lang.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:
    Serialized Form
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  CmsProperty.CmsPropertyLocaleTransformer
      Transforms a given properties map, to a map where the returned values for a property are dependent on the locale.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      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

      Constructors 
      Constructor Description
      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

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean autoCreatePropertyDefinition()
      Checks if the property definition for this property will be created implicitly on any write operation if doesn't already exist.
      CmsProperty clone()
      Creates a clone of this property.
      CmsProperty cloneAsProperty()
      Creates a clone of this property that already is of type CmsProperty.
      int compareTo​(CmsProperty obj)
      Compares this property to another Object.
      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<CmsProperty> list)
      Searches in a list for the first occurrence of a CmsProperty object with the given name.
      static java.lang.String getLocalizedKey​(java.util.Map<java.lang.String,​?> propertiesMap, java.lang.String key, java.util.Locale locale)
      Returns the key for the best matching local-specific property version.
      java.lang.String getName()
      Returns the name of this property.
      static CmsProperty getNullProperty()
      Returns the null property object.
      java.lang.String getOrigin()
      Returns the root path of the resource from which the property was read.
      static java.util.Map<java.lang.String,​CmsProperty> getPropertyMap​(java.util.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.
      java.lang.String getResourceValue()
      Returns the value of this property attached to the resource record.
      java.util.List<java.lang.String> getResourceValueList()
      Returns the value of this property attached to the resource record, split as a list.
      java.util.Map<java.lang.String,​java.lang.String> 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<java.lang.String> getStructureValueList()
      Returns the value of this property attached to the structure record, split as a list.
      java.util.Map<java.lang.String,​java.lang.String> 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<java.lang.String> getValueList()
      Returns the compound value of this property, split as a list.
      java.util.List<java.lang.String> getValueList​(java.util.List<java.lang.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.
      java.util.Map<java.lang.String,​java.lang.String> getValueMap()
      Returns the compound value of this property as a map.
      java.util.Map<java.lang.String,​java.lang.String> getValueMap​(java.util.Map<java.lang.String,​java.lang.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.
      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<CmsProperty> setAutoCreatePropertyDefinitions​(java.util.List<CmsProperty> 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<CmsProperty> setFrozen​(java.util.List<CmsProperty> list)
      Calls setFrozen(boolean) for each CmsProperty object in the given List if it is not already frozen.
      void setName​(java.lang.String name)
      Sets the name of this property.
      void setOrigin​(java.lang.String originRootPath)
      Sets the path of the resource from which the property was read.
      void setResourceValue​(java.lang.String resourceValue)
      Sets the value of this property attached to the resource record.
      void setResourceValueList​(java.util.List<java.lang.String> valueList)
      Sets the value of this property attached to the resource record from the given list of Strings.
      void setResourceValueMap​(java.util.Map<java.lang.String,​java.lang.String> 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<java.lang.String> valueList)
      Sets the value of this property attached to the structure record from the given list of Strings.
      void setStructureValueMap​(java.util.Map<java.lang.String,​java.lang.String> 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<CmsProperty> toList​(java.util.Map<java.lang.String,​java.lang.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.
      static java.util.Map<java.lang.String,​java.lang.String> toMap​(java.util.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).
      static java.util.Map<java.lang.String,​CmsProperty> toObjectMap​(java.lang.Iterable<CmsProperty> properties)
      Stores a collection of properties in a map, with the property names as keys.
      java.lang.String toString()
      Returns a string representation of this property object.
      static CmsProperty wrapIfNull​(CmsProperty prop)
      Wraps a null value into a null property, and returns all other values unchanged.
      • Methods inherited from class java.lang.Object

        finalize, getClass, notify, notifyAll, wait, wait, wait
    • 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<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
      • getLocalizedKey

        public static java.lang.String getLocalizedKey​(java.util.Map<java.lang.String,​?> propertiesMap,
                                                       java.lang.String key,
                                                       java.util.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 java.util.Map<java.lang.String,​CmsPropertygetPropertyMap​(java.util.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
      • toList

        public static java.util.List<CmsPropertytoList​(java.util.Map<java.lang.String,​java.lang.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 java.util.Map<java.lang.String,​java.lang.String> toMap​(java.util.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 java.util.Map<java.lang.String,​CmsPropertytoObjectMap​(java.lang.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 java.lang.Object
        Returns:
        a clone of this property
        See Also:
        cloneAsProperty()
      • compareTo

        public int compareTo​(CmsProperty obj)
        Compares this property to another Object.

        Specified by:
        compareTo in interface java.lang.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​(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)
      • getName

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

        Returns:
        the name of this property
      • getOrigin

        public java.lang.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 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<java.lang.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 java.util.Map<java.lang.String,​java.lang.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 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<java.lang.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 java.util.Map<java.lang.String,​java.lang.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 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<java.lang.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 java.util.List<java.lang.String> getValueList​(java.util.List<java.lang.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 java.util.Map<java.lang.String,​java.lang.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 java.util.Map<java.lang.String,​java.lang.String> getValueMap​(java.util.Map<java.lang.String,​java.lang.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 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
      • setName

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

        Parameters:
        name - the name to set
      • setOrigin

        public void setOrigin​(java.lang.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​(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<java.lang.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​(java.util.Map<java.lang.String,​java.lang.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​(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<java.lang.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​(java.util.Map<java.lang.String,​java.lang.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​(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()