KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > opencms > file > 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 JavaDoc;
38 import java.util.ArrayList JavaDoc;
39 import java.util.Collections JavaDoc;
40 import java.util.HashMap JavaDoc;
41 import java.util.Iterator JavaDoc;
42 import java.util.List JavaDoc;
43 import java.util.Map JavaDoc;
44 import java.util.RandomAccess JavaDoc;
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 JavaDoc, Cloneable JavaDoc, Comparable JavaDoc {
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 JavaDoc DELETE_VALUE = new String JavaDoc("");
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 JavaDoc TYPE_INDIVIDUAL = "individual";
132
133     /** Key used for a shared (resource) property value. */
134     public static final String JavaDoc 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 JavaDoc m_name;
156
157     /** The value of this property attached to the structure record. */
158     private String JavaDoc m_resourceValue;
159
160     /** The (optional) value list of this property attached to the structure record. */
161     private List JavaDoc m_resourceValueList;
162
163     /** The value of this property attached to the resource record. */
164     private String JavaDoc m_structureValue;
165
166     /** The (optional) value list of this property attached to the resource record. */
167     private List JavaDoc 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 JavaDoc name, String JavaDoc structureValue, String JavaDoc 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 JavaDoc name, String JavaDoc structureValue, String JavaDoc 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 JavaDoc name, List JavaDoc list) {
239
240         CmsProperty property = null;
241
242         // choose the fastest method to traverse the list
243
if (list instanceof RandomAccess JavaDoc) {
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 JavaDoc 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 JavaDoc setAutoCreatePropertyDefinitions(List JavaDoc list, boolean value) {
287
288         CmsProperty property;
289
290         // choose the fastest method to traverse the list
291
if (list instanceof RandomAccess JavaDoc) {
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 JavaDoc 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 JavaDoc setFrozen(List JavaDoc list) {
320
321         CmsProperty property;
322
323         // choose the fastest method to traverse the list
324
if (list instanceof RandomAccess JavaDoc) {
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 JavaDoc 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 JavaDoc toList(Map JavaDoc map) {
356
357         String JavaDoc name = null;
358         String JavaDoc value = null;
359         CmsProperty property = null;
360         List JavaDoc properties = null;
361         Object JavaDoc[] names = null;
362
363         if ((map == null) || (map.size() == 0)) {
364             return Collections.EMPTY_LIST;
365         }
366
367         properties = new ArrayList JavaDoc(map.size());
368         names = map.keySet().toArray();
369         for (int i = 0; i < names.length; i++) {
370             name = (String JavaDoc)names[i];
371             value = (String JavaDoc)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 JavaDoc toMap(List JavaDoc list) {
394
395         Map JavaDoc result = null;
396         String JavaDoc name = null;
397         String JavaDoc 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 JavaDoc();
405
406         // choose the fastest method to traverse the list
407
if (list instanceof RandomAccess JavaDoc) {
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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc getValue(String JavaDoc 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 JavaDoc 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 JavaDoc getValueList(List JavaDoc 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 JavaDoc strBuf = new StringBuffer JavaDoc();
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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc valueList) {
869
870         checkFrozen();
871         if (valueList != null) {
872             m_resourceValueList = new ArrayList JavaDoc(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 JavaDoc 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 JavaDoc valueList) {
902
903         checkFrozen();
904         if (valueList != null) {
905             m_structureValueList = new ArrayList JavaDoc(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 JavaDoc value, String JavaDoc 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 JavaDoc toString() {
944
945         StringBuffer JavaDoc strBuf = new StringBuffer JavaDoc();
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 JavaDoc createListFromValue(String JavaDoc 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 JavaDoc createValueFromList(List JavaDoc valueList) {
993
994         if (valueList == null) {
995             return null;
996         }
997         StringBuffer JavaDoc result = new StringBuffer JavaDoc(valueList.size() * 32);
998         Iterator JavaDoc 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}
Popular Tags