DatabaseManager


1   package org.xmldb.api;
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  import org.xmldb.api.base.*;
57  
58  import java.util.*;
59  
60  /**
61   * <code>DatabaseManager</code> is the entry point for the API and enables you to get the 
62   * initial <code>Collection</code> references necessary to do anything useful with the API.
63   * <code>DatabaseManager</code> is intended to be
64   * provided as a concrete implementation in a particular programming
65   * language. Individual language mappings should define the exact syntax and
66   * semantics of its use. 
67   */
68  public class DatabaseManager    
69  {
70     protected static final String   URI_PREFIX = "xmldb:"; 
71     static Properties properties = new Properties();
72     static Hashtable databases = new Hashtable(); 
73   
74     /**
75      * Returns a list of all available <code>Database</code> implementations 
76      * that have been registered with this <code>DatabaseManager</code>.
77      *
78      * @return An array of <code>Database</code> instances. 
79      *  One for each <code>Database</code> registered
80      *  with the <code>DatabaseManager</code>. If no <code>Database</code>
81      *  instances exist then an empty array is returned.
82      */ 
83     public static Database[] getDatabases () {
84        Enumeration e = databases.elements();
85        Database[] result = new Database[databases.size()];
86        
87        int i = 0;
88        while (e.hasMoreElements()) {
89           result[i] = (Database) e.nextElement();
90           i++;
91        }
92        
93        return result;
94     }
95     
96     /**
97      * Registers a new <code>Database</code> implementation with the
98      * <code>DatabaseManager</code>. 
99      *
100     * @param database The database instance to register.
101     * @exception XMLDBException with expected error codes.<br />
102     *  <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
103     *  specific errors that occur.<br />
104     *  <code>ErrorCodes.INVALID_DATABASE</code> if the provided <code>Database
105     *  </code> instance is invalid.
106     */
107    public static void registerDatabase (Database database) throws XMLDBException {
108       if ((database.getName() == null) || (database.getName().equals(""))) {
109          throw new XMLDBException(ErrorCodes.INVALID_DATABASE);
110       }
111       
112       databases.put(database.getName(), database);
113    }
114    
115    /**
116     * Deregisters a <code>Database</code> implementation from the <code>DatabaseManager</code>. Once a
117     * <code>Database</code> has been deregistered it can no longer be used to handle
118     * requests.
119     *
120     * @param database The <code>Database</code> instance to deregister.
121     * @exception XMLDBException with expected error codes.<br />
122     *  <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
123     *  specific errors that occur.
124     */
125    public static void deregisterDatabase (Database database) 
126          throws XMLDBException {
127       databases.remove(database.getName());
128    }
129    
130    /**
131     * Retreives a <code>Collection</code> instance from the database for the 
132     * given URI. The format of the majority of the URI is database 
133     * implementation specific however the uri must begin with characters xmldb:
134     * and be followed by the name of the database instance as returned by 
135     * <code>Database.getName()</code> and a colon
136     * character. An example would be for the database named "vendordb" the URI
137     * handed to getCollection would look something like the following.
138     * <code>xmldb:vendordb://host:port/path/to/collection</code>. The xmldb:
139     * prefix will be removed from the URI prior to handing the URI to the
140     * <code>Database</code> instance for handling.
141     *
142     * @param uri The database specific URI to use to locate the collection.
143     * @return A <code>Collection</code> instance for the requested collection or
144     *  null if the collection could not be found.
145     * @exception XMLDBException with expected error codes.<br />
146     *  <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
147     *  specific errors that occur.<br />
148     *  <code>ErrroCodes.INVALID_URI</code> If the URI is not in a valid format. <br />
149     *  <code>ErrroCodes.NO_SUCH_DATABASE</code> If a <code>Database</code>
150     *    instance could not be found to handle the provided URI.
151     */
152    public static org.xmldb.api.base.Collection getCollection (String   uri) 
153          throws XMLDBException {
154       Database db = getDatabase(uri);
155      
156       uri = stripURIPrefix(uri);
157       
158       return (org.xmldb.api.base.Collection) db.getCollection(uri);   
159    }
160    
161    /**
162     * Returns the Core Level conformance value for the provided URI. The current
163     * API defines valid resuls of "0" or "1" as defined in the XML:DB API
164     * specification.
165     *
166     * @param uri The database specific URI to use to locate the collection.
167     * @return The XML:DB Core Level conformance for the uri.
168     * @exception XMLDBException with expected error codes.<br />
169     *  <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
170     *  specific errors that occur.
171     *  <code>ErrroCodes.INVALID_URI</code> If the URI is not in a valid format. <br />
172     *  <code>ErrroCodes.NO_SUCH_DATABASE</code> If a <code>Database</code>
173     *    instance could not be found to handle the provided URI.
174     */
175    public static String   getConformanceLevel (String   uri) throws XMLDBException {
176       Database database = getDatabase(uri);
177       return database.getConformanceLevel();
178    }
179    
180    /**
181     * Retrieves a property that has been set for the <code>DatabaseManager</code>.
182     *
183     * @param name The property name
184     * @return The property value
185     */
186    public static String   getProperty (String   name) {
187       return properties.getProperty(name);
188    }
189 
190    /**
191     * Sets a property for the <code>DatabaseManager</code>.
192     *
193     * @param name The property name
194     * @param value The value to set.
195     */   
196    public static void setProperty (String   name, String   value) {
197       properties.put(name, value);
198    }
199    
200    /**
201     * Retrieves the registered <code>Database</code> instance associated with the provided 
202     * URI.
203     *
204     * @param uri The uri containing the database reference.
205     * @return the requested <code>Database</code> instance.
206     */
207    protected static Database getDatabase(String   uri) throws XMLDBException {
208       if (!uri.startsWith(URI_PREFIX)) {
209          throw new XMLDBException(ErrorCodes.INVALID_URI);
210       }
211       
212       int end = uri.indexOf(":", URI_PREFIX.length());      
213       if (end == -1) {
214          throw new XMLDBException(ErrorCodes.INVALID_URI);
215       }
216       
217       String   databaseName = uri.substring(URI_PREFIX.length(), end);
218       
219       Database db = (Database) databases.get(databaseName); 
220       if (db == null) {
221          throw new XMLDBException(ErrorCodes.NO_SUCH_DATABASE);         
222       }
223       
224       return db;
225    }
226    
227    /**
228     * Removes the URI_PREFIX from the front of the URI. This is so the database
229     * can focus on handling its own URIs.
230     *
231     * @param uri The full URI to strip.
232     * @return The database specific portion of the URI.
233     */
234    protected static String   stripURIPrefix(String   uri) throws XMLDBException {
235       if (!uri.startsWith(URI_PREFIX)) {
236          throw new XMLDBException(ErrorCodes.INVALID_URI);
237       }
238                   
239       String   dbURI = uri.substring(URI_PREFIX.length(), uri.length());
240       return dbURI;
241    }
242 }
243
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags