KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > slide > structure > Structure


1 /*
2  * $Header: /home/cvs/jakarta-slide/src/share/org/apache/slide/structure/Structure.java,v 1.18 2004/07/28 09:34:35 ib Exp $
3  * $Revision: 1.18 $
4  * $Date: 2004/07/28 09:34:35 $
5  *
6  * ====================================================================
7  *
8  * Copyright 1999-2002 The Apache Software Foundation
9  *
10  * Licensed under the Apache License, Version 2.0 (the "License");
11  * you may not use this file except in compliance with the License.
12  * You may obtain a copy of the License at
13  *
14  * http://www.apache.org/licenses/LICENSE-2.0
15  *
16  * Unless required by applicable law or agreed to in writing, software
17  * distributed under the License is distributed on an "AS IS" BASIS,
18  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19  * See the License for the specific language governing permissions and
20  * limitations under the License.
21  *
22  */
23
24 package org.apache.slide.structure;
25
26 import java.util.Enumeration JavaDoc;
27 import java.util.List JavaDoc;
28 import org.apache.slide.common.ServiceAccessException;
29 import org.apache.slide.common.SlideToken;
30 import org.apache.slide.lock.ObjectLockedException;
31 import org.apache.slide.security.AccessDeniedException;
32 import org.apache.slide.event.VetoException;
33
34 /**
35  * Structure helper.
36  * Provides methods to manage and navigate the hierarchy of nodes in a
37  * namespace.
38  *
39  * @version $Revision: 1.18 $
40  */
41 public interface Structure {
42     
43     
44     // ------------------------------------------------------ Interface Methods
45
46     /**
47      * Generates an URI that is guranteed to be unqiue globally.
48      * If this is not possible <code>null</code> will be returned.
49      *
50      * @param token the slide token
51      * @param parentUri the parent of the unique URI that shall be created
52      *
53      * @return a globally unique URI or <code>null</code> if not possible
54      *
55      * @exception ServiceAccessException low level service access exception
56      */
57     String JavaDoc generateUniqueUri(SlideToken token, String JavaDoc parentUri) throws ServiceAccessException;
58     
59     /**
60      * Returns the children of a node.
61      *
62      * @param token the slide token
63      * @param object the node
64      *
65      * @return Enumeration of ObjectNode objects
66      *
67      * @exception ServiceAccessException low level service access exception
68      * @exception ObjectNotFoundException one of the children specified
69      * by the object was not found
70      * @exception LinkedObjectNotFoundException cannot happen
71      *
72      * @see org.apache.slide.structure.ObjectNode#enumerateChildren()
73      */
74     Enumeration JavaDoc getChildren(SlideToken token, ObjectNode object)
75         throws ServiceAccessException, ObjectNotFoundException,
76         LinkedObjectNotFoundException, VetoException;
77     
78     
79     /**
80      * Returns the parent of a node.
81      *
82      * @param token the slide token
83      * @param object the node
84      *
85      * @return the node's parent, or <code>null</code> if the object specified
86      * is the root node of the namespace
87      *
88      * @exception ServiceAccessException low level service access exception
89      * @exception ObjectNotFoundException the parent object specified
90      * by the object was not found
91      * @exception LinkedObjectNotFoundException cannot happen (a link
92      * cannot have children)
93      * @exception AccessDeniedException credentials token does not
94      * have permission to perform the action
95      *
96      * @see org.apache.slide.structure.ObjectNode#enumerateChildren()
97      */
98     ObjectNode getParent(SlideToken token, ObjectNode object)
99         throws ServiceAccessException, ObjectNotFoundException,
100         LinkedObjectNotFoundException, AccessDeniedException, VetoException;
101     
102     /**
103      * Return all parents of this object node. If pathOnly=true, only parents
104      * on the path of the specified ObjectNode are returned, all parents (binding!)
105      * otherwise. If storeOnly=true, only parents within the scope of the store
106      * in charge of the specified ObjectNode are returned, parents up to the root
107      * ObjectNode (uri="/") otherwise.
108      *
109      * @param token a SlideToken
110      * @param object an ObjectNode
111      * @param pathOnly if true, only parents on the path of the specified
112      * ObjectNode are returned, all parents (binding!)
113      * otherwise
114      * @param storeOnly if true, only parents within the scope of the store
115      * in charge of the specified ObjectNode are returned,
116      * parents up to the root ObjectNode (uri="/") otherwise
117      * @param includeSelf if true, the ObjectNode specified by object is included,
118      * otherwise, it is excluded
119      *
120      * @return a List of ObjectNode instances
121      *
122      * @throws ServiceAccessException
123      * @throws ObjectNotFoundException
124      * @throws LinkedObjectNotFoundException
125      * @throws AccessDeniedException
126      *
127      */
128     List JavaDoc getParents(SlideToken token, ObjectNode object, boolean pathOnly, boolean storeOnly, boolean includeSelf)
129         throws ServiceAccessException, ObjectNotFoundException,
130         LinkedObjectNotFoundException, AccessDeniedException, VetoException;
131     
132     /**
133      * Retrieves a node by URI, following any links.
134      *
135      * @param token the slide token
136      * @param strUri the URI of the object to retrieve
137      *
138      * @return the node specified by the URI or the node linked to by the node
139      * at the URI.
140      *
141      * @exception ServiceAccessException low level service access exception
142      * @exception ObjectNotFoundException if no node exists at the URI
143      * @exception LinkedObjectNotFoundException A link object encountered
144      * during URI resolution doesn't have a valid target
145      * @exception AccessDeniedException credentials token does not have
146      * permission to perform the action
147      */
148     ObjectNode retrieve(SlideToken token, String JavaDoc strUri)
149         throws ServiceAccessException, ObjectNotFoundException,
150         LinkedObjectNotFoundException, AccessDeniedException, VetoException;
151     
152     
153     /**
154      * Retrieves a node by URI.
155      *
156      * @param token the slide token
157      * @param strUri the URI of the object to retrieve
158      * @param translateLastUriElement if set to true and the URI is
159      * associated with a link, this method will return the target of
160      * the link, otherwise the link itself is returned
161      *
162      * @return the node specified by the URI, or the node linked to by the
163      * node at the URI, if <code>translateLastUriElement</code> is true
164      *
165      * @exception ServiceAccessException low level service access exception
166      * @exception ObjectNotFoundException if no node exists at the URI
167      * @exception LinkedObjectNotFoundException A link object encountered
168      * during URI resolution doesn't have a valid target
169      * @exception AccessDeniedException credentials token does not have
170      * permission to perform the action
171      */
172     ObjectNode retrieve(SlideToken token, String JavaDoc strUri,
173                         boolean translateLastUriElement)
174         throws ServiceAccessException, ObjectNotFoundException,
175         LinkedObjectNotFoundException, AccessDeniedException, VetoException;
176     
177     
178     /**
179      * Creates a new node in the namespace.
180      *
181      * @param token the slide token
182      * @param object the object that should be created
183      * @param strUri location in the namespace where we the object should be
184      * created
185      *
186      * @exception ServiceAccessException low level service access exception
187      * @exception ObjectAlreadyExistException an object already exists
188      * at the specified URI
189      * @exception ObjectNotFoundException Update of the parent object
190      * failed because the parent object does no longer exist.
191      * Should not happen, and indicates a critical error if it does
192      * @exception LinkedObjectNotFoundException retrieval of a link target
193      * failed during URI resolution
194      * @exception AccessDeniedException credentials token does not have
195      * permission to perform the action
196      */
197     void create(SlideToken token, ObjectNode object, String JavaDoc strUri)
198         throws ServiceAccessException, ObjectAlreadyExistsException,
199         ObjectNotFoundException, LinkedObjectNotFoundException,
200         AccessDeniedException, ObjectLockedException, VetoException;
201     
202     
203     /**
204      * Creates a link to another node in the namespace.
205      *
206      * @param token the slide token
207      * @param link the link object that should be created
208      * @param linkUri location in the namespace where the link object should
209      * be created
210      * @param linkedObject target object of the link
211      *
212      * @exception ServiceAccessException Low level service access exception
213      * @exception ObjectAlreadyExistException An object already exist
214      * at the specified URI
215      * @exception ObjectNotFoundException Update of the parent object
216      * failed because the parent object does no longer exist.
217      * Should not happen, and indicate a critical error if it does
218      * @exception LinkedObjectNotFoundException Retrieval of a link target
219      * failed during Uri resolution
220      * @exception AccessDeniedException credentials token does not have
221      * permission to perform the action
222      */
223     void createLink(SlideToken token, LinkNode link, String JavaDoc linkUri,
224                     ObjectNode linkedObject)
225         throws ServiceAccessException, ObjectAlreadyExistsException,
226         ObjectNotFoundException, LinkedObjectNotFoundException,
227         AccessDeniedException, ObjectLockedException, VetoException;
228     
229     
230     /**
231      * Stores/updates an object.
232      *
233      * @param token the slide token
234      * @param object the object to update
235      *
236      * @exception ServiceAccessException low level service access exception
237      * @exception ObjectNotFoundException the update failed because one
238      * object was not found during URI resolution
239      * @exception LinkedObjectNotFoundException retrieval of a link target
240      * failed during URI resolution
241      * @exception AccessDeniedException credentials token does not have
242      * permission to perform the action
243      */
244     void store(SlideToken token, ObjectNode object)
245         throws ServiceAccessException, ObjectNotFoundException,
246         AccessDeniedException, LinkedObjectNotFoundException, VetoException;
247     
248     
249     /**
250      * Removes a node from the namespace.
251      *
252      * @param token the slide token
253      * @param object the node to remove
254      *
255      * @exception ServiceAccessException low level service access exception
256      * @exception ObjectNotFoundException the update failed because an
257      * object was not found during URI resolution
258      * @exception ObjectHasChildrenException removal failed because object
259      * has children
260      * @exception LinkedObjectNotFoundException retrieval of a link target
261      * failed during URI resolution
262      * @exception AccessDeniedException credentials token does not have
263      * permission to perform the action
264      */
265     void remove(SlideToken token, ObjectNode object)
266         throws ServiceAccessException, ObjectNotFoundException,
267         ObjectHasChildrenException, AccessDeniedException,
268         LinkedObjectNotFoundException, ObjectLockedException, VetoException;
269     
270     
271     /**
272      * Modifies the collection identified by <b>collectionNode</b>, by adding a new binding
273      * from the specified segment to the resource identified by <b>sourceNode</b>.
274      *
275      * @param token a SlideToken
276      * @param collectionNode an ObjectNode
277      * @param segment a String
278      * @param sourceNode an ObjectNode
279      *
280      * @throws ServiceAccessException
281      * @throws ObjectNotFoundException
282      * @throws AccessDeniedException
283      * @throws LinkedObjectNotFoundException
284      * @throws ObjectLockedException
285      */
286     void addBinding( SlideToken token, ObjectNode collectionNode, String JavaDoc segment, ObjectNode sourceNode )
287         throws ServiceAccessException, ObjectNotFoundException,
288         AccessDeniedException, LinkedObjectNotFoundException, ObjectLockedException, CrossServerBindingException, VetoException;
289
290     /**
291      * Modifies the collection identified by <b>collectionNode</b>, by removing the binding
292      * for the specified segment.
293      *
294      * @param token a SlideToken
295      * @param collectionNode an ObjectNode
296      * @param segment a String
297      *
298      * @throws ServiceAccessException
299      * @throws ObjectNotFoundException
300      * @throws AccessDeniedException
301      * @throws LinkedObjectNotFoundException
302      * @throws ObjectLockedException
303      *
304      */
305     void removeBinding( SlideToken token, ObjectNode collectionNode, String JavaDoc segment )
306         throws ServiceAccessException, ObjectNotFoundException,
307         AccessDeniedException, LinkedObjectNotFoundException, ObjectLockedException, VetoException;
308 }
309
310
Popular Tags