001: /*
002: * Copyright 2006 Day Management AG, Switzerland. All rights reserved.
003: */
004: package javax.jcr;
005:
006: import javax.jcr.nodetype.PropertyDefinition;
007: import javax.jcr.nodetype.ConstraintViolationException;
008: import javax.jcr.version.VersionException;
009: import javax.jcr.lock.LockException;
010: import java.io.InputStream;
011: import java.util.Calendar;
012: import java.math.BigDecimal;
013:
014: /**
015: * A <code>Property</code> object represents the smallest granularity of content
016: * storage. It has a single parent node and no children. A property consists of a
017: * name and a value, or in the case of multi-value properties, a set of values
018: * all of the same type. See <code>{@link Value}</code>.
019: */
020: public interface Property extends Item {
021:
022: /**
023: * Sets the value of this property to <code>value</code>.
024: * If this property's property type is not constrained by the node type of
025: * its parent node, then the property type is changed to that of the supplied
026: * <code>value</code>. If the property type is constrained, then a
027: * best-effort conversion is attempted. If conversion fails, a
028: * <code>ValueFormatException</code> is thrown immediately (not on <code>save</code>).
029: * The change will be persisted (if valid) on <code>save</code>
030: * <p/>
031: * A <code>ConstraintViolationException</code> will be thrown either immediately
032: * or on <code>save</code>, if the change would violate a node type or implementation-specific constraint.
033: * Implementations may differ on when this validation is performed.
034: * <p/>
035: * A <code>VersionException</code> will be thrown either immediately
036: * or on <code>save</code>, if this property belongs to a node that is versionable and
037: * checked-in or is non-versionable but whose nearest versionable ancestor is checked-in.
038: * Implementations may differ on when this validation is performed.
039: * <p/>
040: * A <code>LockException</code> will be thrown either immediately
041: * or on <code>save</code>, if a lock prevents the setting of the value.
042: * Implementations may differ on when this validation is performed.
043: *
044: * @param value The new value to set the property to.
045: * @throws ValueFormatException if the type or format of the specified value
046: * is incompatible with the type of this property.
047: * @throws VersionException if this property belongs to a node that is versionable and checked-in
048: * or is non-versionable but whose nearest versionable ancestor is checked-in and this
049: * implementation performs this validation immediately instead of waiting until <code>save</code>.
050: * @throws LockException if a lock prevents the setting of the value and this
051: * implementation performs this validation immediately instead of waiting until <code>save</code>.
052: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
053: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
054: * @throws RepositoryException if another error occurs.
055: */
056: public void setValue(Value value) throws ValueFormatException,
057: VersionException, LockException,
058: ConstraintViolationException, RepositoryException;
059:
060: /**
061: * Sets the value of this property to the <code>values</code> array.
062: * If this property's property type is not constrained by the node type of
063: * its parent node, then the property type is changed to that of the supplied
064: * <code>values</code>. If the property type is constrained, then a
065: * best-effort conversion is attempted. If conversion fails, a
066: * <code>ValueFormatException</code> is thrown immediately (not on <code>save</code>).
067: * If this property is not a multi-valued then a <code>ValueFormatException</code> is
068: * thrown immediately. The change will be persisted (if valid) on <code>save</code>.
069: * <p/>
070: * A <code>ConstraintViolationException</code> will be thrown either immediately
071: * or on <code>save</code>, if the change would violate a node type or implementation-specific constraint.
072: * Implementations may differ on when this validation is performed.
073: * <p/>
074: * A <code>VersionException</code> will be thrown either immediately
075: * or on <code>save</code>, if this property belongs to a node that is versionable and
076: * checked-in or is non-versionable but whose nearest versionable ancestor is checked-in.
077: * Implementations may differ on when this validation is performed.
078: * <p/>
079: * A <code>LockException</code> will be thrown either immediately
080: * or on <code>save</code>, if a lock prevents the setting of the value.
081: * Implementations may differ on when this validation is performed.
082: *
083: * @param values The new values to set the property to.
084: * @throws ValueFormatException if the type or format of the specified values
085: * is incompatible with the type of this property.
086: * @throws VersionException if this property belongs to a node that is versionable and checked-in
087: * or is non-versionable but whose nearest versionable ancestor is checked-in and this
088: * implementation performs this validation immediately instead of waiting until <code>save</code>.
089: * @throws LockException if a lock prevents the setting of the value and this
090: * implementation performs this validation immediately instead of waiting until <code>save</code>.
091: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
092: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
093: * @throws RepositoryException if another error occurs.
094: */
095: public void setValue(Value[] values) throws ValueFormatException,
096: VersionException, LockException,
097: ConstraintViolationException, RepositoryException;
098:
099: /**
100: * Sets the value of this property to <code>value</code>.
101: * Same as <code>{@link #setValue(Value value)}</code> except that the
102: * value is specified as a <code>String</code>.
103: *
104: * @param value The new value to set the property to.
105: * @throws ValueFormatException if the type or format of the specified value
106: * is incompatible with the type of this property.
107: * @throws VersionException if this property belongs to a node that is versionable and checked-in
108: * or is non-versionable but whose nearest versionable ancestor is checked-in and this
109: * implementation performs this validation immediately instead of waiting until <code>save</code>.
110: * @throws LockException if a lock prevents the setting of the value and this
111: * implementation performs this validation immediately instead of waiting until <code>save</code>.
112: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
113: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
114: * @throws RepositoryException if another error occurs.
115: */
116: public void setValue(String value) throws ValueFormatException,
117: VersionException, LockException,
118: ConstraintViolationException, RepositoryException;
119:
120: /**
121: * Sets the value of this property to the <code>values</code> array.
122: * Same as <code>{@link #setValue(Value[] values)}</code> except that the
123: * values are specified as a <code>String[]</code>.
124: *
125: * @param values The new values to set the property to.
126: * @throws ValueFormatException if the type or format of the specified values
127: * is incompatible with the type of this property.
128: * @throws VersionException if this property belongs to a node that is versionable and checked-in
129: * or is non-versionable but whose nearest versionable ancestor is checked-in and this
130: * implementation performs this validation immediately instead of waiting until <code>save</code>.
131: * @throws LockException if a lock prevents the setting of the value and this
132: * implementation performs this validation immediately instead of waiting until <code>save</code>.
133: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
134: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
135: * @throws RepositoryException if another error occurs.
136: */
137: public void setValue(String[] values) throws ValueFormatException,
138: VersionException, LockException,
139: ConstraintViolationException, RepositoryException;
140:
141: /**
142: * Sets the value of this property to <code>value</code>.
143: * Same as <code>{@link #setValue(Value value)}</code> except that the
144: * value is specified as an <code>InputStream</code>.
145: * <p/>
146: * The passed stream is closed before this method returns either normally or
147: * because of an exception.
148: *
149: * @deprecated As of JCR 2.0, {@link #setValue(Binary)} should be used instead.
150: *
151: * @param value The new value to set the property to.
152: * @throws ValueFormatException if the type or format of the specified value
153: * is incompatible with the type of this property.
154: * @throws VersionException if this property belongs to a node that is versionable and checked-in
155: * or is non-versionable but whose nearest versionable ancestor is checked-in and this
156: * implementation performs this validation immediately instead of waiting until <code>save</code>.
157: * @throws LockException if a lock prevents the setting of the value and this
158: * implementation performs this validation immediately instead of waiting until <code>save</code>.
159: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
160: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
161: * @throws RepositoryException if another error occurs.
162: */
163: public void setValue(InputStream value)
164: throws ValueFormatException, VersionException,
165: LockException, ConstraintViolationException,
166: RepositoryException;
167:
168: /**
169: * Sets the value of this property to <code>value</code>.
170: * Same as <code>{@link #setValue(Value value)}</code> except that the
171: * value is specified as a <code>Binary</code>.
172: *
173: * @param value The new value to set the property to.
174: * @throws ValueFormatException if the type or format of the specified value
175: * is incompatible with the type of this property.
176: * @throws VersionException if this property belongs to a node that is versionable and checked-in
177: * or is non-versionable but whose nearest versionable ancestor is checked-in and this
178: * implementation performs this validation immediately instead of waiting until <code>save</code>.
179: * @throws LockException if a lock prevents the setting of the value and this
180: * implementation performs this validation immediately instead of waiting until <code>save</code>.
181: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
182: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
183: * @throws RepositoryException if another error occurs.
184: */
185: public void setValue(Binary value) throws ValueFormatException,
186: VersionException, LockException,
187: ConstraintViolationException, RepositoryException;
188:
189: /**
190: * Sets the value of this property to <code>value</code>.
191: * Same as <code>{@link #setValue(Value value)}</code> except that the
192: * value is specified as a <code>long</code>.
193: *
194: * @param value The new value to set the property to.
195: * @throws ValueFormatException if the type or format of the specified value
196: * is incompatible with the type of this property.
197: * @throws VersionException if this property belongs to a node that is versionable and checked-in
198: * or is non-versionable but whose nearest versionable ancestor is checked-in and this
199: * implementation performs this validation immediately instead of waiting until <code>save</code>.
200: * @throws LockException if a lock prevents the setting of the value and this
201: * implementation performs this validation immediately instead of waiting until <code>save</code>.
202: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
203: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
204: * @throws RepositoryException if another error occurs.
205: */
206: public void setValue(long value) throws ValueFormatException,
207: VersionException, LockException,
208: ConstraintViolationException, RepositoryException;
209:
210: /**
211: * Sets the value of this property to <code>value</code>.
212: * Same as <code>{@link #setValue(Value value)}</code> except that the
213: * value is specified as a <code>double</code>.
214: *
215: * @param value The new value to set the property to.
216: * @throws ValueFormatException if the type or format of the specified value
217: * is incompatible with the type of this property.
218: * @throws VersionException if this property belongs to a node that is versionable and checked-in
219: * or is non-versionable but whose nearest versionable ancestor is checked-in and this
220: * implementation performs this validation immediately instead of waiting until <code>save</code>.
221: * @throws LockException if a lock prevents the setting of the value and this
222: * implementation performs this validation immediately instead of waiting until <code>save</code>.
223: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
224: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
225: * @throws RepositoryException if another error occurs.
226: */
227: public void setValue(double value) throws ValueFormatException,
228: VersionException, LockException,
229: ConstraintViolationException, RepositoryException;
230:
231: /**
232: * Sets the value of this property to <code>value</code>.
233: * Same as <code>{@link #setValue(Value value)}</code> except that the
234: * value is specified as a <code>BigDecimal</code>.
235: *
236: * @param value The new value to set the property to.
237: * @throws ValueFormatException if the type or format of the specified value
238: * is incompatible with the type of this property.
239: * @throws VersionException if this property belongs to a node that is versionable and checked-in
240: * or is non-versionable but whose nearest versionable ancestor is checked-in and this
241: * implementation performs this validation immediately instead of waiting until <code>save</code>.
242: * @throws LockException if a lock prevents the setting of the value and this
243: * implementation performs this validation immediately instead of waiting until <code>save</code>.
244: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
245: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
246: * @throws RepositoryException if another error occurs.
247: * @since JCR 2.0
248: */
249: public void setValue(BigDecimal value) throws ValueFormatException,
250: VersionException, LockException,
251: ConstraintViolationException, RepositoryException;
252:
253: /**
254: * Sets the value of this property to <code>value</code>.
255: * Same as <code>{@link #setValue(Value value)}</code> except that the
256: * value is specified as a <code>Calendar</code>.
257: *
258: * @param value The new value to set the property to.
259: * @throws ValueFormatException if the type or format of the specified value
260: * is incompatible with the type of this property.
261: * @throws VersionException if this property belongs to a node that is versionable and checked-in
262: * or is non-versionable but whose nearest versionable ancestor is checked-in and this
263: * implementation performs this validation immediately instead of waiting until <code>save</code>.
264: * @throws LockException if a lock prevents the setting of the value and this
265: * implementation performs this validation immediately instead of waiting until <code>save</code>.
266: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
267: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
268: * @throws RepositoryException if another error occurs.
269: */
270: public void setValue(Calendar value) throws ValueFormatException,
271: VersionException, LockException,
272: ConstraintViolationException, RepositoryException;
273:
274: /**
275: * Sets the value of this property to <code>value</code>.
276: * Same as <code>{@link #setValue(Value value)}</code> except that the
277: * value is specified as a <code>boolean</code>.
278: *
279: * @param value The new value to set the property to.
280: * @throws ValueFormatException if the type or format of the specified value
281: * is incompatible with the type of this property.
282: * @throws VersionException if this property belongs to a node that is versionable and checked-in
283: * or is non-versionable but whose nearest versionable ancestor is checked-in and this
284: * implementation performs this validation immediately instead of waiting until <code>save</code>.
285: * @throws LockException if a lock prevents the setting of the value and this
286: * implementation performs this validation immediately instead of waiting until <code>save</code>.
287: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
288: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
289: * @throws RepositoryException if another error occurs.
290: */
291: public void setValue(boolean value) throws ValueFormatException,
292: VersionException, LockException,
293: ConstraintViolationException, RepositoryException;
294:
295: /**
296: * Sets this REFERENCE property to refer to the specified node. If
297: * this property is not of type REFERENCE or the specified node is
298: * not referenceable (i.e., is not of mixin node type
299: * <code>mix:referenceable</code> and therefore does not have a UUID) then a
300: * <code>ValueFormatException</code> is thrown.
301: *
302: * @param value The node to which this REFERENCE property will refer.
303: * @throws ValueFormatException if the type or format of the specified value
304: * is incompatible with the type of this property.
305: * @throws VersionException if this property belongs to a node that is versionable and checked-in
306: * or is non-versionable but whose nearest versionable ancestor is checked-in and this
307: * implementation performs this validation immediately instead of waiting until <code>save</code>.
308: * @throws LockException if a lock prevents the setting of the value and this
309: * implementation performs this validation immediately instead of waiting until <code>save</code>.
310: * @throws ConstraintViolationException if the change would violate a node-type or other constraint
311: * and this implementation performs this validation immediately instead of waiting until <code>save</code>.
312: * @throws RepositoryException if another error occurs.
313: */
314: public void setValue(Node value) throws ValueFormatException,
315: VersionException, LockException,
316: ConstraintViolationException, RepositoryException;
317:
318: /**
319: * Returns the value of this property as a <code>Value</code> object.
320: * <p>
321: * If this property is multi-valued, this method throws a <code>ValueFormatException</code>.
322: * <p/>
323: * The object returned is a copy of the stored value and is immutable.
324: *
325: * @throws ValueFormatException if the property is multi-valued.
326: * @throws RepositoryException if another error occurs.
327: *
328: * @return the value
329: */
330: public Value getValue() throws ValueFormatException,
331: RepositoryException;
332:
333: /**
334: * Returns an array of all the values of this property. Used to access
335: * multi-value properties. If the property is single-valued, this method throws a
336: * <code>ValueFormatException</code>. The array returned is a copy of the stored
337: * values, so changes to it are not reflected in internal storage.
338: *
339: * @throws ValueFormatException if the property is single-valued.
340: * @throws RepositoryException if another error occurs.
341: *
342: * @return a <code>Value</code> array
343: */
344: public Value[] getValues() throws ValueFormatException,
345: RepositoryException;
346:
347: /**
348: * Returns a <code>String</code> representation of the value of this
349: * property. A shortcut for
350: * <code>Property.getValue().getString()</code>. See {@link Value}.
351: * If this property is multi-valued, this method throws a <code>ValueFormatException</code>.
352: * <p>
353: * If the value of this property cannot be converted to a <code>String</code>,
354: * a <code>ValueFormatException</code> is thrown.
355: * <p>
356: * A <code>RepositoryException</code> is thrown if another error occurs.
357: *
358: * @return A string representation of the value of this property.
359: * @throws ValueFormatException if conversion to a <code>String</code> is
360: * not possible or if the property is multi-valued.
361: * @throws RepositoryException if another error occurs.
362: */
363: public String getString() throws ValueFormatException,
364: RepositoryException;
365:
366: /**
367: * Returns an <code>InputStream</code> representation of the value of this
368: * property. A shortcut for
369: * <code>Property.getValue().getStream()</code>. See {@link Value}.
370: * <p/>
371: * It is the responsibility of the caller to close the returned InputStream.
372: * <p/>
373: * If this property is multi-valued, this method throws a <code>ValueFormatException</code>.
374: * <p/>
375: * A <code>RepositoryException</code> is thrown if another error occurs.
376: *
377: * @deprecated As of JCR 2.0, {@link #getBinary()} should be used instead.
378: *
379: * @return A stream representation of the value of this property.
380: * @throws ValueFormatException if the property is multi-valued.
381: * @throws RepositoryException if another error occurs
382: */
383: public InputStream getStream() throws ValueFormatException,
384: RepositoryException;
385:
386: /**
387: * Returns a <code>Binary</code> representation of the value of this
388: * property. A shortcut for
389: * <code>Property.getValue().getBinary()</code>. See {@link Value}.
390: * <p/>
391: * It is the responsibility of the caller to close the returned InputStream.
392: * <p/>
393: * If this property is multi-valued, this method throws a <code>ValueFormatException</code>.
394: * <p/>
395: * A <code>RepositoryException</code> is thrown if another error occurs.
396: *
397: * @return A stream representation of the value of this property.
398: * @throws ValueFormatException if the property is multi-valued.
399: * @throws RepositoryException if another error occurs
400: * @since JCR 2.0
401: */
402: public Binary getBinary() throws ValueFormatException,
403: RepositoryException;
404:
405: /**
406: * Returns a <code>long</code> representation of the value of this
407: * property. A shortcut for
408: * <code>Property.getValue().getLong()</code>. See {@link Value}.
409: * If this property is multi-valued, this method throws a <code>ValueFormatException</code>.
410: * <p>
411: * If the value of this property cannot be converted to a
412: * <code>long</code>, a <code>ValueFormatException</code> is thrown.
413: * <p>
414: * A <code>RepositoryException</code> is thrown if another error occurs.
415: *
416: * @return A <code>long</code> representation of the value of this property.
417: * @throws ValueFormatException if conversion to a <code>long</code> is not
418: * possible or if the property is multi-valued.
419: * @throws RepositoryException if another error occurs
420: */
421: public long getLong() throws ValueFormatException,
422: RepositoryException;
423:
424: /**
425: * Returns a <code>double</code> representation of the value of this
426: * property. A shortcut for
427: * <code>Property.getValue().getDouble()</code>. See {@link Value}.
428: * If this property is multi-valued, this method throws a <code>ValueFormatException</code>.
429: * <p>
430: * If the value of this property cannot be converted to a <code>double</code>,
431: * a <code>ValueFormatException</code> is thrown.
432: * <p>
433: * A <code>RepositoryException</code> is thrown if another error occurs.
434: *
435: * @return A double representation of the value of this property.
436: * @throws ValueFormatException if conversion to a <code>double</code> is
437: * not possible or if the property is multi-valued.
438: * @throws RepositoryException if another error occurs
439: */
440: public double getDouble() throws ValueFormatException,
441: RepositoryException;
442:
443: /**
444: * Returns a <code>BigDecimal</code> representation of the value of this
445: * property. A shortcut for
446: * <code>Property.getValue().getDecimal()</code>. See {@link Value}.
447: * If this property is multi-valued, this method throws a <code>ValueFormatException</code>.
448: * <p>
449: * If the value of this property cannot be converted to a <code>BigDecimal</code>,
450: * a <code>ValueFormatException</code> is thrown.
451: * <p>
452: * A <code>RepositoryException</code> is thrown if another error occurs.
453: *
454: * @return A <code>BigDecimal</code> representation of the value of this property.
455: * @throws ValueFormatException if conversion to a <code>BigDecimal</code>
456: * is not possible or if the property is multi-valued.
457: * @throws RepositoryException if another error occurs
458: * @since JCR 2.0
459: */
460: public BigDecimal getDecimal() throws ValueFormatException,
461: RepositoryException;
462:
463: /**
464: * Returns a <code>Calendar</code> representation of the value of this
465: * property. A shortcut for
466: * <code>Property.getValue().getDate()</code>. See {@link Value}.
467: * <p/>
468: * The object returned is a copy of the stored value, so changes to it are not reflected in internal storage.
469: * <p/>
470: * If this property is multi-valued, this method throws a <code>ValueFormatException</code>.
471: * <p>
472: * If the value of this property cannot be converted to a
473: * <code>Calendar</code>, a <code>ValueFormatException</code> is thrown.
474: * <p>
475: * A <code>RepositoryException</code> is thrown if another error occurs.
476: *
477: * @return A date (<code>Calendar</code> object) representation of the value of this property.
478: * @throws ValueFormatException if conversion to a string is not possible or if the
479: * property is multi-valued.
480: * @throws RepositoryException if another error occurs
481: */
482: public Calendar getDate() throws ValueFormatException,
483: RepositoryException;
484:
485: /**
486: * Returns a <code>boolean</code> representation of the value of this
487: * property. A shortcut for
488: * <code>Property.getValue().getBoolean()</code>. See {@link Value}.
489: * If this property is multi-valued, this method throws a <code>ValueFormatException</code>.
490: * <p>
491: * If the value of this property cannot be converted to a <code>boolean</code>,
492: * a <code>ValueFormatException</code> is thrown.
493: * <p>
494: * A <code>RepositoryException</code> is thrown if another error occurs.
495: *
496: * @return A <code>boolean</code> representation of the value of this property.
497: * @throws ValueFormatException if conversion to a <code>boolean</code> is
498: * not possible or if the property is multi-valued.
499: * @throws RepositoryException if another error occurs
500: */
501: public boolean getBoolean() throws ValueFormatException,
502: RepositoryException;
503:
504: /**
505: * If this property is of type <code>REFERENCE</code>, <code>WEAKREFERENCE</code> or <code>PATH</code>
506: * (or convertible to one of these types) this method returns the <code>Node</code> to which this property refers.
507: * <p/>
508: * If this property is of type <code>PATH</code> and it contains a relative path, it is interpreted relative to the
509: * parent node of this property. For example "<code>.</code>" refers to the parent node itself, "<code>..</code>" to
510: * the parent of the parent node and "<code>foo</code>" to a sibling node of this property.
511: * <p/>
512: * If this property is of type <code>WEAKREFERENCE</code> and no node exists in this workspace with the specified
513: * UUID then an <code>ItemNotFoundException</code> is thrown.
514: * <p/>
515: * If this property is of type <code>PATH</code> and no node accessible by the current <code>Session</code>exists
516: * in this workspace at the specified path then an <code>ItemNotFoundException</code> is thrown. Note that this
517: * applies even if a <i>property</i> exists at the specified location. To dereference to a target property (as
518: * opposed to a target node), the method <code>Property.getProperty</code> is used.
519: * <p/>
520: * If this property is multi-valued, this method throws a <code>ValueFormatException</code>.
521: * <p/>
522: * If this property cannot be converted to a <code>REFERENCE</code>, <code>WEAKREFERENCE</code> or <code>PATH</code>
523: * then a <code>ValueFormatException</code> is thrown.
524: * <p/>
525: * If this property is currently part of the frozen state of a version in version storage, this method will throw a
526: * <code>ValueFormatException</code>.
527: *
528: * @return the referenced Node
529: * @throws ValueFormatException if this property cannot be converted to a referring type (<code>REFERENCE</code>,
530: * <code>WEAKREFERENCE</code> or PATH), if the property is multi-valued or if this property is a referring type
531: * but is currently part of the frozen state of a version in version storage.
532: * @throws ItemNotFoundException If this property is of type <code>PATH</code> and no node accessible by the current <code>Session</code> exists
533: * in this workspace at the specified path.
534: * @throws RepositoryException if another error occurs
535: */
536: public Node getNode() throws ItemNotFoundException,
537: ValueFormatException, RepositoryException;
538:
539: /**
540: * If this property is of type <code>PATH</code> (or convertible to this type) this method returns the
541: * <code>Property</code> to which <i>this</i> property refers.
542: * <p/>
543: * If this property contains a relative path, it is interpreted relative to the parent node of this property.
544: * For example "<code>.</code>" refers to the parent node itself, "<code>..</code>" to the parent of the parent node
545: * and "<code>foo</code>" to a sibling property of this property or this property itself.
546: * <p/>
547: * If no property exists in this workspace at the specified path then an <code>ItemNotFoundException</code> is
548: * thrown. Note that this applies even if a <i>node</i> exists at the specified location. To dereference to a target
549: * node, the method <code>Property.getNode</code> is used.
550: * <p/>
551: * If this property is multi-valued, this method throws a <code>ValueFormatException</code>.
552: * <p/>
553: * If this property cannot be converted to a <code>PATH</code> then a <code>ValueFormatException</code> is thrown.
554: * <p/>
555: * If this property is currently part of the frozen state of a version in version storage, this method will throw a
556: * <code>ValueFormatException</code>.
557: *
558: * @return the referenced property
559: * @throws ValueFormatException if this property cannot be converted to a <code>PATH</code>, if the property is multi-valued or if this property is a referring type
560: * but is currently part of the frozen state of a version in version storage.
561: * @throws ItemNotFoundException If this property is of type <code>PATH</code> and no property accessible by the current <code>Session</code> exists
562: * in this workspace at the specified path.
563: * @throws RepositoryException if another error occurs
564: * @since JCR 2.0
565: */
566: public Property getProperty() throws ItemNotFoundException,
567: ValueFormatException, RepositoryException;
568:
569: /**
570: * Returns the length of the value of this property.
571: * <p>
572: * Returns the length in bytes if the value is a
573: * <code>BINARY</code>, otherwise it returns the number of
574: * characters needed to display the value in its string form.
575: * <p/>
576: * Returns -1 if the implementation cannot determine the length.
577: * <p/>
578: * If this property is multi-valued, this method throws a <code>ValueFormatException</code>.
579: *
580: * @return an <code>long</code>.
581: * @throws ValueFormatException if this property is multi-valued.
582: * @throws RepositoryException if another error occurs.
583: */
584: public long getLength() throws ValueFormatException,
585: RepositoryException;
586:
587: /**
588: * Returns an array holding the lengths of the values of this (multi-value) property in bytes
589: * if the values are <code>PropertyType.BINARY</code>, otherwise it returns the number of
590: * characters needed to display the value in its string form. The order of the
591: * length values corresponds to the order of the values in the property.
592: * <p/>
593: * Returns a <code>-1</code> in the appropriate position if the implementation cannot determine
594: * the length of a value.
595: * <p/>
596: * If this property is single-valued, this method throws a <code>ValueFormatException</code>.
597: * <p/>
598: * A RepositoryException is thrown if another error occurs.
599: * @return an array of lengths
600: * @throws ValueFormatException if this property is single-valued.
601: * @throws RepositoryException if another error occurs.
602: */
603: public long[] getLengths() throws ValueFormatException,
604: RepositoryException;
605:
606: /**
607: * Returns the property definition that applies to this property. In some cases there may appear to
608: * be more than one definition that could apply to this node. However, it is assumed that upon
609: * creation or change of this property, a single particular definition is chosen by the implementation.
610: * It is <i>that</i> definition that this method returns. How this governing definition is selected upon property
611: * creation or change from among others which may have been applicable is an implementation issue and is not
612: * covered by this specification.
613: *
614: * @see javax.jcr.nodetype.NodeType#getPropertyDefinitions
615: * @throws RepositoryException if an error occurs.
616: * @return a <code>PropertyDefinition</code> object.
617: */
618: public PropertyDefinition getDefinition()
619: throws RepositoryException;
620:
621: /**
622: * Returns the type of this <code>Property</code>. One of:
623: * <ul>
624: * <li><code>PropertyType.STRING</code></li>
625: * <li><code>PropertyType.BINARY</code></li>
626: * <li><code>PropertyType.DATE</code></li>
627: * <li><code>PropertyType.DOUBLE</code></li>
628: * <li><code>PropertyType.LONG</code></li>
629: * <li><code>PropertyType.BOOLEAN</code></li>
630: * <li><code>PropertyType.NAME</code></li>
631: * <li><code>PropertyType.PATH</code></li>
632: * <li><code>PropertyType.REFERENCE</code></li>
633: * <li><code>PropertyType.WEAKREFERENCE</code></li>
634: * <li><code>PropertyType.URI</code></li>
635: * </ul>
636: * The type returned is that which was set at property creation. Note that for some property <code>p</code>,
637: * the type returned by <code>p.getType()</code> will differ from the type returned by
638: * <code>p.getDefinition.getRequiredType()</code> only in the case where the latter returns <code>UNDEFINED</code>.
639: * The type of a property instance is never <code>UNDEFINED</code> (it must always have some actual type).
640: *
641: * @return an int
642: * @throws RepositoryException if an error occurs
643: */
644: public int getType() throws RepositoryException;
645: }
|