001: package org.xmldb.api;
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: import org.xmldb.api.base.*;
057:
058: import java.util.*;
059:
060: /**
061: * <code>DatabaseManager</code> is the entry point for the API and enables you to get the
062: * initial <code>Collection</code> references necessary to do anything useful with the API.
063: * <code>DatabaseManager</code> is intended to be
064: * provided as a concrete implementation in a particular programming
065: * language. Individual language mappings should define the exact syntax and
066: * semantics of its use.
067: */
068: public class DatabaseManager {
069: protected static final String URI_PREFIX = "xmldb:";
070: static Properties properties = new Properties();
071: static Hashtable databases = new Hashtable();
072:
073: /**
074: * Returns a list of all available <code>Database</code> implementations
075: * that have been registered with this <code>DatabaseManager</code>.
076: *
077: * @return An array of <code>Database</code> instances.
078: * One for each <code>Database</code> registered
079: * with the <code>DatabaseManager</code>. If no <code>Database</code>
080: * instances exist then an empty array is returned.
081: */
082: public static Database[] getDatabases() {
083: Enumeration e = databases.elements();
084: Database[] result = new Database[databases.size()];
085:
086: int i = 0;
087: while (e.hasMoreElements()) {
088: result[i] = (Database) e.nextElement();
089: i++;
090: }
091:
092: return result;
093: }
094:
095: /**
096: * Registers a new <code>Database</code> implementation with the
097: * <code>DatabaseManager</code>.
098: *
099: * @param database The database instance to register.
100: * @exception XMLDBException with expected error codes.<br />
101: * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
102: * specific errors that occur.<br />
103: * <code>ErrorCodes.INVALID_DATABASE</code> if the provided <code>Database
104: * </code> instance is invalid.
105: */
106: public static void registerDatabase(Database database)
107: throws XMLDBException {
108: if ((database.getName() == null)
109: || (database.getName().equals(""))) {
110: throw new XMLDBException(ErrorCodes.INVALID_DATABASE);
111: }
112:
113: databases.put(database.getName(), database);
114: }
115:
116: /**
117: * Deregisters a <code>Database</code> implementation from the <code>DatabaseManager</code>. Once a
118: * <code>Database</code> has been deregistered it can no longer be used to handle
119: * requests.
120: *
121: * @param database The <code>Database</code> instance to deregister.
122: * @exception XMLDBException with expected error codes.<br />
123: * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
124: * specific errors that occur.
125: */
126: public static void deregisterDatabase(Database database)
127: throws XMLDBException {
128: databases.remove(database.getName());
129: }
130:
131: /**
132: * Retreives a <code>Collection</code> instance from the database for the
133: * given URI. The format of the majority of the URI is database
134: * implementation specific however the uri must begin with characters xmldb:
135: * and be followed by the name of the database instance as returned by
136: * <code>Database.getName()</code> and a colon
137: * character. An example would be for the database named "vendordb" the URI
138: * handed to getCollection would look something like the following.
139: * <code>xmldb:vendordb://host:port/path/to/collection</code>. The xmldb:
140: * prefix will be removed from the URI prior to handing the URI to the
141: * <code>Database</code> instance for handling.
142: *
143: * @param uri The database specific URI to use to locate the collection.
144: * @return A <code>Collection</code> instance for the requested collection or
145: * null if the collection could not be found.
146: * @exception XMLDBException with expected error codes.<br />
147: * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
148: * specific errors that occur.<br />
149: * <code>ErrroCodes.INVALID_URI</code> If the URI is not in a valid format. <br />
150: * <code>ErrroCodes.NO_SUCH_DATABASE</code> If a <code>Database</code>
151: * instance could not be found to handle the provided URI.
152: */
153: public static org.xmldb.api.base.Collection getCollection(String uri)
154: throws XMLDBException {
155: Database db = getDatabase(uri);
156:
157: uri = stripURIPrefix(uri);
158:
159: return (org.xmldb.api.base.Collection) db.getCollection(uri);
160: }
161:
162: /**
163: * Returns the Core Level conformance value for the provided URI. The current
164: * API defines valid resuls of "0" or "1" as defined in the XML:DB API
165: * specification.
166: *
167: * @param uri The database specific URI to use to locate the collection.
168: * @return The XML:DB Core Level conformance for the uri.
169: * @exception XMLDBException with expected error codes.<br />
170: * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
171: * specific errors that occur.
172: * <code>ErrroCodes.INVALID_URI</code> If the URI is not in a valid format. <br />
173: * <code>ErrroCodes.NO_SUCH_DATABASE</code> If a <code>Database</code>
174: * instance could not be found to handle the provided URI.
175: */
176: public static String getConformanceLevel(String uri)
177: throws XMLDBException {
178: Database database = getDatabase(uri);
179: return database.getConformanceLevel();
180: }
181:
182: /**
183: * Retrieves a property that has been set for the <code>DatabaseManager</code>.
184: *
185: * @param name The property name
186: * @return The property value
187: */
188: public static String getProperty(String name) {
189: return properties.getProperty(name);
190: }
191:
192: /**
193: * Sets a property for the <code>DatabaseManager</code>.
194: *
195: * @param name The property name
196: * @param value The value to set.
197: */
198: public static void setProperty(String name, String value) {
199: properties.put(name, value);
200: }
201:
202: /**
203: * Retrieves the registered <code>Database</code> instance associated with the provided
204: * URI.
205: *
206: * @param uri The uri containing the database reference.
207: * @return the requested <code>Database</code> instance.
208: */
209: protected static Database getDatabase(String uri)
210: throws XMLDBException {
211: if (!uri.startsWith(URI_PREFIX)) {
212: throw new XMLDBException(ErrorCodes.INVALID_URI);
213: }
214:
215: int end = uri.indexOf(":", URI_PREFIX.length());
216: if (end == -1) {
217: throw new XMLDBException(ErrorCodes.INVALID_URI);
218: }
219:
220: String databaseName = uri.substring(URI_PREFIX.length(), end);
221:
222: Database db = (Database) databases.get(databaseName);
223: if (db == null) {
224: throw new XMLDBException(ErrorCodes.NO_SUCH_DATABASE);
225: }
226:
227: return db;
228: }
229:
230: /**
231: * Removes the URI_PREFIX from the front of the URI. This is so the database
232: * can focus on handling its own URIs.
233: *
234: * @param uri The full URI to strip.
235: * @return The database specific portion of the URI.
236: */
237: protected static String stripURIPrefix(String uri)
238: throws XMLDBException {
239: if (!uri.startsWith(URI_PREFIX)) {
240: throw new XMLDBException(ErrorCodes.INVALID_URI);
241: }
242:
243: String dbURI = uri.substring(URI_PREFIX.length(), uri.length());
244: return dbURI;
245: }
246: }
|