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  ;
35  import org.xml.sax.SAXException  ;
36  
37  import java.io.OutputStream  ;
38  import java.io.IOException  ;
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   srcPath, String   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   srcAbsPath, String   destAbsPath, String   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   srcAbsPath, String   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   absPath, ContentHandler   contentHandler, boolean binaryAsLink, boolean noRecurse) throws PathNotFoundException, SAXException  , 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   absPath, OutputStream   out, boolean binaryAsLink, boolean noRecurse) throws IOException  , 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   absPath, ContentHandler   contentHandler, boolean binaryAsLink, boolean noRecurse) throws PathNotFoundException, SAXException  , 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   absPath, OutputStream   out, boolean binaryAsLink, boolean noRecurse) throws IOException  , PathNotFoundException, RepositoryException;
357 }
358
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags