001: /*
002: * Copyright 2006 Day Management AG, Switzerland. All rights reserved.
003: */
004: package javax.jcr.nodetype;
005:
006: import javax.jcr.Value;
007:
008: /**
009: * A property definition. Used in node type definitions.
010: *
011: */
012: public interface PropertyDefinition extends ItemDefinition {
013:
014: /**
015: * Gets the required type of the property. One of:
016: * <ul>
017: * <li><code>PropertyType.STRING</code></li>
018: * <li><code>PropertyType.DATE</code></li>
019: * <li><code>PropertyType.BINARY</code></li>
020: * <li><code>PropertyType.DOUBLE</code></li>
021: * <li><code>PropertyType.DECIMAL</code></li>
022: * <li><code>PropertyType.LONG</code></li>
023: * <li><code>PropertyType.BOOLEAN</code></li>
024: * <li><code>PropertyType.NAME</code></li>
025: * <li><code>PropertyType.PATH</code></li>
026: * <li><code>PropertyType.URI</code></li>
027: * <li><code>PropertyType.REFERENCE</code></li>
028: * <li><code>PropertyType.WEAKREFERENCE</code></li>
029: * <li><code>PropertyType.UNDEFINED</code></li>
030: * </ul>
031: * <code>PropertyType.UNDEFINED</code> is returned if this property
032: * may be of any type.
033: * <p/>
034: * In implementations that support node type registration,
035: * if this <code>PropertyDefinition</code> object is actually a
036: * newly-created empty <code>PropertyDefinitionTemplate</code>, then this method will
037: * return <code>PropertyType.STRING</code>.
038: *
039: * @return an <code>int</code> constant member of <code>PropertyType</code>.
040: */
041: public int getRequiredType();
042:
043: /**
044: * Gets the array of constraint strings. Each string in the array specifies
045: * a constraint on the value of the property. The constraints are OR-ed together,
046: * meaning that in order to be valid, the value must meet at least one of the
047: * constraints. For example, a constraint array of <code>["constraint1", "constraint2",
048: * "constraint3"]</code> has the interpretation: "the value of this property must
049: * meet at least one of <code>constraint1</code>, <code>constraint2 </code>or
050: * <code>constraint3</code>".
051: * <p>
052: * Reporting of value constraints is optional. An implementation may return
053: * <code>null</code>, indicating that value constraint information is unavailable
054: * (though a constraint may still exist).
055: * <p/>
056: * Returning an empty array, on the other hand, indicates that value constraint information
057: * is available and that no constraints are placed on this value.
058: * <p>
059: * In the case of multi-value properties, the constraint string array
060: * returned applies to all the values of the property.
061: * <p>
062: * The constraint strings themselves having differing formats and interpretations
063: * depending on the type of the property in question. The following describes the
064: * value constraint syntax for each property type:
065: * <ul>
066: * <li>
067: * <code>STRING</code> and <code>URI</code>: The constraint string is a
068: * regular expression pattern. For example the regular expression
069: * "<code>.*</code>" means "any string, including the empty string". Whereas
070: * a simple literal string (without any RE-specific meta-characters) like
071: * "<code>banana</code>" matches only the string "<code>banana</code>".
072: * </li>
073: * <li>
074: * <code>PATH</code>: The constraint string is a <i>JCR path</i> with an
075: * optional "<code>*</code>" character after the last "<code>/</code>"
076: * character. For example, possible constraint strings for a property of
077: * type <code>PATH</code> include:
078: * <ol>
079: * <li>
080: * "<code>/myapp:products/myapp:televisions</code>"
081: * </li>
082: * <li>
083: * "<code>/myapp:products/myapp:televisions/</code>"
084: * </li>
085: * <li>
086: * "<code>/myapp:products/*</code>"
087: * </li>
088: * <li>
089: * "<code>myapp:products/myapp:televisions</code>"
090: * </li>
091: * <li>
092: * "<code>../myapp:televisions</code>"
093: * </li>
094: * <li>
095: * "<code>../myapp:televisions/*</code>"
096: * </li>
097: * </ol>
098: * The following principles apply:
099: * <ul>
100: * <li>
101: * The "*" means "matches descendants" not "matches any subsequent path". For example,
102: * <code>/a/*</code> does not match <code>/a/../c</code>.
103: * The constraint must match the normalized path.
104: * </li>
105: * <li>
106: * Relative path constraint only match relative path values and absolute path
107: * constraints only match absolute path values.
108: * </li>
109: * <li>
110: * A trailing "<code>/</code>" has no effect (hence, <code>1</code> and <code>2</code>, above, are equivalent).
111: * </li>
112: * <li>
113: * The trailing "<code>*</code>" character means that the value of the <code>PATH</code> property is
114: * restricted to the indicated subtree (in other words any additional relative path
115: * can replace the "<code>*</code>"). For example, 3, above would allow
116: * <code>/myapp:products/myapp:radios</code>, <code>/myapp:products/myapp:microwaves/X900</code>, and so
117: * forth.
118: * </li>
119: * <li>
120: * A constraint without a "<code>*</code>" means that the <code>PATH</code> property is restricted to that
121: * precise path. For example, <code>1</code>, above, would allow only the value
122: * <code>/myapp:products/myapp:televisions</code>.
123: * </li>
124: * <li>
125: * The constraint can indicate either a relative path or an absolute path
126: * depending on whether it includes a leading "<code>/</code>" character. <code>1</code> and <code>4</code>, above for
127: * example, are distinct.
128: * </li>
129: * <li>
130: * The string returned must reflect the namespace mapping in the current <code>Session</code>
131: * (i.e., the current state of the namespace registry overlaid with any
132: * session-specific mappings). Constraint strings for <code>PATH</code> properties should be
133: * stored in fully-qualified form (using the actual URI instead of the prefix) and
134: * then be converted to prefix form according to the current mapping upon the
135: * <code>PropertyDefinition.getValueConstraints</code> call.
136: * </li>
137: * </ul>
138: * </li>
139: * <li>
140: * <code>NAME</code>: The constraint string is a <i>JCR name</i> in prefix form. For example
141: * "<code>myapp:products</code>". No wildcards or other pattern matching are supported. As with
142: * <code>PATH</code> properties, the string returned must reflect the namespace mapping in the
143: * current <code>Session</code>. Constraint strings for <code>NAME</code> properties should be stored in
144: * fully-qualified form (using the actual URI instead of the prefix) and then be
145: * converted to prefix form according to the current mapping.
146: * </li>
147: * <li>
148: * <code>REFERENCE</code> and <code>WEAKREFERENCE</code>: The constraint
149: * string is a <i>JCR name</i> in prefix form. This name is interpreted as a
150: * node type name and the <code>REFERENCE</code> or <code>WEAKREFERENCE</code>
151: * property is restricted to
152: * referring only to nodes that have at least the indicated node type. For
153: * example, a constraint of "<code>mytype:document</code>" would indicate
154: * that the property in question can only refer to nodes that have
155: * at least the node type <code>mytype:document</code> (assuming this was
156: * the only constraint returned in the array, recall that the array of
157: * constraints are to be ORed together). No wildcards or other pattern
158: * matching are supported. As with <code>PATH</code> properties, the string
159: * returned must reflect the namespace mapping in the current
160: * <code>Session</code>. Constraint strings for <code>REFERENCE</code>
161: * and <code>WEAKREFERENCE</code>
162: * properties should be stored by the implementaion in fully-qualified form (using the actual URI
163: * instead of the prefix) and then be converted to prefix form according to
164: * the current mapping.
165: * </li>
166: * <li>
167: * <code>BOOLEAN</code>: <code>BOOLEAN</code> properties will always report a value constraint consisting of an
168: * empty array (meaning no constraint). In implementations that support node type
169: * registration any value constraint set on <code>BOOLEAN</code> is ignored and discarded.
170: * </li>
171: * </ul>
172: * The remaining types all have value constraints in the form of inclusive or
173: * exclusive ranges: i.e., "<code>[min, max]</code>", "<code>(min, max)</code>",
174: * "<code>(min, max]</code>" or "<code>[min, max)</code>". Where "<code>[</code>"
175: * and "<code>]</code>" indicate "inclusive", while "<code>(</code>" and "<code>)</code>"
176: * indicate "exclusive". A missing <code>min</code> or <code>max</code> value
177: * indicates no bound in that direction. For example [,5] means no minimum but a
178: * maximum of 5 (inclusive) while [,] means simply that any value will suffice,
179: * The meaning of the <code>min</code> and <code>max</code> values themselves
180: * differ between types as follows:
181: * <ul>
182: * <li>
183: * <code>BINARY</code>: <code>min</code> and <code>max</code> specify the allowed
184: * size range of the binary value in bytes.
185: * </li>
186: * <li>
187: * <code>DATE</code>: <code>min</code> and <code>max</code> are dates specifying the
188: * allowed date range. The date strings must be in the ISO8601-compliant format:
189: * <code>YYYY-MM-DDThh:mm:ss.sssTZD</code>.
190: * </li>
191: * <li>
192: * <code>LONG</code>, <code>DOUBLE</code>: min and max are numbers.
193: * </li>
194: * </ul>
195: * In implementations that support node type registration, when specifying
196: * that a <code>DATE</code>, <code>LONG </code>or <code>DOUBLE </code>
197: * is constrained to be equal to some
198: * disjunctive set of constants, a string consisting of just the constant
199: * itself, "c" may be used as a shorthand for the standard constraint
200: * notation of "[c, c]", where c is the constant. For example, to indicate
201: * that particular LONG property is constrained to be one of the values 2,
202: * 4, or 8, the constraint string array {"2", "4", "8"} can be used instead
203: * of the standard notation, {"[2,2]", "[4,4]", "[8,8]"}. However, even if
204: * this shorthand is used on registration, the value returned by
205: * <code>PropertyDefinition.getValueConstraints()</code> will always use the standard
206: * notation.
207: * <p/>
208: * Because constraints are returned as an array of disjunctive constraints,
209: * in many cases the elements of the array can serve directly as a "choice list".
210: * This may, for example, be used by an application to display options to the
211: * end user indicating the set of permitted values.
212: * <p/>
213: * In implementations that support node type registration,
214: * if this <code>PropertyDefinition</code> object is actually a
215: * newly-created empty <code>PropertyDefinitionTemplate</code>, then this method will
216: * return <code>null</code>.
217: *
218: * @return a <code>String</code> array.
219: */
220: public String[] getValueConstraints();
221:
222: /**
223: * Gets the default value(s) of the property. These are the values
224: * that the property defined by this PropertyDefinition will be assigned if it
225: * is automatically created (that is, if {@link #isAutoCreated()}
226: * returns <code>true</code>).
227: * <p>
228: * This method returns an array of <code>Value</code> objects. If the property is
229: * multi-valued, then this array represents the full set of values
230: * that the property will be assigned upon being auto-created.
231: * Note that this could be the empty array. If the property is single-valued,
232: * then the array returned will be of size 1.
233: * <p/>
234: * If <code>null</code> is returned, then the property has no fixed default value.
235: * This does not exclude the possibility that the property still assumes some
236: * value automatically, but that value may be parameterized (for example,
237: * "the current date") and hence not expressable as a single fixed value.
238: * In particular, this <i>must</i> be the case if <code>isAutoCreated</code>
239: * returns <code>true</code> and this method returns <code>null</code>.
240: * <p/>
241: * Note that to indicate a <code>null</code> value for this attribute in a
242: * node type definition that is stored in content, the <code>jcr:defaultValues</code>
243: * property is simply removed (since <code>null</code> values for properties
244: * are not allowed.
245: * <p/>
246: * In implementations that support node type registration, if this
247: * <code>PropertyDefinition</code> object is actually a newly-created empty
248: * <code>PropertyDefinitionTemplate</code>, then this method will return
249: * <code>null</code>.
250: *
251: * @return an array of <code>Value</code> objects.
252: */
253: public Value[] getDefaultValues();
254:
255: /**
256: * Reports whether this property can have multiple values. Note that the
257: * <code>isMultiple</code> flag is special in that a given node type may
258: * have two property definitions that are identical in every respect except
259: * for the their <code>isMultiple</code> status. For example, a node type
260: * can specify two string properties both called <code>X</code>, one of
261: * which is multi-valued and the other not. An example of such a node type
262: * is <code>nt:unstructured</code>.
263: * <p/>
264: * In implementations that support node type registration, if this
265: * <code>PropertyDefinition</code> object is actually a newly-created empty
266: * <code>PropertyDefinitionTemplate</code>, then this method will return
267: * <code>false</code>.
268: *
269: * @return a <code>boolean</code>
270: */
271: public boolean isMultiple();
272: }
|