cmsproperty.java

cms是开源的框架

/*
 * File   : $Source: /usr/local/cvs/opencms/src/org/opencms/file/CmsProperty.java,v $
 * Date   : $Date: 2006/07/20 09:53:57 $
 * Version: $Revision: 1.35 $
 *
 * This library is part of OpenCms -
 * the Open Source Content Mananagement System
 *
 * Copyright (c) 2005 Alkacon Software GmbH (http://www.alkacon.com)
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * For further information about Alkacon Software GmbH, please see the
 * company website: http://www.alkacon.com
 *
 * For further information about OpenCms, please see the
 * project website: http://www.opencms.org
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

package org.opencms.file;

import org.opencms.main.CmsRuntimeException;
import org.opencms.util.CmsStringUtil;

import java.io.Serializable;
import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.RandomAccess;

/**
 * Represents a property (meta-information) mapped to a VFS resource.<p>
 * 
 * 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.<p>
 * 
 * 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 {@link #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.<p>
 * 
 * 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 {@link #STRUCTURE_RECORD_MAPPING} and {@link #RESOURCE_RECORD_MAPPING})
 * determines whether the value of the "PROPERTY_MAPPING_ID" attribute of the current row is
 * a structure or resource record ID.<p>
 * 
 * Property objects are written to the database using {@link org.opencms.file.CmsObject#writePropertyObject(String, CmsProperty)}
 * or {@link org.opencms.file.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 {@link #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).<p>
 * 
 * Use {@link #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 <code>false</code>. 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 {@link #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.<p>
 * 
 * @author Thomas Weckert  
 * 
 * @version $Revision: 1.35 $
 * 
 * @since 6.0.0 
 */
public class CmsProperty implements Serializable, Cloneable, Comparable {

    /**
     * Signals that the resource property values of a resource
     * should be deleted using deleteAllProperties.<p>
     */
    public static final int DELETE_OPTION_DELETE_RESOURCE_VALUES = 3;

    /**
     * Signals that both the structure and resource property values of a resource
     * should be deleted using deleteAllProperties.<p>
     */
    public static final int DELETE_OPTION_DELETE_STRUCTURE_AND_RESOURCE_VALUES = 1;

    /**
     * Signals that the structure property values of a resource
     * should be deleted using deleteAllProperties.<p>
     */
    public static final int DELETE_OPTION_DELETE_STRUCTURE_VALUES = 2;

    /**
     * An empty string to decide that a property value should be deleted when this
     * property object is written to the database.<p>
     */
    public static final String DELETE_VALUE = new String("");

    /**
     * Value of the "mapping-type" database attribute to indicate that a property value is mapped
     * to a resource record.<p>
     */
    public static final int RESOURCE_RECORD_MAPPING = 2;

    /**
     * Value of the "mapping-type" database attribute to indicate that a property value is mapped
     * to a structure record.<p>
     */
    public static final int STRUCTURE_RECORD_MAPPING = 1;

    /** Key used for a individual (structure) property value. */
    public static final String TYPE_INDIVIDUAL = "individual";

    /** Key used for a shared (resource) property value. */
    public static final String TYPE_SHARED = "shared";

    /** The delimiter value for separating values in a list, per default this is the <code>|</code> char. */
    public static final char VALUE_LIST_DELIMITER = '|';

    /** The null property object to be used in caches if a property is not found. */
    private static final CmsProperty NULL_PROPERTY = new CmsProperty();

    /** Serial version UID required for safe serialization. */
    private static final long serialVersionUID = 93613508924212782L;

    /**
     * Boolean flag to decide if the property definition for this property should be created 
     * implicitly on any write operation if doesn't exist already.<p>
     */
    private boolean m_autoCreatePropertyDefinition;

    /** Indicates if the property is frozen (required for <code>{@link #NULL_PROPERTY}</code>). */
    private boolean m_frozen;

    /** The name of this property. */
    private String m_name;

    /** The value of this property attached to the structure record. */
    private String m_resourceValue;

    /** The (optional) value list of this property attached to the structure record. */
    private List m_resourceValueList;

    /** The value of this property attached to the resource record. */
    private String m_structureValue;

    /** The (optional) value list of this property attached to the resource record. */
    private List m_structureValueList;

    /**
     * Creates a new CmsProperty object.<p>
     * 
     * The structure and resource property values are initialized to null. The structure and
     * resource IDs are initialized to {@link org.opencms.util.CmsUUID#getNullUUID()}.<p>
     */
    public CmsProperty() {

        // noting to do, all values will be initialized with "null" or <code>"false"</code> by default
    }

    /**
     * Creates a new CmsProperty object using the provided values.<p>
     *
     * If <code>null</code> is supplied for the resource or structure value, this 
     * value will not be available for this property.<p>
     *
     * If the property definition does not exist for the resource type it
     * is automatically created when this propery is written.
     * 
     * @param name the name of the property definition
     * @param structureValue the value to write as structure property, or <code>null</code>
     * @param resourceValue the value to write as resource property, or <code>null</code>
     */
    public CmsProperty(String name, String structureValue, String resourceValue) {

        this(name, structureValue, resourceValue, true);
    }

    /**
     * Creates a new CmsProperty object using the provided values.<p>
     * 
     * If <code>null</code> is supplied for the resource or structure value, this 
     * value will not be available for this property.<p>
     * 
     * @param name the name of the property definition
     * @param structureValue the value to write as structure property, or <code>null</code>
     * @param resourceValue the value to write as resource property , or <code>null</code>
     * @param autoCreatePropertyDefinition if <code>true</code>, the property definition for this property will be 
     *      created implicitly on any write operation if it doesn't exist already
     */
    public CmsProperty(String name, String structureValue, String resourceValue, boolean autoCreatePropertyDefinition) {

        m_name = name;
        m_structureValue = structureValue;
        m_resourceValue = resourceValue;
        m_autoCreatePropertyDefinition = autoCreatePropertyDefinition;
    }

    /**
     * Static initializer required for freezing the <code>{@link #NULL_PROPERTY}</code>.<p>
     */
    static {

        NULL_PROPERTY.m_frozen = true;
        NULL_PROPERTY.m_name = "";
    }

    /**
     * Searches in a list for the first occurence of a Cms property object with the given name.<p> 
     *
     * To check if the "null property" has been returned if a property was 
     * not found, use {@link #isNullProperty()} on the result.<p> 
     *
     * @param name a property name
     * @param list a list of Cms property objects
     * @return the index of the first occurrence of the name in they specified list, 
     *      or {@link CmsProperty#getNullProperty()} if the name is not found
     */
    public static final CmsProperty get(String name, List list) {

        CmsProperty property = null;

        // choose the fastest method to traverse the list
        if (list instanceof RandomAccess) {
            for (int i = 0, n = list.size(); i < n; i++) {
                property = (CmsProperty)list.get(i);
                if (property.m_name.equals(name)) {
                    return property;
                }
            }
        } else {
            Iterator i = list.iterator();
            while (i.hasNext()) {
                property = (CmsProperty)i.next();
                if (property.m_name.equals(name)) {
                    return property;
                }
            }
        }

        return NULL_PROPERTY;
    }

    /**
     * Returns the null property object.<p>
     * 
     * @return the null property object
     */
    public static final CmsProperty getNullProperty() {

        return NULL_PROPERTY;
    }

    /**
     * Calls <code>{@link #setAutoCreatePropertyDefinition(boolean)}</code> for each
     * property object in the given List with the given <code>value</code> parameter.<p>
     * 
     * This method will modify the objects in the input list directly.<p>
     * 
     * @param list a list of property objects
     * @param value boolean value
     * 
     * @return the modified list of properties
     * 
     * @see #setAutoCreatePropertyDefinition(boolean)
     */
    public static final List setAutoCreatePropertyDefinitions(List list, boolean value) {

        CmsProperty property;

        // choose the fastest method to traverse the list
        if (list instanceof RandomAccess) {
            for (int i = 0, n = list.size(); i < n; i++) {
                property = (CmsProperty)list.get(i);
                property.m_autoCreatePropertyDefinition = value;
            }
        } else {
            Iterator i = list.iterator();
            while (i.hasNext()) {
                property = (CmsProperty)i.next();
                property.m_autoCreatePropertyDefinition = value;
            }
        }

        return list;
    }

    /**
     * Calls <code>{@link #setFrozen(boolean)}</code> for each
     * property object in the given List if it is not already frozen.<p>
     * 
     * This method will modify the objects in the input list directly.<p>
     * 
     * @param list a list of property objects
     * 
     * @return the modified list of properties
     * 
     * @see #setFrozen(boolean)
     */
    public static final List setFrozen(List list) {

        CmsProperty property;

        // choose the fastest method to traverse the list
        if (list instanceof RandomAccess) {
            for (int i = 0, n = list.size(); i < n; i++) {
                property = (CmsProperty)list.get(i);
                if (!property.isFrozen()) {
                    property.setFrozen(true);
                }
            }
        } else {
            Iterator i = list.iterator();
            while (i.hasNext()) {
                property = (CmsProperty)i.next();
                if (!property.isFrozen()) {
                    property.setFrozen(true);