001: package org.xmldb.api.base;
002:
003: /*
004: * The XML:DB Initiative Software License, Version 1.0
005: *
006: *
007: * Copyright (c) 2000-2001 The XML:DB Initiative. All rights
008: * reserved.
009: *
010: * Redistribution and use in source and binary forms, with or without
011: * modification, are permitted provided that the following conditions
012: * are met:
013: *
014: * 1. Redistributions of source code must retain the above copyright
015: * notice, this list of conditions and the following disclaimer.
016: *
017: * 2. Redistributions in binary form must reproduce the above copyright
018: * notice, this list of conditions and the following disclaimer in
019: * the documentation and/or other materials provided with the
020: * distribution.
021: *
022: * 3. The end-user documentation included with the redistribution,
023: * if any, must include the following acknowledgment:
024: * "This product includes software developed by the
025: * XML:DB Initiative (http://www.xmldb.org/)."
026: * Alternately, this acknowledgment may appear in the software itself,
027: * if and wherever such third-party acknowledgments normally appear.
028: *
029: * 4. The name "XML:DB Initiative" must not be used to endorse or
030: * promote products derived from this software without prior written
031: * permission. For written permission, please contact info@xmldb.org.
032: *
033: * 5. Products derived from this software may not be called "XML:DB",
034: * nor may "XML:DB" appear in their name, without prior written
035: * permission of the XML:DB Initiative.
036: *
037: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
038: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
039: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
040: * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
041: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
042: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
043: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
044: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
045: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
046: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
047: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
048: * SUCH DAMAGE.
049: * ====================================================================
050: *
051: * This software consists of voluntary contributions made by many
052: * individuals on behalf of the XML:DB Initiative. For more information
053: * on the XML:DB Initiative, please see <http://www.xmldb.org/>.
054: */
055:
056: /**
057: * A <code>Collection</code> represents a collection of <code>Resource</code>s
058: * stored within an XML
059: * database. An XML
060: * database MAY expose collections as a hierarchical set of parent and child
061: * collections.<p />
062: *
063: * A <code>Collection</code> provides access to the <code>Resource</code>s
064: * stored by the <code>Collection</code> and to <code>Service</code> instances
065: * that can operate against the <code>Collection</code> and the
066: * <code>Resource</code>s stored within it. The <code>Service</code> mechanism
067: * provides the ability to extend the functionality of a <code>Collection</code>
068: * in ways that allows optional functionality to be enabled for the <code>Collection</code>.
069: */
070: public interface Collection extends Configurable {
071: /**
072: * Provides a list of all services known to the collection. If no services
073: * are known an empty list is returned.
074: *
075: * @return An array of registered <code>Service</code> implementations.
076: * @exception XMLDBException with expected error codes.<br />
077: * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
078: * specific errors that occur.<br />
079: */
080: Service[] getServices() throws XMLDBException;
081:
082: /**
083: * Returns a <code>Service</code> instance for the requested service name and version. If
084: * no <code>Service</code> exists for those parameters a null value is returned.
085: *
086: * @param name Description of Parameter
087: * @param version Description of Parameter
088: * @return the Service instance or null if no Service could be found.
089: * @exception XMLDBException with expected error codes.<br />
090: * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
091: * specific errors that occur.<br />
092: */
093: Service getService(String name, String version)
094: throws XMLDBException;
095:
096: /**
097: * Registers a new <code>Service</code> implementation with the collection.
098: * The <code>Service</code>
099: * implementation is queried for the name and version that will be used to
100: * retrieve the service. The <code>Service</code> instance must be a valid service for
101: * this collection or an exception will be raised.
102: *
103: * @param serv the service instance to register.
104: * @exception XMLDBException with expected error codes.<br />
105: * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
106: * specific errors that occur.<br />
107: * <code>ErrorCodes.INVALID_SERVICE</code> if the <code>Service</code>
108: * instance does not have a proper name or version or the instance is null.
109: */
110: void registerService(Service serv) throws XMLDBException;
111:
112: /**
113: * Returns the parent collection for this collection or null if no parent
114: * collection exists.
115: *
116: * @return the parent <code>Collection</code> instance.
117: * @exception XMLDBException with expected error codes.<br />
118: * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
119: * specific errors that occur.<br />
120: */
121: Collection getParentCollection() throws XMLDBException;
122:
123: /**
124: * Returns the number of child collections under this
125: * <code>Collection</code> or 0 if no child collections exist.
126: *
127: * @return the number of child collections.
128: * @exception XMLDBException with expected error codes.<br />
129: * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
130: * specific errors that occur.<br />
131: */
132: int getChildCollectionCount() throws XMLDBException;
133:
134: /**
135: * Returns a list of collection names naming all child collections
136: * of the current collection. If no child collections exist an empty list is
137: * returned.
138: *
139: * @return an array containing collection names for all child
140: * collections.
141: * @exception XMLDBException with expected error codes.<br />
142: * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
143: * specific errors that occur.<br />
144: */
145: String[] listChildCollections() throws XMLDBException;
146:
147: /**
148: * Returns a <code>Collection</code> instance for the requested child collection
149: * if it exists.
150: *
151: * @param name the name of the child collection to retrieve.
152: * @return the requested child collection or null if it couldn't be found.
153: * @exception XMLDBException with expected error codes.<br />
154: * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
155: * specific errors that occur.<br />
156: */
157: Collection getChildCollection(String name) throws XMLDBException;
158:
159: /**
160: * Returns the number of resources currently stored in this collection or 0
161: * if the collection is empty.
162: *
163: * @return the number of resource in the collection.
164: * @exception XMLDBException with expected error codes.<br />
165: * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
166: * specific errors that occur.<br />
167: */
168: int getResourceCount() throws XMLDBException;
169:
170: /**
171: * Returns a list of the ids for all resources stored in the collection.
172: *
173: * @return a string array containing the names for all
174: * <code>Resource</code>s in the collection.
175: * @exception XMLDBException with expected error codes.<br />
176: * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
177: * specific errors that occur.<br />
178: */
179: String[] listResources() throws XMLDBException;
180:
181: /**
182: * Creates a new empty <code>Resource</code> with the provided id.
183: * The type of <code>Resource</code>
184: * returned is determined by the <code>type</code> parameter. The XML:DB API currently
185: * defines "XMLResource" and "BinaryResource" as valid resource types.
186: * The <code>id</code> provided must be unique within the scope of the
187: * collection. If
188: * <code>id</code> is null or its value is empty then an id is generated by
189: * calling <code>createId()</code>. The
190: * <code>Resource</code> created is not stored to the database until
191: * <code>storeResource()</code> is called.
192: *
193: * @param id the unique id to associate with the created <code>Resource</code>.
194: * @param type the <code>Resource</code> type to create.
195: * @return an empty <code>Resource</code> instance.
196: * @exception XMLDBException with expected error codes.<br />
197: * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
198: * specific errors that occur.<br />
199: * <code>ErrorCodes.UNKNOWN_RESOURCE_TYPE</code> if the <code>type</code>
200: * parameter is not a known <code>Resource</code> type.
201: */
202: Resource createResource(String id, String type)
203: throws XMLDBException;
204:
205: /**
206: * Removes the <code>Resource</code> from the database.
207: *
208: * @param res the resource to remove.
209: * @exception XMLDBException with expected error codes.<br />
210: * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
211: * specific errors that occur.<br />
212: * <code>ErrorCodes.INVALID_RESOURCE</code> if the <code>Resource</code> is
213: * not valid.<br />
214: * <code>ErrorCodes.NO_SUCH_RESOURCE</code> if the <code>Resource</code> is
215: * not known to this <code>Collection</code>.
216: */
217: void removeResource(Resource res) throws XMLDBException;
218:
219: /**
220: * Stores the provided resource into the database. If the resource does not
221: * already exist it will be created. If it does already exist it will be
222: * updated.
223: *
224: * @param res the resource to store in the database.
225: * @exception XMLDBException with expected error codes.<br />
226: * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
227: * specific errors that occur.<br />
228: * <code>ErrorCodes.INVALID_RESOURCE</code> if the <code>Resource</code> is
229: * not valid.
230: */
231: void storeResource(Resource res) throws XMLDBException;
232:
233: /**
234: * Retrieves a <code>Resource</code> from the database. If the
235: * <code>Resource</code> could not be
236: * located a null value will be returned.
237: *
238: * @param id the unique id for the requested resource.
239: * @return The retrieved <code>Resource</code> instance.
240: * @exception XMLDBException with expected error codes.<br />
241: * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
242: * specific errors that occur.<br />
243: */
244: Resource getResource(String id) throws XMLDBException;
245:
246: /**
247: * Creates a new unique ID within the context of the <code>Collection</code>
248: *
249: * @return the created id as a string.
250: * @exception XMLDBException with expected error codes.<br />
251: * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
252: * specific errors that occur.<br />
253: */
254: String createId() throws XMLDBException;
255:
256: /**
257: * Releases all resources consumed by the <code>Collection</code>.
258: * The <code>close</code> method must
259: * always be called when use of a <code>Collection</code> is complete.
260: *
261: * @exception XMLDBException with expected error codes.<br />
262: * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
263: * specific errors that occur.<br />
264: */
265: void close() throws XMLDBException;
266: }
|