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  ;
33  import java.util.Calendar  ;
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   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   relPath, String   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   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   absPath, String   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   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   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   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   name, String   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   name, String  [] 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   name, String   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   name, InputStream   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   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   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   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   name, Calendar   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   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   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   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   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   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   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   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   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   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   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   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   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   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   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   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 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags