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   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   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 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags