Ticket


1   /*
2    * $Id: Ticket.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 org.xml.sax.*;
27  
28  import javax.jcr.nodetype.*;
29  import javax.jcr.access.*;
30  import java.io.*;
31  
32  /**
33   * Through this interface all access to the content repository occurs.
34   * Given upon <code>login</code> to a <code>Repository</code>.
35   * Both level 1 and 2 implementations must implement this interface, though
36   * in level 1 some methods will throw an
37   * <code>UnsupportedRepositoryOperationException</code> (see the
38   * method-by-method descriptions).
39   *
40   * @author Peeter Piegaze
41   * @author Stefan Guggisberg
42   * @see javax.jcr.xa.XATicket
43   */
44  public interface Ticket {
45  
46    /**
47     * Returns the <code>Repository</code> object through which this ticket was
48     * acquired.
49     *
50     * @return a <code>{@link Repository}</code> object.
51     */
52    public Repository getRepository();
53  
54    /**
55     * Returns the Credentials object that was used to authorize the issue of
56     * this ticket.
57     *
58     * @return the Credentials of this ticket.
59     */
60    public Credentials getCredentials();
61  
62    /**
63     * Returns the <code>Workspace</code> attached to this <code>Ticket</code>.
64     *
65     * @return a <code>{@link Workspace}</code> object.
66     */
67    public Workspace getWorkspace();
68  
69    /**
70     * Returns new ticket in accordance with the specified (new) Credentials.
71     * Allows the current user to "impersonate" another using incomplete
72     * credentials (perhaps including a user name but no password, for example),
73     * assuming that their original ticket gives them that right. Throws a
74     * <code>LoginException</code> if the current ticket does not have
75     * sufficient rights.
76     *
77     * @param credentials A <code>Credentials</code> object
78     * @return a <code>Ticket</code> object
79     * @throws LoginException if the current ticket does not have
80     *                        sufficient rights.
81     */
82    public Ticket impersonate(Credentials credentials) throws LoginException;
83  
84    /**
85     * Returns the root node of the workspace.
86     * The root node, "/", is the main access point to the content of the
87     * workspace.
88     *
89     * @return The root node of the workspace: a <code>Node</code> object.
90     * @throws RepositoryException if an error occurs.
91     */
92    public Node getRootNode() throws RepositoryException;
93  
94    /**
95     * Returns the node specifed by the given UUID. Only applies to nodes that
96     * expose a UUID, in other words, those of mixin node type
97     * <code>mix:referenceable</code>
98     *
99     * @param uuid A universally unique identifier.
100    * @return A <code>Node</code>.
101    * @throws ItemNotFoundException if the specified UUID is not found.
102    * @throws RepositoryException   if another error occurs.
103    */
104   public Node getNodeByUUID(String   uuid) throws ItemNotFoundException, RepositoryException;
105 
106   /**
107    * Returns the node at the specified absolute path.
108    *
109    * @param absPath An absolute path.
110    * @return A <code>Node</code>.
111    * @throws PathNotFoundException if the specified path cannot be found.
112    * @throws RepositoryException   if another error occurs.
113    */
114   public Node getNodeByAbsPath(String   absPath) throws PathNotFoundException, RepositoryException;
115 
116   /**
117    * Validates and (if validation succeeds) persists all changes made through
118    * this Ticket since the last <code>save</code> or </code>revert</code>.
119    * <p/>
120    * Constraints mandated by node types are validated on save. If validation
121    * fails a <code>ConstraintViolationException</code> is thrown and the
122    * state of the transient storage is left unaffected. If validation succeeds
123    * then all pending changes are persited and the transient change cache is
124    * flushed.
125    * <p/>
126    * The save method allows a node to be in a temporarily invalid state while
127    * it is being "built", that is, while it is having properties and child
128    * nodes added to it. Once it is in a consistent state it can be saved.
129    * <p/>
130    * An <code>AccessDeniedException</code> will be thrown if an attempt is
131    * made to save changes for which the current user does not have sufficient
132    * access rights.
133    * <p/>
134    * An <code>ActionVetoedException</code> will be thrown if a
135    * <code>VetoableEventListener</code> vetoes one of the changes being saved.
136    * <p/>
137    * If save succeeds then the all changes are removed from the cache
138    * of pending changes in the ticket.
139    *
140    * @throws ConstraintViolationException If any of the changes would
141    *                                      violate a constraint as defined by the node type of the respective node.
142    * @throws AccessDeniedException        if the current ticket does not have
143    *                                      sufficient access rights to complete the operation.
144    * @throws RepositoryException          If another error occurs.
145    * @throws ActionVetoedException        If a VetoableEventListener vetoes one of
146    *                                      the changes being saved.
147    */
148   public void save() throws AccessDeniedException, ConstraintViolationException, ActionVetoedException, RepositoryException;
149 
150   /**
151    * Discards all pending changes made through this ticket, that is, all
152    * changes made since the last sucessful <code>save</code>.
153    *
154    * @throws RepositoryException If an unexpected error occurs.
155    */
156   public void revert() throws RepositoryException;
157 
158   /**
159    * Deserializes an XML document (in <b>system view</b> form or <b>document
160    * view</b> form) and adds the resulting item subtree as a child of the
161    * node at <code>parentAbsPath</code>. Requires a <code>save</code> to
162    * persist the changes.
163    * <p/>
164    * The deserialization mechanism must take into account the
165    * property <code>jcr:uuid</code> in order to reconstruct hard links
166    * across serialization/deserialization cycles.
167    * <p/>
168    * If node type restrictions prevent the addition of the subtree to the
169    * node at <code>parentAbsPath</code>, a <code>ConstraintViolationException</code>
170    * is thrown.
171    * <p/>
172    * If the XML stream provided is not a valid JCR <b>system view</b> XML
173    * document then an <code>InvalidSerializedDataException</code> is thrown.
174    * <p/>
175    * If the user does not have sufficient access rights to write the
176    * deserialized nodes and properties, then an
177    * <code>AccessDeniedException</code> is thrown on <code>save</code>.
178    * <p/>
179    *
180    * @param parentAbsPath the absolute path of the node below which the deserialized
181    *                      subtree is added.
182    * @param in            The <code>Inputstream</code> from which the XML to be deserilaized
183    *                      is read.
184    * @throws java.io.IOException            if an error during an I/O operation occurs.
185    * @throws PathNotFoundException          if no node exists at <code>parentAbsPath</code>.
186    * @throws ItemExistsException            if an item by the same name as the newly
187    *                                        imported root node already exists.
188    * @throws ConstraintViolationException   if node type restrictions prevent
189    *                                        the addition of the subtree to the node at <code>parentAbsPath</code>
190    * @throws InvalidSerializedDataException if the serialized data being input is
191    *                                        not a valid JCR <b>system view</b> XML document.
192    * @throws RepositoryException            is another error occurs.
193    */
194   public void importXML(String   parentAbsPath, InputStream in) throws IOException, PathNotFoundException, ItemExistsException, ConstraintViolationException, InvalidSerializedDataException, RepositoryException;
195 
196   /**
197    * Deserializes the stream of SAX events (from either system view or
198    * document view XML source) defined by the series of calls of
199    * the methods of the <code>org.xml.ContentHandler</code> into a subtree of
200    * items immediately below the node at <code>parentAbsPath</code>. If the
201    * incoming XML stream (in the form of SAX events) is not a valid JCR
202    * system view or document view XML document then the
203    * <code>ContentHandler</code> will throw a <code>SAXException</code> in
204    * one of its methods. After the document has been fed in <code>save</code>
205    * must be called to persist the changes to the repository.
206    *
207    * @param parentAbsPath the absolute path of a node under which (as child) the imported
208    *                      subtree will be built.
209    * @return an org.xml.ContentHandler whose methods may be called to feed SAX
210    *         events into the deserializer.
211    * @throws ItemExistsException   if an item alread exists at <code>parentAbsPath</code>.
212    * @throws PathNotFoundException if no node exists at <code>parentPath</code>.
213    * @throws RepositoryException   if another error occurs.
214    */
215   public ContentHandler importXML(String   parentAbsPath) throws PathNotFoundException, ItemExistsException, RepositoryException;
216 
217   /**
218    * Within the scope of this ticket, rename a persistently registered
219    * namespace URI to the new prefix.  The renaming only affects operations
220    * done through this ticket. To clear all renamings the client must acquire
221    * a new ticket.
222    * <p/>
223    * If the specified <code>uri</code> is not among those registered in the
224    * <code>NamespaceRegistry</code> then a <code>NamespaceException</code> is
225    * thrown.
226    *
227    * @param prefix a string
228    * @param uri    a string
229    * @throws NamespaceException if specified uri is not registered.
230    */
231   public void setPrefix(String   prefix, String   uri) throws NamespaceException;
232 
233   /**
234    * Returns all prefixes currently set for this ticket. This includes all
235    * those registered in the <code>NamespaceRegistry</code> but <i>not
236    * over-ridden</i> by a <code>Ticket.setPrefix</code>, plus those currently set
237    * locally by <code>Ticket.setPrefix</code>.
238    *
239    * @return a string array
240    */
241   public String  [] getPrefixes();
242 
243   /**
244    * For a given prefix, returns the URI to which it is mapped as currently
245    * set in this ticket. If the prefix is unknown a NamespaceException is thrown.
246    *
247    * @param prefix a string
248    * @return a string
249    * @throws NamespaceException if the prefix is unknown.
250    */
251   public String   getURI(String   prefix) throws NamespaceException;
252 
253   /**
254    * Releases all resources associate with this ticket. Calling this method
255    * is not mandatory since a good implementaion should automatically timeout
256    * anyway. However, when more precise control over resource allocation is
257    * need this method can be used.
258    */
259   public void logout();
260 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags