Collection


1   package org.xmldb.api.base;
2   
3   /*
4    *  The XML:DB Initiative Software License, Version 1.0
5    *
6    *
7    * Copyright (c) 2000-2001 The XML:DB Initiative.  All rights
8    * reserved.
9    *
10   * Redistribution and use in source and binary forms, with or without
11   * modification, are permitted provided that the following conditions
12   * are met:
13   *
14   * 1. Redistributions of source code must retain the above copyright
15   *    notice, this list of conditions and the following disclaimer.
16   *
17   * 2. Redistributions in binary form must reproduce the above copyright
18   *    notice, this list of conditions and the following disclaimer in
19   *    the documentation and/or other materials provided with the
20   *    distribution.
21   *
22   * 3. The end-user documentation included with the redistribution,
23   *    if any, must include the following acknowledgment:
24   *       "This product includes software developed by the
25   *        XML:DB Initiative (http://www.xmldb.org/)."
26   *    Alternately, this acknowledgment may appear in the software itself,
27   *    if and wherever such third-party acknowledgments normally appear.
28   *
29   * 4. The name "XML:DB Initiative" must not be used to endorse or
30   *    promote products derived from this software without prior written
31   *    permission. For written permission, please contact info@xmldb.org.
32   *
33   * 5. Products derived from this software may not be called "XML:DB",
34   *    nor may "XML:DB" appear in their name, without prior written
35   *    permission of the XML:DB Initiative.
36   *
37   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
38   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
39   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
40   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
41   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
42   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
43   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
44   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
45   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
46   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
47   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
48   * SUCH DAMAGE.
49   * ====================================================================
50   *
51   * This software consists of voluntary contributions made by many
52   * individuals on behalf of the XML:DB Initiative. For more information
53   * on the XML:DB Initiative, please see <http://www.xmldb.org/>.
54   */
55  
56  /**
57   * A <code>Collection</code> represents a collection of <code>Resource</code>s 
58   * stored within an XML
59   * database. An XML
60   * database MAY expose collections as a hierarchical set of parent and child
61   * collections.<p />
62   *
63   * A <code>Collection</code> provides access to the <code>Resource</code>s
64   * stored by the <code>Collection</code> and to <code>Service</code> instances
65   * that can operate against the <code>Collection</code> and the 
66   * <code>Resource</code>s stored within it. The <code>Service</code> mechanism
67   * provides the ability to extend the functionality of a <code>Collection</code>
68   * in ways that allows optional functionality to be enabled for the <code>Collection</code>. 
69   */
70  public interface Collection extends Configurable {
71     /**
72      * Provides a list of all services known to the collection. If no services
73      * are known an empty list is returned.
74      *
75      * @return An array of registered <code>Service</code> implementations.
76      * @exception XMLDBException with expected error codes.<br />
77      *  <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
78      *  specific errors that occur.<br />
79      */
80     Service[] getServices() throws XMLDBException;
81  
82     /**
83      * Returns a <code>Service</code> instance for the requested service name and version. If
84      * no <code>Service</code> exists for those parameters a null value is returned.
85      *
86      * @param name Description of Parameter
87      * @param version Description of Parameter
88      * @return the Service instance or null if no Service could be found.
89      * @exception XMLDBException with expected error codes.<br />
90      *  <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
91      *  specific errors that occur.<br />
92      */
93     Service getService(String   name, String   version) throws XMLDBException;
94  
95     /**
96      * Registers a new <code>Service</code> implementation with the collection.
97      * The <code>Service</code>
98      * implementation is queried for the name and version that will be used to
99      * retrieve the service. The <code>Service</code> instance must be a valid service for
100     * this collection or an exception will be raised.
101     *
102     * @param serv the service instance to register.
103     * @exception XMLDBException with expected error codes.<br />
104     *  <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
105     *  specific errors that occur.<br />
106     *  <code>ErrorCodes.INVALID_SERVICE</code> if the <code>Service</code>
107     *  instance does not have a proper name or version or the instance is null.
108     */
109    void registerService(Service serv) throws XMLDBException;
110 
111    /**
112     * Returns the parent collection for this collection or null if no parent
113     * collection exists.
114     *
115     * @return the parent <code>Collection</code> instance.
116     * @exception XMLDBException with expected error codes.<br />
117     *  <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
118     *  specific errors that occur.<br />
119     */
120    Collection getParentCollection() throws XMLDBException;
121 
122    /**
123     * Returns the number of child collections under this 
124     * <code>Collection</code> or 0 if no child collections exist.
125     *
126     * @return the number of child collections.
127     * @exception XMLDBException with expected error codes.<br />
128     *  <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
129     *  specific errors that occur.<br />
130     */
131    int getChildCollectionCount() throws XMLDBException;
132 
133    /**
134     * Returns a list of collection names naming all child collections
135     * of the current collection. If no child collections exist an empty list is
136     * returned.
137     *
138     * @return an array containing collection names for all child
139     *      collections.
140     * @exception XMLDBException with expected error codes.<br />
141     *  <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
142     *  specific errors that occur.<br />
143     */
144    String  [] listChildCollections() throws XMLDBException;
145 
146    /**
147     * Returns a <code>Collection</code> instance for the requested child collection 
148     * if it exists.
149     *
150     * @param name the name of the child collection to retrieve.
151     * @return the requested child collection or null if it couldn't be found.
152     * @exception XMLDBException with expected error codes.<br />
153     *  <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
154     *  specific errors that occur.<br />
155     */
156    Collection getChildCollection(String   name) throws XMLDBException;
157    
158    /**
159     * Returns the number of resources currently stored in this collection or 0
160     * if the collection is empty.
161     *
162     * @return the number of resource in the collection.
163     * @exception XMLDBException with expected error codes.<br />
164     *  <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
165     *  specific errors that occur.<br />
166     */
167    int getResourceCount() throws XMLDBException;
168 
169    /**
170     * Returns a list of the ids for all resources stored in the collection.
171     *
172     * @return a string array containing the names for all 
173     *  <code>Resource</code>s in the collection.
174     * @exception XMLDBException with expected error codes.<br />
175     *  <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
176     *  specific errors that occur.<br />
177     */
178    String  [] listResources() throws XMLDBException;
179 
180    /**
181     * Creates a new empty <code>Resource</code> with the provided id. 
182     * The type of <code>Resource</code>
183     * returned is determined by the <code>type</code> parameter. The XML:DB API currently 
184     * defines "XMLResource" and "BinaryResource" as valid resource types.
185     * The <code>id</code> provided must be unique within the scope of the 
186     * collection. If 
187     * <code>id</code> is null or its value is empty then an id is generated by   
188     * calling <code>createId()</code>. The
189     * <code>Resource</code> created is not stored to the database until 
190     * <code>storeResource()</code> is called.
191     *
192     * @param id the unique id to associate with the created <code>Resource</code>.
193     * @param type the <code>Resource</code> type to create.
194     * @return an empty <code>Resource</code> instance.    
195     * @exception XMLDBException with expected error codes.<br />
196     *  <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
197     *  specific errors that occur.<br />
198     *  <code>ErrorCodes.UNKNOWN_RESOURCE_TYPE</code> if the <code>type</code>
199     *   parameter is not a known <code>Resource</code> type.
200     */
201    Resource createResource(String   id, String   type) throws XMLDBException;
202 
203    /**
204     * Removes the <code>Resource</code> from the database.
205     *
206     * @param res the resource to remove.
207     * @exception XMLDBException with expected error codes.<br />
208     *  <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
209     *  specific errors that occur.<br />
210     *  <code>ErrorCodes.INVALID_RESOURCE</code> if the <code>Resource</code> is
211     *   not valid.<br />
212     *  <code>ErrorCodes.NO_SUCH_RESOURCE</code> if the <code>Resource</code> is
213     *   not known to this <code>Collection</code>.
214     */
215    void removeResource(Resource res) throws XMLDBException;
216 
217    /**
218     * Stores the provided resource into the database. If the resource does not
219     * already exist it will be created. If it does already exist it will be
220     * updated.
221     *
222     * @param res the resource to store in the database.
223     * @exception XMLDBException with expected error codes.<br />
224     *  <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
225     *  specific errors that occur.<br />
226     *  <code>ErrorCodes.INVALID_RESOURCE</code> if the <code>Resource</code> is
227     *   not valid.
228     */
229    void storeResource(Resource res) throws XMLDBException;
230 
231    /**
232     * Retrieves a <code>Resource</code> from the database. If the 
233     * <code>Resource</code> could not be
234     * located a null value will be returned.
235     *
236     * @param id the unique id for the requested resource.
237     * @return The retrieved <code>Resource</code> instance.
238     * @exception XMLDBException with expected error codes.<br />
239     *  <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
240     *  specific errors that occur.<br />    
241     */
242    Resource getResource(String   id) throws XMLDBException;
243 
244    /**
245     * Creates a new unique ID within the context of the <code>Collection</code>
246     *
247     * @return the created id as a string.
248     * @exception XMLDBException with expected error codes.<br />
249     *  <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
250     *  specific errors that occur.<br />
251     */
252    String   createId() throws XMLDBException;
253 
254    /**
255     * Releases all resources consumed by the <code>Collection</code>. 
256     * The <code>close</code> method must
257     * always be called when use of a <code>Collection</code> is complete.
258     *
259     * @exception XMLDBException with expected error codes.<br />
260     *  <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
261     *  specific errors that occur.<br />
262     */
263    void close() throws XMLDBException;
264 }
265 
266
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags