KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > jcr > Node


1 /*
2  * $Id: Node.java,v 1.2 2004/07/24 00:16:21 benjmestrallet Exp $
3  *
4  * Copyright 2002-2004 Day Management AG, Switzerland.
5  *
6  * Licensed under the Day RI License, Version 2.0 (the "License"),
7  * as a reference implementation of the following specification:
8  *
9  * Content Repository API for Java Technology, revision 0.12
10  * <http://www.jcp.org/en/jsr/detail?id=170>
11  *
12  * You may not use this file except in compliance with the License.
13  * You may obtain a copy of the License files at
14  *
15  * http://www.day.com/content/en/licenses/day-ri-license-2.0
16  * http://www.apache.org/licenses/LICENSE-2.0
17  *
18  * Unless required by applicable law or agreed to in writing, software
19  * distributed under the License is distributed on an "AS IS" BASIS,
20  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
21  * See the License for the specific language governing permissions and
22  * limitations under the License.
23  */

24 package javax.jcr;
25
26 import javax.jcr.access.AccessDeniedException;
27 import javax.jcr.nodetype.ConstraintViolationException;
28 import javax.jcr.nodetype.NoSuchNodeTypeException;
29 import javax.jcr.nodetype.NodeDef;
30 import javax.jcr.nodetype.NodeType;
31 import javax.jcr.version.*;
32 import java.io.InputStream JavaDoc;
33 import java.util.Calendar JavaDoc;
34
35 /**
36  * The <code>Node</code> interface represents a node in the hierarchy that
37  * makes up the repository.
38  *
39  * @author Peeter Piegaze
40  * @author Stefan Guggisberg
41  */

42 public interface Node extends Item {
43
44   /**
45    * Creates a new node at <code>relPath</code>. The new node will only be
46    * persisted in the workspace when <code>save()</code> and if the structure
47    * of the new node (its child nodes and properties) meets the constraint
48    * criteria of the parent node's node type.
49    * <p/>
50    * If <code>relPath</code> implies intermediary nodes that do not
51    * exist then a <code>PathNotFoundException</code> is thrown.
52    * <p/>
53    * If an item already exists at <code>relPath</code> then an
54    * <code>ItemExistsException</code> is thrown.
55    * <p/>
56    * If an attempt is made to add a node as a child of a
57    * property then a <code>ConstraintViolationException</code> is
58    * thrown immediately (not on <code>save</code>).
59    * <p/>
60    * Since this signature does not allow explicit node type assignment, the
61    * new node's node types (primary and mixin, if applicable) will be
62    * determined immediately (not on save) by the <code>NodeDef</code>s
63    * in the node types of its parent. If there is no <code>NodeDef</code>
64    * corresponding to the name specified for this new node, then a
65    * <code>ConstraintViolationException</code> is thrown immediately (not on
66    * <code>save</code>).
67    *
68    * @param relPath The path of the new node to be created.
69    * @return The node that was added.
70    * @throws ItemExistsException If an item at the specified path already exists.
71    * @throws PathNotFoundException If the specified path implies intermediary
72    * nodes that do not exist.
73    * @throws ConstraintViolationException if If there is no NodeDef
74    * corresponding to the name specified for this new node in the parent
75    * node's node type, or if an attempt is made to add a node as a child of a
76    * property.
77    * @throws RepositoryException If another error occurs.
78    */

79   public Node addNode(String JavaDoc relPath) throws ItemExistsException, PathNotFoundException, ConstraintViolationException, RepositoryException;
80
81   /**
82    * Creates a new node at <code>relPath</code> of the specified node type.
83    * The same as <code>{@link #addNode(String relPath)}</code> except that the primary
84    * node type type of the new node is explictly specified.
85    * <p/>
86    * If <code>primaryNodeTypeName</code> is not
87    * recognized, then a <code>NoSuchNodeTypeException</code> is thrown.
88    *
89    * @param relPath The path of the new <code>Node</code> that is to be created,
90    * the last item of this pathwill be the name of the new <code>Node</code>.
91    * @param primaryNodeTypeName The name of the primary node type of the new node.
92    * @return The node that was added.
93    * @throws ItemExistsException If an item at the
94    * specified path already exists.
95    * @throws PathNotFoundException If specified path implies intermediary
96    * <code>Node</code>s that do not exist.
97    * @throws NoSuchNodeTypeException If the specified <code>nodeTypeName</code>
98    * is not recognized.
99    * @throws ConstraintViolationException If an attempt is made to add a node as the
100    * child of a <code>Property</code>
101    * @throws RepositoryException if another error occurs.
102    */

103   public Node addNode(String JavaDoc relPath, String JavaDoc primaryNodeTypeName) throws ItemExistsException, PathNotFoundException, NoSuchNodeTypeException, ConstraintViolationException, RepositoryException;
104
105   /**
106    * Adds the existing node at <code>absPath</code> as child of this node, thus adding
107    * <code>this</code> node as an addional parent of the node at <code>absPath</code>.
108    * <p/>
109    * This change will be persisted (if valid) on <code>save</code>.
110    * <p/>
111    * If the node at <code>absPath</code> is not of mixin type
112    * <code>mix:referenceable</code>, a <code>ConstraintViolationException</code>
113    * will be thrown on <code>save</code>.
114    * <p/>
115    * The name of the new child node as accessed from <code>this</code> node
116    * will be the same as its current name in <code>absPath</code> (that is, the last path
117    * segment in that <code>absPath</code>).
118    *
119    * @param absPath The absolute path of the new child node.
120    * @return The new child node.
121    * @throws PathNotFoundException If no node exists at <code>absPath</code>.
122    * @throws RepositoryException In level 2: If another error occurs.
123    */

124   public Node addExistingNode(String JavaDoc absPath) throws PathNotFoundException, RepositoryException;
125
126   /**
127    * The same as <code>addExistingNode(String absPath)</code> except that the
128    * node at <code>absPath</code> adopts <code>newName</code> in the path
129    * where this node is its parent.
130    *
131    * @param absPath The absolute path of the new child node.
132    * @param newName The new name for this node when referenced as a child of this node.
133    * @return The new child node.
134    * @throws PathNotFoundException If no node exists at <code>absPath</code>.
135    * @throws RepositoryException If another error occurs.
136    */

137   public Node addExistingNode(String JavaDoc absPath, String JavaDoc newName) throws PathNotFoundException, RepositoryException;
138
139   /**
140    * Sets the specified property to the specified value. If the property does
141    * not yet exist, it is created. The property type of the property will be
142    * that specified by the node type of <code>this</code> node (the one on
143    * which this method is being called). If the </code>PropertyType</code>
144    * of the supplied <code>Value</code> object (recall that a
145    * <code>{@link Value}</code> object records the property type of its
146    * contained value) is different from that required, a best-effort
147    * conversion is attempted.
148    * <p/>
149    * If the node type of the parent node does not specify a
150    * specific property type for the property being set, then
151    * the property type of the supplied <code>Value</code> object
152    * is used.
153    * <p/>
154    * If the property already exists (has previously been set) it assumes
155    * the new value. If the node type of the parent node does not specify a
156    * specific property type for the property being set, then the property
157    * will also assume the new type (if different).
158    * <p/>
159    * To erase a property, use <code>{@link #remove(String relPath)}</code>.
160    * <p/>
161    * To persist the addition or change of a property to the workspace
162    * <code>{@link #save}</code> must be called on
163    * this node (the parent of the property being set) or a higher-order
164    * ancestor of the property.
165    *
166    * @param name The name of a property of this node
167    * @param value The value to be assigned
168    * @return The updated <code>Property</code> object
169    * @throws ValueFormatException if <code>value</code> is incompatible with
170    * (i.e. can not be converted to) the type of the specified property.
171    * @throws RepositoryException If another error occurs.
172    */

173   public Property setProperty(String JavaDoc name, Value value) throws ValueFormatException, RepositoryException;
174
175   /**
176    * Sets the specified property to the specified value and the specified type.
177    * If the property does not yet exist, it is created.
178    * <p/>
179    * If the node type of the parent node does not specify a
180    * specific property type for the property being set, then the property type
181    * specified by the <code>type</code> parameter is used.
182    * <p/>
183    * If the property already exists (has previously been set) it assumes both
184    * the new value and new type.
185    * <p/>
186    * To erase a property, use
187    * <code>{@link #remove(String relPath)}</code>.
188    * <p/>
189    * To persist the addition or change of a property to the workspace
190    * <code>save()</code> must be called on
191    * <code>this</code> node (the parent of the property being set) or a higher-order
192    * ancestor of the property.
193    *
194    * @param name The name of a property of this node
195    * @param value The value to be assigned
196    * @param type The type of the property
197    * @return The updated <code>Property</code> object
198    * @throws ValueFormatException if the type or format of <code>value</code>
199    * is incompatible with the type of the specified property or if
200    * <code>value</code> is incompatible with (i.e. can not be converted to)
201    * <code>type</code>.
202    * @throws RepositoryException If another error occurs.
203    */

204   public Property setProperty(String JavaDoc name, Value value, int type) throws ValueFormatException, RepositoryException;
205
206   /**
207    * Sets the specified property to the specified array of values (assuming it
208    * is a multi-value property) and the specified type. Same as
209    * <code>{@link #setProperty(String name, Value value, int type)}<code>
210    * except that an array of <code>Value</code> objects is assigned instead
211    * of a single <code>Value</code>. If an array of more than one element
212    * is passed and the property is not multi-valued then a
213    * <code>ValueFormatException</code> is thrown.
214    *
215    * @param name the name of the property to be set.
216    * @param values an array of <code>Value</code> objects.
217    * @param type a <code>PropertyType</code> constant.
218    * @return the updated <code>Property</code> object.
219    * @throws ValueFormatException if the type or format of <code>values</code>
220    * is incompatible with the type of the specified property or if
221    * <code>values</code> is incompatible with (i.e. can not be converted to)
222    * <code>type</code> or if an array of more than one value is being passed
223    * and the property is not multi-valued.
224    * @throws RepositoryException if another error occurs.
225    */

226   public Property setProperty(String JavaDoc name, Value[] values, int type) throws ValueFormatException, RepositoryException;
227
228   /**
229    * Sets the specified property to the specified value and the specified type.
230    * If the property does not yet exist, it is created. Same as
231    * {@link #setProperty(String name, Value value, int type)} except the value
232    * is passed as a <code>String</code> instead of a <code>Value</code> object.
233    *
234    * @param name The name of a property of this node
235    * @param value The value to assigned
236    * @param type The type of the property
237    * @return The updated <code>Property</code> object
238    * @throws ValueFormatException if the type or format of <code>value</code>
239    * is incompatible with the type of the specified property or if
240    * <code>value</code> is incompatible with (i.e. can not be converted to)
241    * <code>type</code>.
242    * @throws RepositoryException If another error occurs.
243    */

244   public Property setProperty(String JavaDoc name, String JavaDoc value, int type) throws ValueFormatException, RepositoryException;
245
246   /**
247    * Sets the specified property to the specified array of values (assuming it
248    * is a multi-value property) and the specified type. Same as
249    * <code>{@link #setProperty(String name, String[] value, int type)}<code>
250    * except that an array of <code>String</code> objects is assigned instead
251    * of a single <code>String</code>. If an array of more than one element
252    * is passed and the property is not multi-valued then a
253    * <code>ValueFormatException</code> is thrown.
254    *
255    * @param name the name of the property to be set.
256    * @param values an array of <code>String</code> objects.
257    * @param type a <code>PropertyType</code> constant.
258    * @return the updated <code>Property</code> object.
259    * @throws ValueFormatException if the type or format of <code>values</code>
260    * is incompatible with the type of the specified property or if
261    * <code>values</code> is incompatible with (i.e. can not be converted to)
262    * <code>type</code> or if an array of more than one value is being passed
263    * and the property is not multi-valued.
264    * @throws RepositoryException if another error occurs.
265    */

266   public Property setProperty(String JavaDoc name, String JavaDoc[] values, int type) throws ValueFormatException, RepositoryException;
267
268   /**
269    * Sets the specified property to the specified value.
270    * If the property does not yet exist, it is created.
271    * The property type of the property being set is determined
272    * by the node type of <code>this</code> node (the one on which
273    * this method is being called). If this is something other than
274    * <code>PropertyType.STRING</code>, a best-effort conversion is attempted.
275    * If the conversion fails, a <code>ValueFormatException</code> is
276    * thrown.
277    * <p/>
278    * If the node type of <code>this</code> node does not
279    * specify a particular property type for the property being set
280    * then <code>PropertyType.STRING</code> is used.
281    * <p/>
282    * If the property
283    * already exists (has previously been set) it assumes both the new value
284    * and new type (if different). To erase a property, use
285    * <code>{@link #remove(String relPath)}</code>.
286    * <p/>
287    * To persist the addition or change of a property to the workspace
288    * <code>save</code> must be called.
289    * <p/>
290    *
291    * @param name The name of a property of this node
292    * @param value The value to assigned
293    * @return The updated <code>Property</code> object
294    * @throws ValueFormatException if <code>value</code> is incompatible with
295    * (i.e. can not be converted to) the type of the specified property.
296    * @throws RepositoryException If another error occurs.
297    */

298   public Property setProperty(String JavaDoc name, String JavaDoc value) throws ValueFormatException, RepositoryException;
299
300   /**
301    * Sets the specified property to the specified value.
302    * If the property does not yet exist, it is created.
303    * Same as <code>{@link #setProperty(String name, String value)}</code>
304    * except that the value passed is an <code>InputStream</code> and therefore the
305    * implied property type is <code>PropertyType.BINARY</code>.
306    *
307    * @param name The name of a property of this node
308    * @param value The value to assigned
309    * @return The updated <code>Property</code> object
310    * @throws ValueFormatException if <code>value</code> is incompatible with
311    * (i.e. can not be converted to) the type of the specified property.
312    * @throws RepositoryException If another error occurs.
313    */

314   public Property setProperty(String JavaDoc name, InputStream JavaDoc value) throws ValueFormatException, RepositoryException;
315
316   /**
317    * Sets the specified property to the specified value.
318    * If the property does not yet exist, it is created.
319    * Same as <code>{@link #setProperty(String name, String value)}</code>
320    * except that the value passed is a <code>boolean</code> and therefore the
321    * implied property type is <code>PropertyType.BOOLEAN</code>.
322    *
323    * @param name The name of a property of this node
324    * @param value The value to assigned
325    * @return The updated <code>Property</code> object
326    * @throws ValueFormatException if <code>value</code> is incompatible with
327    * (i.e. can not be converted to) the type of the specified property.
328    * @throws RepositoryException If another error occurs.
329    */

330   public Property setProperty(String JavaDoc name, boolean value) throws ValueFormatException, RepositoryException;
331
332   /**
333    * Sets the specified property to the specified value.
334    * If the property does not yet exist, it is created.
335    * Same as <code>{@link #setProperty(String name, String value)}</code>
336    * except that the value passed is a <code>double</code> and therefore the implied
337    * property type is <code>PropertyType.DOUBLE</code>.
338    *
339    * @param name The name of a property of this node
340    * @param value The value to assigned
341    * @return The updated <code>Property</code> object
342    * @throws ValueFormatException if <code>value</code> is incompatible with
343    * (i.e. can not be converted to) the type of the specified property.
344    * @throws RepositoryException If another error occurs.
345    */

346   public Property setProperty(String JavaDoc name, double value) throws ValueFormatException, RepositoryException;
347
348   /**
349    * Sets the specified property to the specified value.
350    * If the property does not yet exist, it is created.
351    * Same as <code>{@link #setProperty(String name, String value)}</code>
352    * except that the value passed is a <code>long</code> and therefore the implied
353    * property type is <code>PropertyType.LONG</code>.
354    *
355    * @param name The name of a property of this node
356    * @param value The value to assigned
357    * @return The updated <code>Property</code> object
358    * @throws ValueFormatException if <code>value</code> is incompatible with
359    * (i.e. can not be converted to) the type of the specified property.
360    * @throws RepositoryException If another error occurs.
361    */

362   public Property setProperty(String JavaDoc name, long value) throws ValueFormatException, RepositoryException;
363
364   /**
365    * Sets the specified property to the specified value.
366    * If the property does not yet exist, it is created.
367    * Same as <code>{@link #setProperty(String name, String value)}</code>
368    * except that the value passed is a <code>Calendar</code> and therefore the implied
369    * property type is <code>PropertyType.DATE</code>.
370    *
371    * @param name The name of a property of this node
372    * @param value The value to assigned
373    * @return The updated <code>Property</code> object
374    * @throws ValueFormatException if <code>value</code> is incompatible with
375    * (i.e. can not be converted to) the type of the specified property.
376    * @throws RepositoryException If another error occurs.
377    */

378   public Property setProperty(String JavaDoc name, Calendar JavaDoc value) throws ValueFormatException, RepositoryException;
379
380   /**
381    * Removes the parent-child binding along relPath to the item. If this item
382    * is a node that has other references to it (due to multiple parents),
383    * then all of these other references to the node are preserved. If the
384    * item at path has no other references to it then it is actually erased,
385    * along with any child items that also have no other references and so on
386    * down the subtree. A call to save (either on Ticket or on an ancestor of
387    * the newly removed node) is required to persist the removal.
388    *
389    * @param relPath The path of the item to be removed.
390    * @throws PathNotFoundException if no <code>Item</code> exists at
391    * <code>relPath</code>.
392    * @throws RepositoryException if another error occurs.
393    */

394   public void remove(String JavaDoc relPath) throws PathNotFoundException, RepositoryException;
395
396   /**
397    * Validates and (if validation succeeds) persists all changes to this node
398    * made via the ticket through which this <code>Node</code> object was
399    * acquired.
400    * <p/>
401    * If <code>shallow</code> is <code>false</code> then all pending changes
402    * to this node and all its descendants are validated and (if validation
403    * succeeds) persisted.
404    * <p/>
405    * If <code>shallow</code> is <code>true</code> then pending changes to
406    * this node only are validated and (if validation succeeds) persisted.
407    * The changes persisted are:
408    * <ul>
409    * <li>New properties added to this node.
410    * <li>Changes to values of existing properties of this node
411    * <li>Removal of properties from this node
412    * <li>Removal of child nodes from this node
413    * </ul>
414    * <p/>
415    * Constraints mandated by node types are validated on save. If validation
416    * fails a <code>ConstraintViolationException</code> is thrown and the
417    * state of the transient storage is left unaffected.
418    * <p/>
419    * An <code>AccessDeniedException</code> will be thrown if an attempt is
420    * made to save changes for which the current ticket does not have sufficient
421    * access rights.
422    * <p/>
423    * Throws an <code>ActionVetoedException</code> If a <code>VetoableEventListener</code>
424    * vetoes one of the changes being saved.
425    * <p/>
426    * If save succeeds then the changes persisted are removed from the cache
427    * of pending changes in the ticket.
428    *
429    * @param shallow a boolean. If <code>false</code> then this node and its
430    * subtrree is saved. If <code>true</code> then only this node is saved.
431    * @throws ConstraintViolationException If any of the changes would
432    * violate a constraint as defined by the node type of the respective node.
433    * @throws AccessDeniedException If the current ticket does not have
434    * sufficient access rights to complete the operation.
435    * @throws ActionVetoedException If a <code>VetoableEventListener</code>
436    * vetoes one of the changes being saved.
437    * @throws RepositoryException If another error occurs.
438    */

439   public void save(boolean shallow) throws AccessDeniedException, ConstraintViolationException, ActionVetoedException, RepositoryException;
440
441   /**
442    * Returns the node at <code>relPath</code> relative to <code>this</code> node.
443    * The properties and child nodes of the returned node can then be read
444    * (and if permissions allow) changed and written. However, any changes
445    * made to this node, its properties or its child nodes
446    * (and their properties and child nodes, etc.) will only be persisted to
447    * the repository upon calling save. Within the scope of a single
448    * <code>Ticket</code> object, if a node has been acquired with
449    * <code>getNode</code>, any subsequent call of <code>getNode</code>
450    * re-acquiring the same node will return a reference to same object,
451    * not a new copy.
452    *
453    * @param relPath The relative path of the node to retrieve.
454    * @return The node at <code>relPath</code>.
455    * @throws PathNotFoundException If no node exists at the
456    * specified path.
457    * @throws RepositoryException If another error occurs.
458    */

459   public Node getNode(String JavaDoc relPath) throws PathNotFoundException, RepositoryException;
460
461   /**
462    * Returns a <code>NodeIterator</code> over all child <code>Node</code>s of
463    * this <code>Node</code>. Does <i>not</i> include properties of this
464    * <code>Node</code>. The same <code>save</code> and re-acquisition
465    * semantics apply as with <code>{@link #getNode(String)}</code>.
466    *
467    * @return A <code>NodeIterator</code> over all child <code>Node</code>s of
468    * this <code>Node</code>.
469    * @throws RepositoryException If an unexpected error occurs.
470    */

471   public NodeIterator getNodes() throws RepositoryException;
472
473   /**
474    * Gets all child nodes of this node that match <code>namePattern</code>.
475    * The pattern may be a full name or a partial name with one or more
476    * wildcard characters ("<code>*</code>"), or a disjunction (using the
477    * "<code>|</code>" character to represent logical <code>OR</code>) of
478    * these. For example,
479    * <p/>
480    * <code>N.getNodes("jcr:* | myapp:report")</code>
481    * <p/>
482    * would return a <code>NodeIterator</code> holding all child nodes of
483    * <code>N</code> that are either called <code>myapp:report</code> or begin
484    * with the prefix <code>jcr:</code>. The pattern does not represent paths,
485    * that is, it may not contain <code>/</code> characters.
486    * <p/>
487    * The same <code>save</code> and re-acquisition
488    * semantics apply as with <code>{@link #getNode(String)}</code>.
489    *
490    * @param namePattern a name pattern
491    * @return a <code>NodeIterator</code>
492    * @throws RepositoryException If an unexpected error occurs.
493    */

494   public NodeIterator getNodes(String JavaDoc namePattern) throws RepositoryException;
495
496   /**
497    * Returns the property at <code>relPath</code> relative to <code>this</code>
498    * node. The same <code>save</code> and re-acquisition
499    * semantics apply as with <code>{@link #getNode(String)}</code>.
500    *
501    * @param relPath The relative path of the property to retrieve.
502    * @return The property at <code>relPath</code>.
503    * @throws PathNotFoundException If no property exists at the
504    * specified path.
505    * @throws RepositoryException If another error occurs.
506    */

507   public Property getProperty(String JavaDoc relPath) throws PathNotFoundException, RepositoryException;
508
509   /**
510    * Returns all properties of this node.
511    * Returns a <code>PropertyIterator</code> over all properties
512    * of this node. Does <i>not</i> include child <i>nodes</i> of this
513    * node. The same <code>save</code> and re-acquisition
514    * semantics apply as with <code>{@link #getNode(String)}</code>.
515    *
516    * @return A <code>PropertyIterator</code>.
517    * @throws RepositoryException If an error occurs.
518    */

519   public PropertyIterator getProperties() throws RepositoryException;
520
521   /**
522    * Gets all properties of this node that match <code>namePattern</code>.
523    * The pattern may be a full name or a partial name with one or more
524    * wildcard characters ("<code>*</code>"), or a disjunction (using the
525    * "<code>|</code>" character to represent logical <code>OR</code>) of
526    * these. For example,
527    * <p/>
528    * <code>N.getProperties("jcr:* | myapp:name")</code>
529    * <p/>
530    * would return a <code>PropertyIterator</code> holding all properties of
531    * <code>N</code> that are either called <code>myapp:name</code> or begin
532    * with the prefix <code>jcr:</code>. The pattern does not represent paths,
533    * that is, it may not contain <code>/</code> characters.
534    * <p/>
535    * The same <code>save</code> and re-acquisition
536    * semantics apply as with <code>{@link #getNode(String)}</code>.
537    *
538    * @param namePattern a name pattern
539    * @return a <code>PropertyIterator</code>
540    * @throws RepositoryException If an unexpected error occurs.
541    */

542   public PropertyIterator getProperties(String JavaDoc namePattern) throws RepositoryException;
543
544   /**
545    * Returns the first property of <i>this</i> node found with the specified value.
546    * What makes a particular property "first" (that is, the search order) is
547    * implementaion dependent. If the specified value and the value of a
548    * property are of different types then a conversion is attempted before the
549    * equality test is made. Returns <code>null</code> if no such property is
550    * found. In the case of multivalue properties, a property qualifies as
551    * having the specified value if and only if at least one of its values matches.
552    * The same <code>save</code> and re-acquisition
553    * semantics apply as with <code>{@link #getNode(String)}</code>.
554    *
555    * @param value A <code>Value</code> object.
556    * @return The first property of <i>this</i> node found with the specified value.
557    * @throws RepositoryException If an unexpected error occurs.
558    */

559   public Property findProperty(Value value) throws RepositoryException;
560
561   /**
562    * Returns all properties of <i>this</i> node with the specified value.
563    * If the spedified value and the value of a property are of different types
564    * then a conversion is attempted before the equality test is made. Returns
565    * an empty iterator if no such property could be found. In the case of
566    * multivalue properties, a property qualifies as having the specified value
567    * if and only if at least one of its values matches.
568    * The same <code>save</code> and re-acquisition
569    * semantics apply as with <code>{@link #getNode(String)}</code>.
570    *
571    * @param value A <code>Value</code> object.
572    * @return A PropertyIterator holding all properties of this node with the
573    * specified value. Returns an empty iterator if no such property could be found.
574    * @throws RepositoryException If an unexpected error occurs.
575    */

576   public PropertyIterator findProperties(Value value) throws RepositoryException;
577
578   /**
579    * Returns the deepest primary child item accessible via a chain of
580    * primary child items from this node.
581    * A node's type can specifiy a maximum of one of
582    * its child items (child node or property) as its <i>primary child item</i>.
583    * This method traverses the chain of primary child items of this node
584    * until it either encounters a property or encounters a node that does not
585    * have a primary child item. It then returns that property or node. If
586    * this node itself (the one that this method is being called on) has no
587    * primary child item then this method throws a
588    * <code>ItemNotFoundException</code>. The same <code>save</code> and re-acquisition
589    * semantics apply as with <code>{@link #getNode(String)}</code>.
590    *
591    * @return the deepest primary child item accessible from this node via
592    * a chain of primary child items.
593    * @throws ItemNotFoundException if this node does not have a primary
594    * child item.
595    * @throws RepositoryException If another error occurs.
596    */

597   public Item getPrimaryItem() throws ItemNotFoundException, RepositoryException;
598
599   /**
600    * Returns the UUID of this node as recorded in the node's jcr:UUID
601    * property. This method only works on nodes of mixin node type
602    * <code>mix:referenceable</code>. On nonreferenceable nodes, this method
603    * throws an <code>UnsupportedRepositoryOperationException</code>.
604    *
605    * @return the UUID of this node
606    * @throws UnsupportedRepositoryOperationException
607    * If this node nonreferenceable.
608    * @throws RepositoryException If another error occurs.
609    */

610   public String JavaDoc getUUID() throws UnsupportedRepositoryOperationException, RepositoryException;
611
612   /**
613    * Indicates whether a node exists at <code>relPath</code>
614    * Returns <code>true</code> if a node exists at <code>relPath</code> and
615    * <code>false</code> otherwise.
616    *
617    * @param relPath The path of a (possible) node.
618    * @return <code>true</code> if a node exists at <code>relPath</code>;
619    * <code>false</code> otherwise.
620    * @throws RepositoryException If an unspecified error occurs.
621    */

622   public boolean hasNode(String JavaDoc relPath) throws RepositoryException;
623
624   /**
625    * Indicates whether a property exists at <code>relPath</code>
626    * Returns <code>true</code> if a property exists at <code>relPath</code> and
627    * <code>false</code> otherwise.
628    *
629    * @param relPath The path of a (possible) property.
630    * @return <code>true</code> if a property exists at <code>relPath</code>;
631    * <code>false</code> otherwise.
632    * @throws RepositoryException If an unspecified error occurs.
633    */

634   public boolean hasProperty(String JavaDoc relPath) throws RepositoryException;
635
636   /**
637    * Indicates whether this node has child nodes.
638    * Returns <code>true</code> if this node has one or more child nodes;
639    * <code>false</code> otherwise.
640    *
641    * @return <code>true</code> if this node has one or more child nodes;
642    * <code>false</code> otherwise.
643    * @throws RepositoryException If an unspecified error occurs.
644    */

645   public boolean hasNodes() throws RepositoryException;
646
647   /**
648    * Indicates whether this node has properties.
649    * Returns <code>true</code> if this node has one or more properties;
650    * <code>false</code> otherwise.
651    *
652    * @return <code>true</code> if this node has one or more properties;
653    * <code>false</code> otherwise.
654    * @throws RepositoryException If an unspecified error occurs.
655    */

656   public boolean hasProperties() throws RepositoryException;
657
658   /**
659    * Returns the primary node type of this node.
660    *
661    * @return a <code>NodeType</code> object.
662    */

663   public NodeType getPrimaryNodeType();
664
665   /**
666    * Returns an array of NodeType objects representing the mixin node types
667    * assigned to this node.
668    *
669    * @return a <code>NodeType</code> object.
670    */

671   public NodeType[] getMixinNodeTypes();
672
673   /**
674    * Indicates whether this node is of the specified node type.
675    * Returns <code>true</code> if this node is of the specified node type
676    * or a subtype of the specified node type. Returns <code>false</code> otherwise.
677    * This method provides a quick method for determining whether
678    * a particular node is of a particular type without having to
679    * manually search the inheritance hierarchy (which, in some implementations
680    * may be a multiple-inhertiance hierarchy, making a manual search even
681    * more complex). This method works for both perimary node types and mixin
682    * node types.
683    *
684    * @param nodeTypeName the name of a node type.
685    * @return true if this node is of the specified node type
686    * or a subtype of the specified node type; returns false otherwise.
687    * @throws RepositoryException If an unspecified error occurs.
688    */

689   public boolean isNodeType(String JavaDoc nodeTypeName) throws RepositoryException;
690
691   /**
692    * Adds the specified mixin node type to this node. If a conflict with
693    * another assigned mixin or the main node type results, then an exception
694    * is thrown on save. Adding a mixin node type to a node immediately adds
695    * the name of that type to the list held in that node’s
696    * <code>jcr:mixinTypes</code> property.
697    *
698    * @param mixinName
699    */

700   public void addMixin(String JavaDoc mixinName);
701
702   /**
703    * Returns the definition of <i>this</i> <code>Node</code>. This method is
704    * actually a shortcut to searching through this node's parent's node type
705    * (and its supertypes) for the child node definition applicable to this
706    * node.
707    *
708    * @return a <code>NodeDef</code> object.
709    * @see NodeType#getChildNodeDefs
710    */

711   public NodeDef getDefinition();
712
713   /**
714    * Creates a new version with a system generated version name and returns that version.
715    *
716    * @return a <code>Version</code> object
717    * @throws UnsupportedRepositoryOperationException
718    * if versioning is not supported.
719    * @throws RepositoryException If another error occurs.
720    */

721   public Version checkin() throws UnsupportedRepositoryOperationException, RepositoryException;
722
723   /**
724    * Sets this versionable node to checked-out status by setting its
725    * <code>jcr:isCheckedOut</code> property to true.
726    *
727    * @throws UnsupportedRepositoryOperationException
728    * if versioning is not supported.
729    * @throws RepositoryException If another error occurs.
730    */

731   public void checkout() throws UnsupportedRepositoryOperationException, RepositoryException;
732
733   /**
734    * Updates this node to reflect the state (i.e., have the same properties
735    * and child nodes) of this node's corresponding node in srcWorkspace (that
736    * is, the node in srcWorkspace with the same UUID as this node). If
737    * shallow is set to false, then only this node is updated. If shallow is
738    * set to true then every node with a UUID in the subtree rooted at this
739    * node is updated. If the current ticket does not have sufficient rights
740    * to perform the update or the specified workspace does not exist, a
741    * <code>NoSuchWorkspaceException</code> is thrown. If another error occurs
742    * then a RepositoryException is thrown. If the update succeeds the changes
743    * made to this node are persisted immediately, there is no need to call
744    * save.
745    *
746    * @param srcWorkspaceName the name of the source workspace.
747    * @param shallow a boolean
748    * @throws RepositoryException If another error occurs.
749    */

750   public void update(String JavaDoc srcWorkspaceName, boolean shallow) throws NoSuchWorkspaceException, RepositoryException;
751
752   /**
753    * Performs the same function as update (above) with one restriction:
754    * merge only succeeds if the base version of the corresponding node in
755    * <code>srcWorkspace</code> is a successor (or a successor of a successor, etc., to
756    * any degree of separation) of the base version of this node. Otherwise,
757    * the operation throws a <code>MergeException</code>. In repositories that
758    * do not support versioning, <code>merge</code> throws an
759    * <code>UnsupportedRepositoryOperationException</code>. If the current
760    * ticket does not have sufficient rights to perform the <code>merge</code> or the
761    * specified workspace does not exist, a <code>NoSuchWorkspaceException</code> is thrown.
762    * If the <code>merge</code> succeeds, the changes made to this node are
763    * persisted immediately, there is no need to call <code>save</code>.
764    *
765    * @param srcWorkspace the name of the source workspace.
766    * @param shallow a boolean
767    * @throws UnsupportedRepositoryOperationException
768    * if versioning is not supported.
769    * @throws MergeException succeeds if the base version of the corresponding
770    * node in srcWorkspace is not a successor of the base version of this node.
771    * @throws NoSuchWorkspaceException If the current
772    * ticket does not have sufficient rights to perform the <code>merge</code> or the
773    * specified workspace does not exist.
774    * @throws RepositoryException If another error occurs.
775    */

776   public void merge(String JavaDoc srcWorkspace, boolean shallow) throws UnsupportedRepositoryOperationException, NoSuchWorkspaceException, MergeException, RepositoryException;
777
778   /**
779    * Returns <code>true</code> if this node is currently checked-out and <code>false</code> otherwise.
780    *
781    * @return a boolean
782    * @throws UnsupportedRepositoryOperationException
783    * if versioning is not supported.
784    * @throws RepositoryException If another error occurs.
785    */

786   public boolean isCheckedOut() throws UnsupportedRepositoryOperationException, RepositoryException;
787
788   /**
789    * Restores this node to the state recorded in the specified version.
790    *
791    * @param versionName
792    * @throws UnsupportedRepositoryOperationException
793    * if versioning is not supported.
794    * @throws RepositoryException If another error occurs.
795    */

796   public void restore(String JavaDoc versionName) throws UnsupportedRepositoryOperationException, RepositoryException;
797
798   /**
799    * Restores this node to the state recorded in the specified version.
800    *
801    * @param version a <code>Version</code> object
802    * @throws UnsupportedRepositoryOperationException
803    * if versioning is not supported.
804    * @throws RepositoryException If another error occurs.
805    */

806   public void restore(Version version) throws UnsupportedRepositoryOperationException, RepositoryException;
807
808   /**
809    * Restores this node to the state recorded in the version corresponding to the specified date.
810    *
811    * @param date a <codeCalendar</code> object
812    * @throws UnsupportedRepositoryOperationException
813    * if versioning is not supported.
814    * @throws RepositoryException If another error occurs.
815    */

816   public void restore(Calendar JavaDoc date) throws UnsupportedRepositoryOperationException, RepositoryException;
817
818   /**
819    * Restores this node to the state recorded in the version specified by
820    * <code>versionLabel</code>.
821    *
822    * @param versionLabel a String
823    * @throws UnsupportedRepositoryOperationException
824    * if versioning is not supported.
825    * @throws RepositoryException If another error occurs.
826    */

827   public void restoreByLabel(String JavaDoc versionLabel) throws UnsupportedRepositoryOperationException, RepositoryException;
828
829   /**
830    * Returns the <code>VersionHistory</code> object of this node. This object
831    * is simply a wrapper for the <code>nt:versionHistory</code> node holding
832    * this node's versions.
833    *
834    * @return a <code>VersionHistory</code> object
835    * @throws UnsupportedRepositoryOperationException
836    * if versioning is not supported.
837    * @throws RepositoryException If another error occurs.
838    */

839   public VersionHistory getVersionHistory() throws UnsupportedRepositoryOperationException, RepositoryException;
840
841   /**
842    * Returns the current base version of this versionable node.
843    *
844    * @return a <code>Version</code> object.
845    * @throws UnsupportedRepositoryOperationException
846    * if versioning is not supported.
847    * @throws RepositoryException If another error occurs.
848    */

849   public Version getBaseVersion() throws UnsupportedRepositoryOperationException, RepositoryException;
850 }
Popular Tags