CmsProperty


1   /*
2    * File   : $Source: /usr/local/cvs/opencms/src/org/opencms/file/CmsProperty.java,v $
3    * Date   : $Date: 2006/07/20 09:53:57 $
4    * Version: $Revision: 1.35 $
5    *
6    * This library is part of OpenCms -
7    * the Open Source Content Mananagement System
8    *
9    * Copyright (c) 2005 Alkacon Software GmbH (http://www.alkacon.com)
10   *
11   * This library is free software; you can redistribute it and/or
12   * modify it under the terms of the GNU Lesser General Public
13   * License as published by the Free Software Foundation; either
14   * version 2.1 of the License, or (at your option) any later version.
15   *
16   * This library is distributed in the hope that it will be useful,
17   * but WITHOUT ANY WARRANTY; without even the implied warranty of
18   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19   * Lesser General Public License for more details.
20   *
21   * For further information about Alkacon Software GmbH, please see the
22   * company website: http://www.alkacon.com
23   *
24   * For further information about OpenCms, please see the
25   * project website: http://www.opencms.org
26   * 
27   * You should have received a copy of the GNU Lesser General Public
28   * License along with this library; if not, write to the Free Software
29   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
30   */
31  
32  package org.opencms.file;
33  
34  import org.opencms.main.CmsRuntimeException;
35  import org.opencms.util.CmsStringUtil;
36  
37  import java.io.Serializable  ;
38  import java.util.ArrayList  ;
39  import java.util.Collections  ;
40  import java.util.HashMap  ;
41  import java.util.Iterator  ;
42  import java.util.List  ;
43  import java.util.Map  ;
44  import java.util.RandomAccess  ;
45  
46  /**
47   * Represents a property (meta-information) mapped to a VFS resource.<p>
48   * 
49   * A property is an object that contains three string values: a name, a property value which is mapped
50   * to the structure record of a resource, and a property value which is mapped to the resource
51   * record of a resource. A property object is valid if it has both values or just one value set.
52   * Each property needs at least a name and one value set.<p>
53   * 
54   * A property value mapped to the structure record of a resource is significant for a single
55   * resource (sibling). A property value mapped to the resource record of a resource is significant
56   * for all siblings of a resource record. This is possible by getting the "compound value" 
57   * (see {@link #getValue()}) of a property in case a property object has both values set. The compound 
58   * value of a property object is the value mapped to the structure record, because it's structure 
59   * value is more significant than it's resource value. This allows to set a property only one time 
60   * on the resource record, and the property takes effect on all siblings of this resource record.<p>
61   * 
62   * The ID of the structure or resource record where a property value is mapped to is represented by 
63   * the "PROPERTY_MAPPING_ID" table attribute in the database. The "PROPERTY_MAPPING_TYPE" table 
64   * attribute (see {@link #STRUCTURE_RECORD_MAPPING} and {@link #RESOURCE_RECORD_MAPPING})
65   * determines whether the value of the "PROPERTY_MAPPING_ID" attribute of the current row is
66   * a structure or resource record ID.<p>
67   * 
68   * Property objects are written to the database using {@link org.opencms.file.CmsObject#writePropertyObject(String, CmsProperty)}
69   * or {@link org.opencms.file.CmsObject#writePropertyObjects(String, List)}, no matter
70   * whether you want to save a new (non-existing) property, update an existing property, or delete an
71   * existing property. To delete a property you would write a property object with either the
72   * structure and/or resource record values set to {@link #DELETE_VALUE} to indicate that a
73   * property value should be deleted in the database. Set property values to null if they should
74   * remain unchanged in the database when a property object is written. As for example you want to
75   * update just the structure value of a property, you would set the structure value to the new string,
76   * and the resource value to null (which is already the case by default).<p>
77   * 
78   * Use {@link #setAutoCreatePropertyDefinition(boolean)} to set a boolean flag whether a missing property
79   * definition should be created implicitly for a resource type when a property is written to the database.
80   * The default value for this flag is <code>false</code>. Thus, you receive a CmsException if you try
81   * to write a property of a resource with a resource type which lacks a property definition for
82   * this resource type. It is not a good style to set {@link #setAutoCreatePropertyDefinition(boolean)}
83   * on true to make writing properties to the database work in any case, because then you will loose
84   * control about which resource types support which property definitions.<p>
85   * 
86   * @author Thomas Weckert  
87   * 
88   * @version $Revision: 1.35 $
89   * 
90   * @since 6.0.0 
91   */
92  public class CmsProperty implements Serializable  , Cloneable  , Comparable   {
93  
94      /**
95       * Signals that the resource property values of a resource
96       * should be deleted using deleteAllProperties.<p>
97       */
98      public static final int DELETE_OPTION_DELETE_RESOURCE_VALUES = 3;
99  
100     /**
101      * Signals that both the structure and resource property values of a resource
102      * should be deleted using deleteAllProperties.<p>
103      */
104     public static final int DELETE_OPTION_DELETE_STRUCTURE_AND_RESOURCE_VALUES = 1;
105 
106     /**
107      * Signals that the structure property values of a resource
108      * should be deleted using deleteAllProperties.<p>
109      */
110     public static final int DELETE_OPTION_DELETE_STRUCTURE_VALUES = 2;
111 
112     /**
113      * An empty string to decide that a property value should be deleted when this
114      * property object is written to the database.<p>
115      */
116     public static final String   DELETE_VALUE = new String  ("");
117 
118     /**
119      * Value of the "mapping-type" database attribute to indicate that a property value is mapped
120      * to a resource record.<p>
121      */
122     public static final int RESOURCE_RECORD_MAPPING = 2;
123 
124     /**
125      * Value of the "mapping-type" database attribute to indicate that a property value is mapped
126      * to a structure record.<p>
127      */
128     public static final int STRUCTURE_RECORD_MAPPING = 1;
129 
130     /** Key used for a individual (structure) property value. */
131     public static final String   TYPE_INDIVIDUAL = "individual";
132 
133     /** Key used for a shared (resource) property value. */
134     public static final String   TYPE_SHARED = "shared";
135 
136     /** The delimiter value for separating values in a list, per default this is the <code>|</code> char. */
137     public static final char VALUE_LIST_DELIMITER = '|';
138 
139     /** The null property object to be used in caches if a property is not found. */
140     private static final CmsProperty NULL_PROPERTY = new CmsProperty();
141 
142     /** Serial version UID required for safe serialization. */
143     private static final long serialVersionUID = 93613508924212782L;
144 
145     /**
146      * Boolean flag to decide if the property definition for this property should be created 
147      * implicitly on any write operation if doesn't exist already.<p>
148      */
149     private boolean m_autoCreatePropertyDefinition;
150 
151     /** Indicates if the property is frozen (required for <code>{@link #NULL_PROPERTY}</code>). */
152     private boolean m_frozen;
153 
154     /** The name of this property. */
155     private String   m_name;
156 
157     /** The value of this property attached to the structure record. */
158     private String   m_resourceValue;
159 
160     /** The (optional) value list of this property attached to the structure record. */
161     private List   m_resourceValueList;
162 
163     /** The value of this property attached to the resource record. */
164     private String   m_structureValue;
165 
166     /** The (optional) value list of this property attached to the resource record. */
167     private List   m_structureValueList;
168 
169     /**
170      * Creates a new CmsProperty object.<p>
171      * 
172      * The structure and resource property values are initialized to null. The structure and
173      * resource IDs are initialized to {@link org.opencms.util.CmsUUID#getNullUUID()}.<p>
174      */
175     public CmsProperty() {
176 
177         // noting to do, all values will be initialized with "null" or <code>"false"</code> by default
178     }
179 
180     /**
181      * Creates a new CmsProperty object using the provided values.<p>
182      *
183      * If <code>null</code> is supplied for the resource or structure value, this 
184      * value will not be available for this property.<p>
185      *
186      * If the property definition does not exist for the resource type it
187      * is automatically created when this propery is written.
188      * 
189      * @param name the name of the property definition
190      * @param structureValue the value to write as structure property, or <code>null</code>
191      * @param resourceValue the value to write as resource property, or <code>null</code>
192      */
193     public CmsProperty(String   name, String   structureValue, String   resourceValue) {
194 
195         this(name, structureValue, resourceValue, true);
196     }
197 
198     /**
199      * Creates a new CmsProperty object using the provided values.<p>
200      * 
201      * If <code>null</code> is supplied for the resource or structure value, this 
202      * value will not be available for this property.<p>
203      * 
204      * @param name the name of the property definition
205      * @param structureValue the value to write as structure property, or <code>null</code>
206      * @param resourceValue the value to write as resource property , or <code>null</code>
207      * @param autoCreatePropertyDefinition if <code>true</code>, the property definition for this property will be 
208      *      created implicitly on any write operation if it doesn't exist already
209      */
210     public CmsProperty(String   name, String   structureValue, String   resourceValue, boolean autoCreatePropertyDefinition) {
211 
212         m_name = name;
213         m_structureValue = structureValue;
214         m_resourceValue = resourceValue;
215         m_autoCreatePropertyDefinition = autoCreatePropertyDefinition;
216     }
217 
218     /**
219      * Static initializer required for freezing the <code>{@link #NULL_PROPERTY}</code>.<p>
220      */
221     static {
222 
223         NULL_PROPERTY.m_frozen = true;
224         NULL_PROPERTY.m_name = "";
225     }
226 
227     /**
228      * Searches in a list for the first occurence of a Cms property object with the given name.<p> 
229      *
230      * To check if the "null property" has been returned if a property was 
231      * not found, use {@link #isNullProperty()} on the result.<p> 
232      *
233      * @param name a property name
234      * @param list a list of Cms property objects
235      * @return the index of the first occurrence of the name in they specified list, 
236      *      or {@link CmsProperty#getNullProperty()} if the name is not found
237      */
238     public static final CmsProperty get(String   name, List   list) {
239 
240         CmsProperty property = null;
241 
242         // choose the fastest method to traverse the list
243         if (list instanceof RandomAccess  ) {
244             for (int i = 0, n = list.size(); i < n; i++) {
245                 property = (CmsProperty)list.get(i);
246                 if (property.m_name.equals(name)) {
247                     return property;
248                 }
249             }
250         } else {
251             Iterator   i = list.iterator();
252             while (i.hasNext()) {
253                 property = (CmsProperty)i.next();
254                 if (property.m_name.equals(name)) {
255                     return property;
256                 }
257             }
258         }
259 
260         return NULL_PROPERTY;
261     }
262 
263     /**
264      * Returns the null property object.<p>
265      * 
266      * @return the null property object
267      */
268     public static final CmsProperty getNullProperty() {
269 
270         return NULL_PROPERTY;
271     }
272 
273     /**
274      * Calls <code>{@link #setAutoCreatePropertyDefinition(boolean)}</code> for each
275      * property object in the given List with the given <code>value</code> parameter.<p>
276      * 
277      * This method will modify the objects in the input list directly.<p>
278      * 
279      * @param list a list of property objects
280      * @param value boolean value
281      * 
282      * @return the modified list of properties
283      * 
284      * @see #setAutoCreatePropertyDefinition(boolean)
285      */
286     public static final List   setAutoCreatePropertyDefinitions(List   list, boolean value) {
287 
288         CmsProperty property;
289 
290         // choose the fastest method to traverse the list
291         if (list instanceof RandomAccess  ) {
292             for (int i = 0, n = list.size(); i < n; i++) {
293                 property = (CmsProperty)list.get(i);
294                 property.m_autoCreatePropertyDefinition = value;
295             }
296         } else {
297             Iterator   i = list.iterator();
298             while (i.hasNext()) {
299                 property = (CmsProperty)i.next();
300                 property.m_autoCreatePropertyDefinition = value;
301             }
302         }
303 
304         return list;
305     }
306 
307     /**
308      * Calls <code>{@link #setFrozen(boolean)}</code> for each
309      * property object in the given List if it is not already frozen.<p>
310      * 
311      * This method will modify the objects in the input list directly.<p>
312      * 
313      * @param list a list of property objects
314      * 
315      * @return the modified list of properties
316      * 
317      * @see #setFrozen(boolean)
318      */
319     public static final List   setFrozen(List   list) {
320 
321         CmsProperty property;
322 
323         // choose the fastest method to traverse the list
324         if (list instanceof RandomAccess  ) {
325             for (int i = 0, n = list.size(); i < n; i++) {
326                 property = (CmsProperty)list.get(i);
327                 if (!property.isFrozen()) {
328                     property.setFrozen(true);
329                 }
330             }
331         } else {
332             Iterator   i = list.iterator();
333             while (i.hasNext()) {
334                 property = (CmsProperty)i.next();
335                 if (!property.isFrozen()) {
336                     property.setFrozen(true);
337                 }
338             }
339         }
340 
341         return list;
342     }
343 
344     /**
345      * Transforms a map with compound (String) values keyed by property names into a list of 
346      * CmsProperty objects with structure values.<p>
347      * 
348      * This method is to prevent issues with backward incompatibilities in older code.
349      * Use this method with caution, it might be removed without with being deprecated
350      * before.<p>
351      * 
352      * @param map a map with compound (String) values keyed by property names
353      * @return a list of CmsProperty objects
354      */
355     public static List   toList(Map   map) {
356 
357         String   name = null;
358         String   value = null;
359         CmsProperty property = null;
360         List   properties = null;
361         Object  [] names = null;
362 
363         if ((map == null) || (map.size() == 0)) {
364             return Collections.EMPTY_LIST;
365         }
366 
367         properties = new ArrayList  (map.size());
368         names = map.keySet().toArray();
369         for (int i = 0; i < names.length; i++) {
370             name = (String  )names[i];
371             value = (String  )map.get(name);
372 
373             property = new CmsProperty();
374             property.m_name = name;
375             property.m_structureValue = value;
376             properties.add(property);
377         }
378 
379         return properties;
380     }
381 
382     /**
383      * Transforms a list of CmsProperty objects with structure and resource values into a map with
384      * compound (String) values keyed by property names.<p>
385      *
386      * This method is to prevent issues with backward incompatibilities in older code.
387      * Use this method with caution, it might be removed without with being deprecated
388      * before.<p>
389      * 
390      * @param list a list of CmsProperty objects
391      * @return a map with compound (String) values keyed by property names
392      */
393     public static Map   toMap(List   list) {
394 
395         Map   result = null;
396         String   name = null;
397         String   value = null;
398         CmsProperty property = null;
399 
400         if ((list == null) || (list.size() == 0)) {
401             return Collections.EMPTY_MAP;
402         }
403 
404         result = new HashMap  ();
405 
406         // choose the fastest method to traverse the list
407         if (list instanceof RandomAccess  ) {
408             for (int i = 0, n = list.size(); i < n; i++) {
409                 property = (CmsProperty)list.get(i);
410                 name = property.m_name;
411                 value = property.getValue();
412                 result.put(name, value);
413             }
414         } else {
415             Iterator   i = list.iterator();
416             while (i.hasNext()) {
417                 property = (CmsProperty)i.next();
418                 name = property.m_name;
419                 value = property.getValue();
420                 result.put(name, value);
421             }
422         }
423 
424         return result;
425     }
426 
427     /**
428      * Checks if the property definition for this property will be 
429      * created implicitly on any write operation if doesn't already exist.<p>
430      * 
431      * @return <code>true</code>, if the property definition for this property will be created implicitly on any write operation
432      */
433     public boolean autoCreatePropertyDefinition() {
434 
435         return m_autoCreatePropertyDefinition;
436     }
437 
438     /**
439      * Creates a clone of this property.<p>
440      *  
441      * @return a clone of this property
442      * 
443      * @see #cloneAsProperty()
444      */
445     public Object   clone() {
446 
447         return cloneAsProperty();
448     }
449 
450     /**
451      * Creates a clone of this property that already is of type <code>{@link CmsProperty}</code>.<p>
452      * 
453      * The cloned property will not be frozen.<p>
454      * 
455      * @return a clone of this property that already is of type <code>{@link CmsProperty}</code>
456      */
457     public CmsProperty cloneAsProperty() {
458 
459         if (this == NULL_PROPERTY) {
460             // null property must never be cloned
461             return NULL_PROPERTY;
462         }
463 
464         CmsProperty clone = new CmsProperty();
465 
466         clone.m_name = m_name;
467         clone.m_structureValue = m_structureValue;
468         clone.m_structureValueList = m_structureValueList;
469         clone.m_resourceValue = m_resourceValue;
470         clone.m_resourceValueList = m_resourceValueList;
471         clone.m_autoCreatePropertyDefinition = m_autoCreatePropertyDefinition;
472         // the value for m_frozen does not need to be set as it is false by default
473 
474         return clone;
475     }
476 
477     /**
478      * Compares this property to another Object.<p>
479      * 
480      * @param obj the other object to be compared
481      * @return if the argument is a property object, returns zero if the name of the argument is equal to the name of this property object, 
482      *      a value less than zero if the name of this property is lexicographically less than the name of the argument, 
483      *      or a value greater than zero if the name of this property is lexicographically greater than the name of the argument 
484      */
485     public int compareTo(Object   obj) {
486 
487         if (obj == this) {
488             return 0;
489         }
490         if (obj instanceof CmsProperty) {
491             return m_name.compareTo(((CmsProperty)obj).m_name);
492         }
493         return 0;
494     }
495 
496     /**
497      * Checks if the resource value of this property should be deleted when this
498      * property object is written to the database.<p>
499      * 
500      * @return true, if the resource value of this property should be deleted
501      * 
502      * @deprecated use <code>{@link #isDeleteResourceValue()}</code> instead
503      */
504     public boolean deleteResourceValue() {
505 
506         return isDeleteResourceValue();
507     }
508 
509     /**
510      * Checks if the structure value of this property should be deleted when this
511      * property object is written to the database.<p>
512      * 
513      * @return true, if the structure value of this property should be deleted
514      * 
515      * @deprecated use <code>{@link #isDeleteStructureValue()}</code> instead
516      */
517     public boolean deleteStructureValue() {
518 
519         return isDeleteStructureValue();
520     }
521 
522     /**
523      * Tests if a specified object is equal to this CmsProperty object.<p>
524      * 
525      * Two property objecs are equal if their names are equal.<p>
526      * 
527      * @param obj another object
528      * @return true, if the specified object is equal to this CmsProperty object
529      */
530     public boolean equals(Object   obj) {
531 
532         if (obj == this) {
533             return true;
534         }
535         if (obj instanceof CmsProperty) {
536             return ((CmsProperty)obj).m_name.equals(m_name);
537         }
538         return false;
539     }
540 
541     /**
542      * Returns the name of this property.<p>
543      * 
544      * @return name of this property
545      * 
546      * @deprecated use {@link #getName()} instead
547      */
548     public String   getKey() {
549 
550         return getName();
551     }
552 
553     /**
554      * Returns the name of this property.<p>
555      * 
556      * @return the name of this property
557      */
558     public String   getName() {
559 
560         return m_name;
561     }
562 
563     /**
564      * Returns the value of this property attached to the resource record.<p>
565      * 
566      * @return the value of this property attached to the resource record
567      */
568     public String   getResourceValue() {
569 
570         return m_resourceValue;
571     }
572 
573     /**
574      * Returns the value of this property attached to the resource record, split as a list.<p>
575      * 
576      * This list is build form the resource value, which is split into separate values
577      * using the <code>|</code> char as delimiter. If the delimiter is not found,
578      * then the list will contain one entry which is equal to <code>{@link #getResourceValue()}</code>.<p>
579      * 
580      * @return the value of this property attached to the resource record, split as a (unmodifiable) list of Strings
581      */
582     public List   getResourceValueList() {
583 
584         if ((m_resourceValueList == null) && (m_resourceValue != null)) {
585             // use lazy initializing of the list
586             m_resourceValueList = createListFromValue(m_resourceValue);
587             m_resourceValueList = Collections.unmodifiableList(m_resourceValueList);
588         }
589         return m_resourceValueList;
590     }
591 
592     /**
593      * Returns the value of this property attached to the structure record.<p>
594      * 
595      * @return the value of this property attached to the structure record
596      */
597     public String   getStructureValue() {
598 
599         return m_structureValue;
600     }
601 
602     /**
603      * Returns the value of this property attached to the structure record, split as a list.<p>
604      * 
605      * This list is build form the structure value, which is split into separate values
606      * using the <code>|</code> char as delimiter. If the delimiter is not found,
607      * then the list will contain one entry which is equal to <code>{@link #getStructureValue()}</code>.<p>
608      * 
609      * @return the value of this property attached to the structure record, split as a (unmodifiable) list of Strings
610      */
611     public List   getStructureValueList() {
612 
613         if ((m_structureValueList == null) && (m_structureValue != null)) {
614             // use lazy initializing of the list
615             m_structureValueList = createListFromValue(m_structureValue);
616             m_structureValueList = Collections.unmodifiableList(m_structureValueList);
617         }
618         return m_structureValueList;
619     }
620 
621     /**
622      * Returns the compound value of this property.<p>
623      * 
624      * The value returned is the value of {@link #getStructureValue()}, if it is not <code>null</code>.
625      * Otherwise the value if {@link #getResourceValue()} is returned (which may also be <code>null</code>).<p>
626      * 
627      * @return the compound value of this property
628      */
629     public String   getValue() {
630 
631         return (m_structureValue != null) ? m_structureValue : m_resourceValue;
632     }
633 
634     /**
635      * Returns the compound value of this property, or a specified default value,
636      * if both the structure and resource values are null.<p>
637      * 
638      * In other words, this method returns the defaultValue if this property object 
639      * is the null property (see {@link CmsProperty#getNullProperty()}).<p>
640      * 
641      * @param defaultValue a default value which is returned if both the structure and resource values are <code>null</code>
642      * 
643      * @return the compound value of this property, or the default value
644      */
645     public String   getValue(String   defaultValue) {
646 
647         if (this == CmsProperty.NULL_PROPERTY) {
648             // return the default value if this property is the null property
649             return defaultValue;
650         }
651 
652         // somebody might have set both values to null manually
653         // on a property object different from the null property...
654         return (m_structureValue != null) ? m_structureValue : ((m_resourceValue != null) ? m_resourceValue
655         : defaultValue);
656     }
657 
658     /**
659      * Returns the compound value of this property, split as a list.<p>
660      * 
661      * This list is build form the used value, which is split into separate values
662      * using the <code>|</code> char as delimiter. If the delimiter is not found,
663      * then the list will contain one entry.<p>
664      * 
665      * The value returned is the value of {@link #getStructureValueList()}, if it is not <code>null</code>.
666      * Otherwise the value if {@link #getResourceValueList()} is returned (which may also be <code>null</code>).<p>
667      * 
668      * @return the compound value of this property, split as a (unmodifiable) list of Strings
669      */
670     public List   getValueList() {
671 
672         return (m_structureValue != null) ? getStructureValueList() : getResourceValueList();
673     }
674 
675     /**
676      * Returns the compound value of this property, split as a list, or a specified default value list,
677      * if both the structure and resource values are null.<p>
678      * 
679      * In other words, this method returns the defaultValue if this property object 
680      * is the null property (see {@link CmsProperty#getNullProperty()}).<p>
681      * 
682      * @param defaultValue a default value list which is returned if both the structure and resource values are <code>null</code>
683      * 
684      * @return the compound value of this property, split as a (unmodifiable) list of Strings
685      */
686     public List   getValueList(List   defaultValue) {
687 
688         if (this == CmsProperty.NULL_PROPERTY) {
689             // return the default value if this property is the null property
690             return defaultValue;
691         }
692 
693         // somebody might have set both values to null manually
694         // on a property object different from the null property...
695         return (m_structureValue != null) ? getStructureValueList()
696         : ((m_resourceValue != null) ? getResourceValueList() : defaultValue);
697     }
698 
699     /**
700      * @see java.lang.Object#hashCode()
701      */
702     public int hashCode() {
703 
704         StringBuffer   strBuf = new StringBuffer  ();
705 
706         strBuf.append(m_name);
707         strBuf.append("_");
708         strBuf.append(m_structureValue);
709         strBuf.append("_");
710         strBuf.append(m_resourceValue);
711 
712         return strBuf.toString().hashCode();
713     }
714 
715     /**
716      * Checks if the resource value of this property should be deleted when this
717      * property object is written to the database.<p>
718      * 
719      * @return true, if the resource value of this property should be deleted
720      * @see CmsProperty#DELETE_VALUE
721      */
722     public boolean isDeleteResourceValue() {
723 
724         return (m_resourceValue == DELETE_VALUE) || ((m_resourceValue != null) && (m_resourceValue.length() == 0));
725     }
726 
727     /**
728      * Checks if the structure value of this property should be deleted when this
729      * property object is written to the database.<p>
730      * 
731      * @return true, if the structure value of this property should be deleted
732      * @see CmsProperty#DELETE_VALUE
733      */
734     public boolean isDeleteStructureValue() {
735 
736         return (m_structureValue == DELETE_VALUE) || ((m_structureValue != null) && (m_structureValue.length() == 0));
737     }
738 
739     /**
740      * Returns <code>true</code> if this property is frozen, that is read only.<p>
741      *
742      * @return <code>true</code> if this property is frozen, that is read only
743      */
744     public boolean isFrozen() {
745 
746         return m_frozen;
747     }
748 
749     /**
750      * Tests if a given CmsProperty is identical to this CmsProperty object.<p>
751      * 
752      * The property object are identical if their name, structure and 
753      * resource values are all equals.<p>
754      * 
755      * @param property another property object
756      * @return true, if the specified object is equal to this CmsProperty object
757      */
758     public boolean isIdentical(CmsProperty property) {
759 
760         boolean isEqual;
761 
762         // compare the name
763         if (m_name == null) {
764             isEqual = (property.getName() == null);
765         } else {
766             isEqual = m_name.equals(property.getName());
767         }
768 
769         // compare the structure value
770         if (m_structureValue == null) {
771             isEqual &= (property.getStructureValue() == null);
772         } else {
773             isEqual &= m_structureValue.equals(property.getStructureValue());
774         }
775 
776         // compare the resource value
777         if (m_resourceValue == null) {
778             isEqual &= (property.getResourceValue() == null);
779         } else {
780             isEqual &= m_resourceValue.equals(property.getResourceValue());
781         }
782 
783         return isEqual;
784     }
785 
786     /**
787      * Checks if this property object is the null property object.<p>
788      * 
789      * @return true if this property object is the null property object
790      */
791     public boolean isNullProperty() {
792 
793         return NULL_PROPERTY.equals(this);
794     }
795 
796     /**
797      * Sets the boolean flag to decide if the property definition for this property should be 
798      * created implicitly on any write operation if doesn't exist already.<p>
799      * 
800      * @param value true, if the property definition for this property should be created implicitly on any write operation
801      */
802     public void setAutoCreatePropertyDefinition(boolean value) {
803 
804         checkFrozen();
805         m_autoCreatePropertyDefinition = value;
806     }
807 
808     /**
809      * Sets the frozen state of the property, if set to <code>true</code> then this property is read only.<p>
810      *
811      * If the property is already frozen, then setting the frozen state to <code>true</code> again is allowed, 
812      * but seeting the value to <code>false</code> causes a <code>{@link CmsRuntimeException}</code>.<p>
813      *
814      * @param frozen the frozen state to set
815      */
816     public void setFrozen(boolean frozen) {
817 
818         if (!frozen) {
819             checkFrozen();
820         }
821         m_frozen = frozen;
822     }
823 
824     /**
825      * Sets the name of this property.<p>
826      * 
827      * @param name the name of this property
828      * 
829      * @deprecated use {@link #setName(String)} instead
830      */
831     public void setKey(String   name) {
832 
833         checkFrozen();
834         setName(name);
835     }
836 
837     /**
838      * Sets the name of this property.<p>
839      * 
840      * @param name the name to set
841      */
842     public void setName(String   name) {
843 
844         checkFrozen();
845         m_name = name;
846     }
847 
848     /**
849      * Sets the value of this property attached to the resource record.<p>
850      * 
851      * @param resourceValue the value of this property attached to the resource record
852      */
853     public void setResourceValue(String   resourceValue) {
854 
855         checkFrozen();
856         m_resourceValue = resourceValue;
857         m_resourceValueList = null;
858     }
859 
860     /**
861      * Sets the value of this property attached to the resource record form the given list of Strings.<p>
862      * 
863      * The value will be created form the individual values of the given list, which are appended
864      * using the <code>|</code> char as delimiter.<p>
865      * 
866      * @param valueList the list of value (Strings) to attach to the resource record
867      */
868     public void setResourceValueList(List   valueList) {
869 
870         checkFrozen();
871         if (valueList != null) {
872             m_resourceValueList = new ArrayList  (valueList);
873             m_resourceValueList = Collections.unmodifiableList(m_resourceValueList);
874             m_resourceValue = createValueFromList(m_resourceValueList);
875         } else {
876             m_resourceValueList = null;
877             m_resourceValue = null;
878         }
879     }
880 
881     /**
882      * Sets the value of this property attached to the structure record.<p>
883      * 
884      * @param structureValue the value of this property attached to the structure record
885      */
886     public void setStructureValue(String   structureValue) {
887 
888         checkFrozen();
889         m_structureValue = structureValue;
890         m_structureValueList = null;
891     }
892 
893     /**
894      * Sets the value of this property attached to the structure record form the given list of Strings.<p>
895      * 
896      * The value will be created form the individual values of the given list, which are appended
897      * using the <code>|</code> char as delimiter.<p>
898      * 
899      * @param valueList the list of value (Strings) to attach to the structure record
900      */
901     public void setStructureValueList(List   valueList) {
902 
903         checkFrozen();
904         if (valueList != null) {
905             m_structureValueList = new ArrayList  (valueList);
906             m_structureValueList = Collections.unmodifiableList(m_structureValueList);
907             m_structureValue = createValueFromList(m_structureValueList);
908         } else {
909             m_structureValueList = null;
910             m_structureValue = null;
911         }
912     }
913 
914     /**
915      * Sets the value of this property as either shared or 
916      * individual value.<p>
917      * 
918      * If the given type equals {@link CmsProperty#TYPE_SHARED} then
919      * the value is set as a shared (resource) value, otherwise it
920      * is set as individual (structure) value.<p>
921      * 
922      * @param value the value to set
923      * @param type the value type to set
924      */
925     public void setValue(String   value, String   type) {
926 
927         checkFrozen();
928         setAutoCreatePropertyDefinition(true);
929         if (TYPE_SHARED.equalsIgnoreCase(type)) {
930             // set the provided value as shared (resource) value
931             setResourceValue(value);
932         } else {
933             // set the provided value as individual (structure) value
934             setStructureValue(value);
935         }
936     }
937 
938     /**
939      * Returns a string representation of this property object.<p>
940      * 
941      * @see java.lang.Object#toString()
942      */
943     public String   toString() {
944 
945         StringBuffer   strBuf = new StringBuffer  ();
946 
947         strBuf.append("[").append(getClass().getName()).append(": ");
948         strBuf.append("name: '").append(m_name).append("'");
949         strBuf.append(", value: '").append(getValue()).append("'");
950         strBuf.append(", structure value: '").append(m_structureValue).append("'");
951         strBuf.append(", resource value: '").append(m_resourceValue).append("'");
952         strBuf.append(", frozen: ").append(m_frozen);
953         strBuf.append("]");
954 
955         return strBuf.toString();
956     }
957 
958     /**
959      * Checks if this property is frozen, that is read only.<p> 
960      */
961     private void checkFrozen() {
962 
963         if (m_frozen) {
964             throw new CmsRuntimeException(Messages.get().container(Messages.ERR_PROPERTY_FROZEN_1, toString()));
965         }
966     }
967 
968     /**
969      * Returns the list value representation for the given String.<p>
970      * 
971      * The given value is split along the <code>|</code> char.<p>
972      * 
973      * @param value the value list to create the list representation for
974      * 
975      * @return the list value representation for the given String
976      */
977     private List   createListFromValue(String   value) {
978 
979         if (value == null) {
980             return null;
981         }
982         return CmsStringUtil.splitAsList(value, VALUE_LIST_DELIMITER);
983     }
984 
985     /**
986      * Returns the single String value representation for the given value list.<p>
987      * 
988      * @param valueList the value list to create the single String value for
989      * 
990      * @return the single String value representation for the given value list
991      */
992     private String   createValueFromList(List   valueList) {
993 
994         if (valueList == null) {
995             return null;
996         }
997         StringBuffer   result = new StringBuffer  (valueList.size() * 32);
998         Iterator   i = valueList.iterator();
999         while (i.hasNext()) {
1000            result.append(i.next().toString());
1001            if (i.hasNext()) {
1002                result.append(VALUE_LIST_DELIMITER);
1003            }
1004        }
1005        return result.toString();
1006    }
1007}
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags