KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > jcr > Workspace


1 /*
2  * $Id: Workspace.java,v 1.5 2004/08/12 18:13:43 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.access.AccessManager;
28 import javax.jcr.lock.LockCapabilities;
29 import javax.jcr.nodetype.ConstraintViolationException;
30 import javax.jcr.nodetype.NodeTypeManager;
31 import javax.jcr.observation.ObservationManager;
32 import javax.jcr.query.QueryManager;
33
34 import org.xml.sax.ContentHandler JavaDoc;
35 import org.xml.sax.SAXException JavaDoc;
36
37 import java.io.OutputStream JavaDoc;
38 import java.io.IOException JavaDoc;
39
40 /**
41  * Represents a view onto the the content repository
42  * associated with a particular <code>Ticket</code>.
43  * Acquired by calling <code>{@link Ticket#getWorkspace()}</code>.
44  *
45  * @author Peeter Piegaze
46  * @author Stefan Guggisberg
47  */

48 public interface Workspace {
49
50   /**
51    * Returns the <code>Ticket</code> object through which this Workspace
52    * object was acquired.
53    *
54    * @return a <code>{@link Ticket}</code> object.
55    */

56   public Ticket getTicket();
57
58   /**
59    * Copies the node at <code>srcAbsPath</code> to the new location at
60    * <code>destAbsPath</code>.
61    * If <code>shallow</code> is true then only the node at <code>srcAbsPath</code>
62    * and its properties (but not its child nodes) is copied to the new
63    * location, otherwise its entire subtree is copied. Throws an exception if
64    * there is already an item at <code>destAbsPath</code>, or if some other
65    * constraint (access, node type, system-level) is violated. If succesful,
66    * the parent of the new node at <code>destAbsPath</code> is "saved" (i.e. the
67    * change is persisted immediately, there is no need to call
68    * <code>Node.save()</code>).
69    *
70    * @param srcAbsPath the path of the node to be copied.
71    * @param destAbsPath the location to which the node at <code>srcAbsPath</code>
72    * is to be copied.
73    * @param shallow if true only the node at <code>srcAbsPath</code> and its
74    * properties are copied, otherwise the source node and its entire subtree is copied.
75    * @throws ConstraintViolationException if the copy would violate a
76    * node type or other constraint.
77    * @throws AccessDeniedException if the current ticket (i.e. the ticket that
78    * was used to aqcuire this <code>Workspace</code> object) does not have
79    * sufficient access rights to complete the operation.
80    * @throws PathNotFoundException if the node at <code>srcAbsPath</code> or
81    * the parent of the new node at <code>destAbsPath</code> does not exist.
82    * @throws ItemExistsException if a node or property already exists at
83    * <code>destAbsPath</code>.
84    * @throws ActionVetoedException If a <code>VetoableEventListener</code>
85    * vetoes one of the changes being saved.
86    * @throws RepositoryException if another error occurs.
87    */

88   public void copy(String JavaDoc srcPath, String JavaDoc destPath, boolean shallow)
89       throws ConstraintViolationException, ItemExistsException, AccessDeniedException, RepositoryException;
90
91   /**
92    * Copies the subtree (or node and its properties if <code>shallow</code> is
93    * <code>true</code>) at <code>srcAbsPath</code> to the new location at
94    * <code>destAbsPath</code> in the specified workspace.
95    *
96    * @param srcAbsPath the path of the node to be copied.
97    * @param destAbsPath the location to which the node at <code>srcAbsPath</code>
98    * is to be copied.
99    * @param shallow if true only the node at <code>srcAbsPath</code> and its
100    * properties are copied, otherwise the source node and its entire subtree is copied.
101    * @throws ConstraintViolationException if the copy would violate a
102    * node type or other constraint.
103    * @throws AccessDeniedException if the current ticket (i.e. the ticket that
104    * was used to aqcuire this <code>Workspace</code> object) does not have
105    * sufficient access rights to complete the operation.
106    * @throws PathNotFoundException if the node at <code>srcAbsPath</code> or
107    * the parent of the new node at <code>destAbsPath</code> does not exist.
108    * @throws ItemExistsException if a node or property already exists at
109    * <code>destAbsPath</code>.
110    * @throws ActionVetoedException If a <code>VetoableEventListener</code>
111    * vetoes one of the changes being saved.
112    * @throws RepositoryException if another error occurs.
113    */

114   public void clone(String JavaDoc srcAbsPath, String JavaDoc destAbsPath, String JavaDoc destWorkspace, boolean shallow) throws ConstraintViolationException, AccessDeniedException, PathNotFoundException, ItemExistsException, ActionVetoedException, RepositoryException;
115
116
117
118
119   /**
120    * Moves the node at <code>srcAbsPath</code> (and its entire subtree) to the
121    * new location at <code>destAbsPath</code>.
122    * Throws an exception if
123    * there is already an item at <code>destAbsPath</code>, or if some other
124    * constraint (access, node type, system-level) is violated. If succesful,
125    * the parent of the new node at <code>destAbsPath</code> is "saved" (i.e. the
126    * change is persisted immediately as is the parent of the moved node at its
127    * original location, there is no need to call <code>Node.save()</code>).
128    *
129    * @param srcAbsPath the path of the node to be moved.
130    * @param destAbsPath the location to which the node at <code>srcAbsPath</code>
131    * is to be moved.
132    * @throws ConstraintViolationException if the move would violate a
133    * node type or other constraint.
134    * @throws AccessDeniedException if the current ticket (i.e. the ticket that
135    * was used to aqcuire this <code>Workspace</code> object) does not have
136    * sufficient access rights to complete the operation.
137    * @throws PathNotFoundException if the node at <code>srcAbsPath</code> or
138    * the parent of the new node at <code>destAbsPath</code> does not exist.
139    * @throws ItemExistsException if a node or property already exists at
140    * <code>destAbsPath</code>.
141    * @throws ActionVetoedException If a <code>VetoableEventListener</code>
142    * vetoes one of the changes being saved.
143    * @throws RepositoryException if another error occurs.
144    */

145   public void move(String JavaDoc srcAbsPath, String JavaDoc destAbsPath) throws ConstraintViolationException, AccessDeniedException, PathNotFoundException, ItemExistsException, ActionVetoedException, RepositoryException;
146
147   /**
148    * Gets the <code>QueryManager</code>.
149    * Gets the <code>QueryManager</code> through which searching is done.
150    *
151    * @return the <code>QueryManager</code> object.
152    */

153   public QueryManager getQueryManager();
154
155   /**
156    * Returns the NamespaceRegistry object, which is used to set the mapping
157    * between namespace prefixes and URIs.
158    *
159    * @return the <code>NamespaceRegistry</code>.
160    */

161   public NamespaceRegistry getNamespaceRegistry();
162
163   /**
164    * Gets the <code>NodeTypeManager</code> object.
165    * Returns the <code>NodeTypeManager</code> through which node type
166    * information can be queried.
167    *
168    * @return a <code>NodeTypeManager</code> object.
169    */

170   public NodeTypeManager getNodeTypeManager();
171
172   /**
173    * In level 2 gets the <code>AccessManager</code>, in level 1 throws
174    * an <code>UnsupportedRepositoryOperationException</code>.
175    * <p/>
176    * <b>Level 1:</b>
177    * <p/>
178    * Always throws an <code>UnsupportedRepositoryOperationException</code> since
179    * access control is not supported in level 1.
180    * <p/>
181    * <b>Level 2:</b>
182    * <p/>
183    * Gets the <code>AccessManager</code> through which access control
184    * information is queried.
185    *
186    * @return an <code>AccessManager</code> object.
187    * @throws UnsupportedRepositoryOperationException
188    * In level 1: Always.
189    * In level 2: Never.
190    */

191   public AccessManager getAccessManager() throws UnsupportedRepositoryOperationException;
192
193   /**
194    * <i>If locking is supported</i> returns the
195    * <code>LockCapabilities</code> object, otherwise throws an
196    * <code>UnsupportedRepositoryOperationException</code>.
197    * <p/>
198    * <b>Level 1:</b>
199    * <p/>
200    * Always throws an <code>UnsupportedRepositoryOperationException</code>
201    * since locking is not supported in level 1.
202    * <p/>
203    * <b>Level 2:</b>
204    * <p/>
205    * If locking is supported, returns the <code>LockCapabilities</code>
206    * object through which dynamic discovery of supported locking functionality
207    * is provided. If locking is not supported then this method throws an
208    * <code>UnsupportedRepositoryOperationException</code>.
209    *
210    * @return A <code>LockCapabilities</code> object.
211    * @throws UnsupportedRepositoryOperationException
212    * In level 1: Always.
213    * In level 2: if implementation does not support locking.
214    */

215   public LockCapabilities getLockCapabilities() throws UnsupportedRepositoryOperationException;
216
217   /**
218    * If observation is supproted gets the <code>ObservationManager</code>,
219    * otherwisein throws an <code>UnsupportedRepositoryOperationException</code>.
220    * <p/>
221    * <b>Level 1:</b>
222    * <p/>
223    * Always throws an <code>UnsupportedRepositoryOperationException</code> since
224    * observation is not in supported in level 1.
225    * <p/>
226    * <b>Level 2:</b>
227    * <p/>
228    * If observation is supported (it is optional, even in level 2), gets the
229    * <code>ObservationManager</code> object through which event observation
230    * is managed. Otherwise throws an
231    * <code>UnsupportedRepositoryOperationException</code>.
232    *
233    * @return an <code>ObservationManager</code> object.
234    * @throws UnsupportedRepositoryOperationException
235    * In level 1: Always.
236    * In level 2: if implementation doesnot support observation.
237    */

238   public ObservationManager getObservationManager() throws UnsupportedRepositoryOperationException;
239
240   /**
241    * Serializes the subtree rooted at the node at <code>absPath</code>
242    * (it must be a node, not a property) as a stream of SAX
243    * events to the supplied <code>org.xml.sax.ContentHandler</code>.
244    * The XML represented by these SAX events will be in the
245    * <b>system view</b> form.
246    * <p/>
247    * If <code>binaryAsLink</code> is <code>true</code> then any properties
248    * of <code>PropertyType.BINARY</code> will be replaced in the serialized
249    * output by properties of <code>PropertyType.SOFTLINK</code> recording
250    * their own absolute path.
251    * <p/>
252    * If <code>binaryAsLink</code> is <code>false</code> then the actual value
253    * of each <code>BINARY</code> property is recorded using Base64 encoding.
254    * <p/>
255    * If <code>noRecurse</code> is true then only the node at
256    * <code>absPath</code> and its properties, but not its child nodes, is
257    * serialized.
258    * <p/>
259    * If <code>noRecurse</code> is <code>false</code> then the entire subtree
260    * rooted at <code>absPath</code> is serialized.
261    * <p/>
262    * If the user lacks read access to some subsection of the specified tree,
263    * that section simply does not get serialized, since, from the user's
264    * point of view, it is not there.
265    *
266    * @param absPath The path of the root of the subtree to be serialized.
267    * This must be the path to a node, not a property
268    * @param contentHandler The <code>org.xml.ContentHandler</code> to
269    * which the SAX events representing the XML serialization of the subtree
270    * will be output.
271    * @param binaryAsLink A <code>boolean</code> governing whether binary
272    * properties are to converted to soft links.
273    * @param noRecurse A <code>boolean</code> governing whether the subtree at
274    * absPath is to be recursed.
275    * @throws PathNotFoundException if no node exists at <code>absPath</code>.
276    * @throws SAXException if an error occurs while feeding events to the
277    * <code>org.xml.ContentHandler</code>.
278    * @throws RepositoryException if another error occurs.
279    */

280   public void exportSysView(String JavaDoc absPath, ContentHandler JavaDoc contentHandler, boolean binaryAsLink, boolean noRecurse) throws PathNotFoundException, SAXException JavaDoc, RepositoryException;
281
282   /**
283    * Serializes the subtree rooted at the node (it must be a node, not a
284    * property)at <code>absPath</code> as an XML document and streams it to
285    * the supplied <code>OutputStream</code>. The resulting XML is in the
286    * <b>system view</b> form.
287    * <p/>
288    * If <code>binaryAsLink</code> is <code>true</code> then any properties
289    * of <code>PropertyType.BINARY</code> will be replaced in the serialized
290    * output by properties of <code>PropertyType.SOFTLINK</code> recording
291    * their own absolute path.
292    * <p/>
293    * If <code>binaryAsLink</code> is <code>false</code> then the actual value
294    * of each <code>BINARY</code> property is recorded using Base64 encoding.
295    * <p/>
296    * If <code>noRecurse</code> is true then only the node at
297    * <code>absPath</code> and its properties, but not its child nodes, is
298    * serialized.
299    * <p/>
300    * If <code>noRecurse</code> is <code>false</code> then the entire subtree
301    * rooted at <code>absPath</code> is serialized.
302    * <p/>
303    * If the user lacks read access to some subsection of the specified tree,
304    * that section simply does not get serialized, since, from the user's
305    * point of view, it is not there.
306    *
307    * @param absPath The path of the root of the subtree to be serialized.
308    * @param out The <code>OutputStream</code> to which the XML
309    * serialization of the subtree will be output.
310    * @param binaryAsLink A <code>boolean</code> governing whether binary
311    * properties are to converted to soft links.
312    * @param noRecurse A <code>boolean</code> governing whether the subtree at
313    * <code>absPath</code> is to be recursed.
314    * @throws IOException if an error during an I/O operation occurs.
315    * @throws PathNotFoundException if no node exists at <code>absPath</code>.
316    * @throws RepositoryException if another error occurs.
317    */

318   public void exportSysView(String JavaDoc absPath, OutputStream JavaDoc out, boolean binaryAsLink, boolean noRecurse) throws IOException JavaDoc, PathNotFoundException, RepositoryException;
319
320   /**
321    * Same as <code>exportSysView(String absPath, ContentHandler contentHandler,
322    * boolean binaryAsLink, boolean noRecurse)</code> except that the resulting
323    * XML is in the <b>document view</b> form.
324    *
325    * @param absPath The path of the root of the subtree to be serialized.
326    * @param contentHandler The <code>org.xml.ContentHandler</code> to
327    * which the SAX events representing the XML serialization of the subtree
328    * will be output.
329    * @param binaryAsLink A <code>boolean</code> governing whether binary
330    * properties are to converted to soft links.
331    * @param noRecurse A <code>boolean</code> governing whether the subtree at
332    * <code>absPath</code> is to be recursed.
333    * @throws PathNotFoundException if no node exists at <code>absPath</code>.
334    * @throws SAXException if an error occurs while feeding events to the
335    * <code>org.xml.ContentHandler</code>.
336    * @throws RepositoryException if another error occurs.
337    */

338   public void exportDocView(String JavaDoc absPath, ContentHandler JavaDoc contentHandler, boolean binaryAsLink, boolean noRecurse) throws PathNotFoundException, SAXException JavaDoc, RepositoryException;
339
340   /**
341    * Same as <code>exportSysView(String absPath, OutputStream out,
342    * boolean binaryAsLink, boolean noRecurse</code> except that the resulting
343    * XML is in the <b>document view</b> form.
344    *
345    * @param absPath The path of the root of the subtree to be serialized.
346    * @param out The <code>OutputStream</code> to which the XML
347    * serialization of the subtree will be output.
348    * @param binaryAsLink A <code>boolean</code> governing whether binary
349    * properties are to converted to soft links.
350    * @param noRecurse A <code>boolean</code> governing whether the subtree at
351    * <code>absPath</code> is to be recursed.
352    * @throws IOException if an error during an I/O operation occurs.
353    * @throws PathNotFoundException if no node exists at <code>absPath</code>.
354    * @throws RepositoryException if another error occurs.
355    */

356   public void exportDocView(String JavaDoc absPath, OutputStream JavaDoc out, boolean binaryAsLink, boolean noRecurse) throws IOException JavaDoc, PathNotFoundException, RepositoryException;
357 }
358
Popular Tags