KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > jcr > Item


1 /*
2  * $Id: Item.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.lock.Lock;
28
29 /**
30  * The <code>Item</code> is the base interface of <code>{@link Node}</code>
31  * and <code>{@link Property}</code>.
32  *
33  * @author Peeter Piegaze
34  * @author Stefan Guggisberg
35  */

36 public interface Item {
37
38   /**
39    * Returns the path to this <code>Item</code>.
40    * If this item or an ancestor has multiple parents then this item will
41    * have more than one path. In that case, this method returns one of those
42    * paths. The mechanism by which the implementation chooses which path to
43    * return is left unspecified, the only requirement being that for a given
44    * <code>Item</code> this method always returns the same path. To get all
45    * paths to this <code>Item</code> use <code>{@link #getPaths()}</code>.
46    *
47    * @return the path (or one of the paths) of this <code>Item</code>.
48    */

49   public String JavaDoc getPath();
50
51   /**
52    * Returns all paths to this <code>Item</code>.
53    *
54    * @return An array of strings: all paths that lead to this
55    * <code>Item</code>.
56    */

57   public StringIterator getPaths();
58
59   /**
60    * Returns the name of this <code>Item</code>.
61    * The name is the last item in the path. If this <code>Item</code>
62    * is the root node of the repository (i.e. if
63    * <code>this.getDepth() == 0</code>), an empty string will be returned.
64    * <p/>
65    * If this item has multple paths then the name returned
66    * is the last item in the path returned by <code>{@link #getPath()}</code>.
67    *
68    * @return the (or a) name of this <code>Item</code> or an empty string
69    * if this <code>Item</code> is the root node.
70    */

71   public String JavaDoc getName();
72
73   /**
74    * Returns the ancestor of the specified absolute degree.
75    * An ancestor of
76    * absolute degree <i>x</i> is the <code>Item</code> that is <i>x</i>
77    * levels down along the path from the root node to <i>this</i>
78    * <code>Item</code>.
79    * <ul>
80    * <li><i>degree</i> = 0 returns the root node.
81    * <li><i>degree</i> = 1 returns the child of the root node along the path
82    * to <i>this</i> <code>Item</code>.
83    * <li><i>degree</i> = 2 returns the grandchild of the root node along the
84    * path to <i>this</i> <code>Item</code>.
85    * <li>And so on to <i>degree</i> = <i>n</i>, where <i>n</i> is the depth
86    * of <i>this</i> <code>Item</code>, which returns <i>this</i>
87    * <code>Item</code> itself.
88    * </ul>
89    * If <i>degree</i> &gt; <i>n</i> is specified then a
90    * <code>ItemNotFoundException</code> is thrown.
91    * <p/>
92    * If multiple paths exist to this
93    * <code>Item</code> then the path used is the same one that is returned
94    * by <code>{@link #getPath()}</code>.
95    *
96    * @param degree An integer, 0 &lt;= <i>degree</i> &lt;= <i>n</i> where <i>n</i> is the depth
97    * of <i>this</i> <code>Item</code> along the path returned by
98    * <code>{@link #getPath()}</code>.
99    * @return The ancestor of the specified absolute degree of this
100    * <code>Item</code> along the path returned by
101    * <code>{@link #getPath()}</code>.
102    * @throws ItemNotFoundException if <i>degree</i> &lt; 0 or
103    * <i>degree</i> &gt; <i>n</i> where <i>n</i> is the is the depth of
104    * <i>this</i> <code>Item</code> along the path returned by
105    * <code>{@link #getPath()}</code>.
106    * @throws AccessDeniedException if the current ticket does not have
107    * sufficient access rights to complete the operation.
108    * @throws RepositoryException if another error occurs.
109    */

110   public Item getAncestor(int degree) throws ItemNotFoundException, AccessDeniedException, RepositoryException;
111
112   /**
113    * Returns the parent of this <code>Item</code>.
114    * If this <code>Item</code> has multiple paths then this method returns
115    * the parent along the path returned by <code>{@link #getPath()}</code>.
116    *
117    * @return The parent of this <code>Item</code> along the path returned
118    * by <code>{@link #getPath()}</code>.
119    * @throws ItemNotFoundException if there is no parent. This only happens
120    * if <i>this</i> <code>Item</code> is the root node.
121    * @throws AccessDeniedException if the current ticket does not have
122    * sufficient access rights to complete the operation.
123    * @throws RepositoryException if another error occurs.
124    */

125   public Node getParent() throws ItemNotFoundException, AccessDeniedException, RepositoryException;
126
127   /**
128    * Returns all parents of this <code>Item</code>.
129    *
130    * @return An iterator over the parents of this <code>Item</code>.
131    * @throws ItemNotFoundException if there is no parent. This only happens
132    * if <i>this</i> <code>Item</code> is the root.
133    * @throws AccessDeniedException if the current ticket does not have
134    * sufficient access rights to complete the operation.
135    * @throws RepositoryException if another error occurs.
136    */

137   public NodeIterator getParents() throws ItemNotFoundException, AccessDeniedException, RepositoryException;
138
139   /**
140    * Returns the <code>Ticket</code> through which this <code>Item</code>
141    * was acquired.
142    * Every <code>Item</code> can ultimately be traced back through a series
143    * of method calls to the call <code>{@link Ticket#getRootNode}</code>,
144    * <code>{@link Ticket#getNodeByAbsPath}</code> or
145    * <code>{@link Ticket#getNodeByUUID}</code>. This method returns that
146    * <code>Ticket</code> object.
147    *
148    * @return the <code>Tickete</code> through which this <code>Item</code> was
149    * acquired.
150    */

151   public Ticket getTicket();
152
153   /**
154    * Accepts an <code>ItemVistor</code>.
155    * Calls the appropriate <code>ItemVistor</code>
156    * <code>visit</code> method of the according to whether <i>this</i>
157    * <code>Item</code> is a <code>Node</code> or a <code>Property</code>.
158    *
159    * @param visitor The ItemVisitor to be accepted.
160    * @throws RepositoryException if an error occurs.
161    */

162   public void accept(ItemVisitor visitor) throws RepositoryException;
163
164   /**
165    * Indicates whether this <code>Item</code> is a <code>Node</code> or a
166    * <code>Property</code>.
167    * Returns <code>true</code> if this <code>Item</code> is a <code>Node</code>;
168    * Returns <code>false</code> if this <code>Item</code> is a <code>Property</code>.
169    *
170    * @return <code>true</code> if this <code>Item</code> is a
171    * <code>Node</code>, <code>false</code> if it is a <code>Property</code>.
172    */

173   public boolean isNode();
174
175   /**
176    * Returns the status of this <code>Item</code> regarding
177    * the specified permissions.
178    * Returns the status of this <code>Item</code> regarding
179    * the specified <code>permissions</code> (under the rights held by current
180    * ticket). See <code>{@link javax.jcr.access.Permission}</code> and
181    * <code>{@link javax.jcr.access.AccessManager}</code> for more details. Equivalent to
182    * <code>AccessManager.isGranted(<b>this</b>, permissions)</code>.
183    *
184    * @param permissions A combination of one or more of the following constants
185    * encoded as a bitmask value:
186    * <ul>
187    * <li><code>Permission.ADD_NODE</code></li>
188    * <li><code>Permission.SET_PROPERTY</code></li>
189    * <li><code>Permission.REMOVE_ITEM</code></li>
190    * <li><code>Permission.READ_ITEM</code></li>
191    * </ul>
192    * See <code>{@link javax.jcr.access.Permission}</code>.
193    * @return <code>true</code> if all requested permissions are true for this
194    * <code>Item</code>; <code>false</code> otherwise.
195    * @throws UnsupportedRepositoryOperationException
196    * if access control
197    * discovery is not supported.
198    * @throws RepositoryException if another error occurs.
199    */

200   public boolean isGranted(long permissions) throws UnsupportedRepositoryOperationException, RepositoryException;
201
202   /**
203    * Returns the depth of this <code>Item</code> in the repository tree.
204    * Returns the depth below the root node of <i>this</i> <code>Item</code>
205    * (counting <i>this</i> <code>Item</code> itself).
206    * <ul>
207    * <li>The root node returns 0.
208    * <li>A property or child node of the root node returns 1.
209    * <li>A property or child node of a child node of the root returns 2.
210    * <li>And so on to <i>this</i> <code>Item</code>.
211    * </ul>
212    * If multiple paths exist to this
213    * <code>Item</code> then the path used to determine the depth is the
214    * same one that is returned by <code>{@link #getPath()}</code>.
215    *
216    * @return The depth of this <code>Item</code> in the repository hierarchy.
217    */

218   public int getDepth();
219
220   /**
221    * Places a lock on this node, or throws an
222    * <code>UnsupportedRepositoryOperationException</code> if locking is
223    * not supported.
224    * <p/>
225    * Puts a lock on this item.
226    * <p/>
227    * If <code>recurse</code> is <code>true</code> then a lock is also placed
228    * on all descendants of this item. If <code>false</code> then only this
229    * item is locked.
230    * <p/>
231    * If <code>shared</code> is <code>true</code> then this lock is
232    * a shared lock. If <code>false</code> then it is an exclusive lock.
233    * <p/>
234    * The lock is of the specified <code>lockType</code>. This standard
235    * defines only one type, <code>LockType.WRITE_LOCK</code>, though more can
236    * be added by the implementation, see <code>{@link javax.jcr.lock.LockType LockType}</code> for the
237    * semantics specific to this lock type.
238    * <p/>
239    * <b>General points about locking</b>
240    * <p/>
241    * Locking is an optional part of the specification. If locking is not
242    * supported then this method will throw an
243    * <code>UnsupportedRepositoryOperationException</code>, even in a level 2
244    * implementation.
245    * <p/>
246    * Even if locking is supported, the features of a particular
247    * implementation can vary along the following dimensions:
248    * <dl>
249    * <dt>Lock Type</dt>
250    * <dd>Only WRITE_LOCK is defined by this standard. An implementation may
251    * define other lock types.</dd>
252    * <dt>Lock Scope</dt>
253    * <dd>An implementation may choose to implement exclusive locks, shared
254    * locks or both.</dd>
255    * <dt>Lock Level</dt>
256    * <dd>An implementation may choose to implement locking on
257    * nodes only or on both nodes and properties. If the implementation locks
258    * only on the node level this is equivalent to a
259    * "both nodes and properties" locking implementaion in which locking or
260    * unlocking a node automatically performs the same operation on all its
261    * properties.</dd>
262    * </dl>
263    * Information about what locking support is provided is available via
264    * the method <code>{@link Workspace#getLockCapabilities()}</code> which returns
265    * a <code>{@link javax.jcr.lock.LockCapabilities LockCapabilities}</code> object which provides methods for
266    * querying the locking support provided by the implementation.
267    *
268    * @param recurse if <code>true</code> set locks on all descendants also.
269    * @param shared Whether the lock is shared or exclusive
270    * @param lockType The type of the lock
271    * @return The Lock object.
272    * @throws AccessDeniedException If the user
273    * ticket does not have the right to lock this user <i>or</i> does have
274    * the right to lock this node but an exclusive lock is already held by
275    * another user.
276    * @throws UnsupportedRepositoryOperationException
277    * If the lock type or
278    * <code>shared</code> status is not supported in this
279    * implementation or locking in general is not supported.
280    * @throws RepositoryException if another error occurs.
281    */

282   public Lock lock(boolean recurse, boolean shared, int lockType) throws UnsupportedRepositoryOperationException, AccessDeniedException, RepositoryException;
283
284   /**
285    * Removes the specified lock from this node or throws an
286    * <code>UnsupportedRepositoryOperationException</code> if locking is not
287    * supported.
288    * <p/>
289    * If this node is not locked, then this method has no effect.
290    * If this node is locked and the user of this ticket is a user of the
291    * lock then the lock is removed. If this node is locked but the user of
292    * this ticket does not have the power to unlock it, then an
293    * <code>AccessDeniedException</code> is thrown.
294    *
295    * @throws AccessDeniedException In level 1: Never. In level 2: If the user
296    * of this ticket does not have the right to unlock this node.
297    * @throws UnsupportedRepositoryOperationException
298    * If locking in general is not supported.
299    */

300   public void unlock(Lock lock) throws UnsupportedRepositoryOperationException, AccessDeniedException;
301
302   /**
303    * Returns all locks on this node or throws an
304    * <code>UnsupportedRepositoryOperationException</code> if locking is not
305    * supported.
306    * <p/>
307    * Returns all locks on this node, if there are any, otherwise returns
308    * <code>null</code>.
309    *
310    * @return The locks on this node
311    * @throws UnsupportedRepositoryOperationException
312    * If locking in general is not supported.
313    */

314   public Lock[] getLocks() throws UnsupportedRepositoryOperationException;
315
316   /**
317    * Returns <code>true</code> if there is a lock on this node, false
318    * otherwise.
319    *
320    * @return a boolean.
321    */

322   public boolean hasLocks();
323
324   /**
325    * Returns <code>true</code> if <code>this</code> <code>Item</code>
326    * (the Java object) represents the same repository item as the Java
327    * object <code>otherItem</code>.
328    * <p/>
329    * In some implementations the results of <code>Item.isIdentical</code>
330    * and <code>Object.equals</code> will not always be the same. Therefore,
331    * in general, clients of the API cannot rely on <code>Object.equals</code>
332    * to test for identity of repository items and must use this method.
333    *
334    * @param otherItem the item to be tested for identity with
335    * <code>this</code>.
336    * @return a <code>boolean</code>.
337    */

338   public boolean isIdentical(Item otherItem);
339 }
Popular Tags