You are viewing a plain text version of this content. The canonical link for it is here.
Posted to xindice-dev@xml.apache.org by vl...@apache.org on 2002/11/21 08:44:36 UTC
cvs commit: xml-xindice/java/src/org/apache/xindice/tools/command ImportTree.java StringSerializer.java
vladimir 2002/11/20 23:44:36
Modified: java/src/org/apache/xindice/client/xmldb DatabaseImpl.java
XindiceCollection.java
java/src/org/apache/xindice/client/xmldb/embed
CollectionImpl.java DatabaseImpl.java
java/src/org/apache/xindice/client/xmldb/services
CollectionManagementServiceImpl.java
CollectionManager.java QueryService.java
XPathQueryServiceImpl.java
XUpdateQueryServiceImpl.java
java/src/org/apache/xindice/client/xmldb/xmlrpc
CollectionImpl.java DatabaseImpl.java
java/src/org/apache/xindice/server XindiceServlet.java
java/src/org/apache/xindice/server/rpc
RPCDefaultMessage.java
java/src/org/apache/xindice/server/rpc/messages
GetCollectionCount.java
java/src/org/apache/xindice/tools DeploymentTask.java
java/src/org/apache/xindice/tools/command ImportTree.java
StringSerializer.java
Log:
Updating some Javadoc to match the XMLDB:API (methods' documentation and parameters).
Revision Changes Path
1.11 +25 -12 xml-xindice/java/src/org/apache/xindice/client/xmldb/DatabaseImpl.java
Index: DatabaseImpl.java
===================================================================
RCS file: /home/cvs/xml-xindice/java/src/org/apache/xindice/client/xmldb/DatabaseImpl.java,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -r1.10 -r1.11
--- DatabaseImpl.java 19 Nov 2002 05:22:19 -0000 1.10
+++ DatabaseImpl.java 21 Nov 2002 07:44:35 -0000 1.11
@@ -111,10 +111,13 @@
}
/**
- * Gets the instance Name
+ * Returns the prefix used in XML:DB to denote URI's that this driver can
+ * handle.
*
- * @return The Name value
- * @exception XMLDBException
+ * @return the prefix driver name
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
*/
public String getName() throws XMLDBException {
return INSTANCE_NAME;
@@ -153,23 +156,33 @@
}
/**
- * Gets the ConformanceLevel attribute of the DatabaseImpl object
+ * Returns the XML:DB API Conformance level for the implementation. This can
+ * be used by client programs to determine what functionality is available to
+ * them.
*
- * @return The ConformanceLevel value
- * @exception XMLDBException Description of Exception
+ * @return the XML:DB API conformance level for this implementation.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
*/
public String getConformanceLevel() throws XMLDBException {
return CONFORMANCE_LEVEL;
}
/**
- * Used by org.xmldb.api.base.DatabaseManager to determine if this database
- * instance is the proper one to handle a request or not.
+ * Determines whether this <code>Database</code> implementation can handle
+ * the URI. It should return true if the Database instance knows how to
+ * handle the URI and false otherwise. <p />
+ *
+ * This method is called by org.xmldb.api.base.DatabaseManager.
*
- * @param uri The uri to test - see getCollection for a description of the
- * format.
+ * @param uri the URI to check for.
* @return true if the URI can be handled, false otherwise.
- * @exception XMLDBException
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrroCodes.INVALID_URI</code> If the URI is not in a valid format. <br />
+ * @see #getCollection for a description of the URI's format
*/
public boolean acceptsURI(String uri) throws XMLDBException {
if ( uri == null || uri.equals("") ) {
1.6 +49 -36 xml-xindice/java/src/org/apache/xindice/client/xmldb/XindiceCollection.java
Index: XindiceCollection.java
===================================================================
RCS file: /home/cvs/xml-xindice/java/src/org/apache/xindice/client/xmldb/XindiceCollection.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- XindiceCollection.java 31 Oct 2002 06:58:48 -0000 1.5
+++ XindiceCollection.java 21 Nov 2002 07:44:35 -0000 1.6
@@ -81,9 +81,8 @@
* This enables the implementation of drivers in just two classes and the
* use of common services implementations.
*
- * @author Kimbro Staken <ks...@xmldatabases.org>
- * @author James Bates <ja...@amplexor.com>
- * @version 1
+ * @author <a href="mailto:kstaken@xmldatabases.org">Kimbro Staken</a>
+ * @author <a href="mailto:james.bates@amplexor.com">James Bates</a>
*/
public abstract class XindiceCollection extends CommonConfigurable implements Collection {
/* Instantiated named services map */
@@ -96,11 +95,9 @@
protected String collPath;
/**
- /* Creates new <code>CollectionImpl</code> instance representing connection
+ * Creates new <code>CollectionImpl</code> instance representing connection
* to server collection.
*
- * @param hostPort hostname and port number in <code>host:port</code> format.
- * Port no is optional, in which case HTTP default is assumed.
* @exception XMLDBException thrown if a connection could not be established,
* because of URL syntax errors, or connection failure, or if no
* collection with path <code>collPath</code> could be located.
@@ -138,13 +135,18 @@
}
}
- /**
- * Returns the list of Services supported by this Collection.
- *
- * @return A list of supported Services
- * @exception XMLDBException
- */
- public org.xmldb.api.base.Service[] getServices() throws XMLDBException {
+ /**
+ * Provides a list of all services known to the collection. If no services
+ * are known an empty list is returned.
+ *
+ * @return An array of registered <code>Service</code> implementations.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrorCodes.COLLECTION_CLOSED</code> if the <code>close</code>
+ * method has been called on the <code>Collection</code><br />
+ */
+ public Service[] getServices() throws XMLDBException {
checkOpen();
Enumeration e = services.elements();
@@ -159,14 +161,19 @@
return result;
}
- /**
- * Get a Service instance based on the name and version.
- *
- * @param name The Service instance to retrieve
- * @param version The version of the service to retrieve.
- * @return The Service instance or null if no service was found.
- * @exception XMLDBException
- */
+ /**
+ * Returns a <code>Service</code> instance for the requested service name and version. If
+ * no <code>Service</code> exists for those parameters a null value is returned.
+ *
+ * @param name Description of Parameter
+ * @param version Description of Parameter
+ * @return the Service instance or null if no Service could be found.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrorCodes.COLLECTION_CLOSED</code> if the <code>close</code>
+ * method has been called on the <code>Collection</code><br />
+ */
public org.xmldb.api.base.Service getService(String name, String version) throws XMLDBException {
checkOpen();
@@ -209,12 +216,12 @@
}
}
- /**
- * Returns this collection's name
- *
- * @return collection name
- */
- public String getName() {
+ /**
+ * Returns the name associated with the <code>Collection</code> instance.
+ *
+ * @return the name of the object.
+ */
+ public String getName() {
return collPath.substring(collPath.lastIndexOf('/') + 1);
}
@@ -266,8 +273,7 @@
/**
* Queries the entire collection and resturns the result
*
- * @param name name of document to query
- * @param queryLang <code>XUpdate</code> or <code>XPath</code>
+ * @param queryLang <code>XUpdate</code> or <code>XPath</code>
* @param query the text of the query statement
* @param nsMap namespace bindings to use when evaluating query
* @return set containing result of query
@@ -296,14 +302,22 @@
/**
* Creates a new child collection in this collection
*
- * @param childName name for new child collection
+ * @param name The name for new child collection
* @return object representing newly created collection
* @exception XMLDBException thrown if collection createion fails for some
* reason
*/
- public abstract Collection createCollection(String childName)
+ public abstract Collection createCollection(String name)
throws XMLDBException;
-
+
+ /**
+ * Creates a new child collection in this collection
+ *
+ * @param name The name for new child collection
+ * @return object representing newly created collection
+ * @exception XMLDBException thrown if collection createion fails for some
+ * reason
+ */
public abstract Collection createCollection(String name, Document configuration) throws XMLDBException;
/**
@@ -326,7 +340,6 @@
/**
* Creates a new Indexer for this collection.
*
- * @param name The name for this indexer
* @param configuration The configuration to use for this indexer.
* @exception XMLDBException
*/
@@ -335,7 +348,7 @@
/**
* Drops the indexer from the collection
*
- * @param indexer The indexer to drop.
+ * @param name The name of the indexer to drop.
* @exception XMLDBException
*/
public abstract void dropIndexer(String name) throws XMLDBException;
@@ -343,8 +356,8 @@
/**
* Shutsdown the Database instance
*
- * @return the result of the shutdown operation
* @exception XMLDBException
*/
public abstract void shutdown() throws XMLDBException;
+
}
1.10 +199 -201 xml-xindice/java/src/org/apache/xindice/client/xmldb/embed/CollectionImpl.java
Index: CollectionImpl.java
===================================================================
RCS file: /home/cvs/xml-xindice/java/src/org/apache/xindice/client/xmldb/embed/CollectionImpl.java,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- CollectionImpl.java 19 Nov 2002 05:20:36 -0000 1.9
+++ CollectionImpl.java 21 Nov 2002 07:44:35 -0000 1.10
@@ -84,9 +84,8 @@
* Implementation of XML:DB's <code>Collection</code> interface using
* XML-RPC to interact with database server
*
- * @author James Bates <ja...@amplexor.com>
- * @author Kimbro Staken <ks...@xmldatabases.org>
- * @version 1
+ * @author <a href="mailto:james.bates@amplexor.com">James Bates</a>
+ * @author <a href="mailto:kstaken@xmldatabases.org">Kimbro Staken</a>
*/
public class CollectionImpl extends XindiceCollection {
Database db = null;
@@ -96,8 +95,6 @@
* Creates new <code>CollectionImpl</code> instance representing connection
* to server collection.
*
- * @param hostPort hostname and port number in <code>host:port</code> format.
- * Port no is optional, in which case HTTP default is assumed.
* @exception XMLDBException thrown if a connection could not be established,
* because of URL syntax errors, or connection failure, or if no
* collection with path <code>collPath</code> could be located.
@@ -118,20 +115,27 @@
}
}
- /**
- * Returns the named resource in this collection
- *
- * @param resourceName resource name
- * @return the resource
- */
- public Resource getResource(String resourceName) throws XMLDBException {
+ /**
+ * Retrieves a <code>Resource</code> from the database. If the
+ * <code>Resource</code> could not be
+ * located a null value will be returned.
+ *
+ * @param id the unique id for the requested resource.
+ * @return The retrieved <code>Resource</code> instance.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrorCodes.COLLECTION_CLOSED</code> if the <code>close</code>
+ * method has been called on the <code>Collection</code><br />
+ */
+ public Resource getResource(String id) throws XMLDBException {
checkOpen();
try {
- Document doc = col.getDocument(resourceName);
+ Document doc = col.getDocument(id);
// This should probably just pass the document.
- return new XMLResourceImpl(resourceName, resourceName, this,
+ return new XMLResourceImpl(id, id, this,
((DocumentImpl) doc).getSymbols(),
((DocumentImpl) doc).getDataBytes());
} catch (Exception e) {
@@ -139,13 +143,17 @@
}
}
- /**
- * Returns number of resources in this collection.
- *
- * @return the number of resources
- * @exception XMLDBException thrown if count could not be obtained for
- * some unexpected reason
- */
+ /**
+ * Returns the number of resources currently stored in this collection or 0
+ * if the collection is empty.
+ *
+ * @return the number of resource in the collection.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrorCodes.COLLECTION_CLOSED</code> if the <code>close</code>
+ * method has been called on the <code>Collection</code><br />
+ */
public int getResourceCount() throws XMLDBException {
checkOpen();
@@ -156,21 +164,28 @@
}
}
- /**
- * Stores contents of reource back to database
- *
- * @param resource the resource to store in database
- * @exception XMLDBException thrown if resource was of incompatible type,
- * or if some other error condition arises.
- */
- public void storeResource(Resource resource) throws XMLDBException {
+ /**
+ * Stores the provided resource into the database. If the resource does not
+ * already exist it will be created. If it does already exist it will be
+ * updated.
+ *
+ * @param res the resource to store in the database.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrorCodes.INVALID_RESOURCE</code> if the <code>Resource</code> is
+ * not valid.
+ * <code>ErrorCodes.COLLECTION_CLOSED</code> if the <code>close</code>
+ * method has been called on the <code>Collection</code><br />
+ */
+ public void storeResource(Resource res) throws XMLDBException {
- if (!(resource instanceof XMLResource)) {
+ if (!(res instanceof XMLResource)) {
throw new XMLDBException(ErrorCodes.INVALID_RESOURCE,
"Only XML resources supported");
}
- if (resource.getContent() == null) {
+ if (res.getContent() == null) {
throw new XMLDBException(ErrorCodes.INVALID_RESOURCE,
"no resource data");
}
@@ -179,15 +194,15 @@
try {
String name = "";
- Node content = ((XMLResourceImpl) resource).getContentAsDOM();
+ Node content = ((XMLResourceImpl) res).getContentAsDOM();
if (content != null && content instanceof Document) {
- if (resource.getId() != null) {
- col.insertDocument(resource.getId(),
+ if (res.getId() != null) {
+ col.insertDocument(res.getId(),
(Document) content);
}
else {
name = col.insertDocument((Document) content).toString();
- ((XMLResourceImpl) resource).setId(name);
+ ((XMLResourceImpl) res).setId(name);
}
}
else {
@@ -199,58 +214,56 @@
}
}
- /**
- * Checks if the collection is still open. Only open collections are safe
- * to work with.
- *
- * @return whether the collection is still open
- */
+ /* see superclass for documentation */
public boolean isOpen() {
return (col != null);
}
- /**
- * Returns XML:DB URI that would retrieve this collection
- *
- * @return a complete XML:DB URI
- */
- public String getURI() {
+ /* see superclass for documentation */
+ public String getURI() {
return "xmldb:" + DatabaseImpl.DRIVER_NAME + "://" + collPath;
}
- /**
- * Returns child collection of this collection with specified name
- *
- * @param colName child's name
- * @return the child collection
- * @exception XMLDBException thrown if there is no such child, or some
- * other connection error occurred
- */
- public org.xmldb.api.base.Collection getChildCollection(String collName) throws XMLDBException {
-
- if (collName.indexOf('/') != -1) {
- throw new XMLDBException(ErrorCodes.INVALID_COLLECTION);
- }
-
- try {
- return new CollectionImpl(db, collPath + "/" + collName);
- }
- catch(XMLDBException e) {
- if(e.errorCode == ErrorCodes.NO_SUCH_COLLECTION) {
- // per getChildCollection contract, return null if not found
- return null;
- }
- throw e;
- }
- }
+ /**
+ * Returns a <code>Collection</code> instance for the requested child collection
+ * if it exists.
+ *
+ * @param name the name of the child collection to retrieve.
+ * @return the requested child collection or null if it couldn't be found.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrorCodes.COLLECTION_CLOSED</code> if the <code>close</code>
+ * method has been called on the <code>Collection</code><br />
+ */
+ public org.xmldb.api.base.Collection getChildCollection(String name) throws XMLDBException {
+
+ if (name.indexOf('/') != -1) {
+ throw new XMLDBException(ErrorCodes.INVALID_COLLECTION);
+ }
+
+ try {
+ return new CollectionImpl(db, collPath + "/" + name);
+ }
+ catch (XMLDBException e) {
+ if (e.errorCode == ErrorCodes.NO_SUCH_COLLECTION) {
+ // per getChildCollection contract, return null if not found
+ return null;
+ }
+ throw e;
+ }
+ }
- /**
- * Creates a new identifier that can be used as name for a resource in this
- * collection.
- *
- * @return the new identifier name
- * @exception XMLDBException thrown in case of some unknwon error condition
- */
+ /**
+ * Creates a new unique ID within the context of the <code>Collection</code>
+ *
+ * @return the created id as a string.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrorCodes.COLLECTION_CLOSED</code> if the <code>close</code>
+ * method has been called on the <code>Collection</code><br />
+ */
public String createId() throws XMLDBException {
checkOpen();
@@ -261,63 +274,75 @@
}
}
- /**
- * Closes the collection.
- *
- * After calling this method, most methods will throw a <code>XMLDBException</code>
- * exception with code <code>ErrorCodes.COLLECTION_CLOSED</code>. The collection
- * object will in effect become useless.
- */
- public void close() throws org.xmldb.api.base.XMLDBException {
+ /**
+ * Releases all resources consumed by the <code>Collection</code>.
+ * The <code>close</code> method must
+ * always be called when use of a <code>Collection</code> is complete. It is
+ * not safe to use a <code>Collection</code> after the <code>close</code>
+ * method has been called.
+ *
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ */
+ public void close() throws org.xmldb.api.base.XMLDBException {
col = null;
db.flushConfig();
}
- /**
- * Returns the parent collection, if any, of this collection
- *
- * @return the parent collectionm
- * @exception XMLDBException thrown if this is the root collection (which
- * has no parent), or in case of some other unknown error.
- */
- public org.xmldb.api.base.Collection getParentCollection() throws XMLDBException {
- // If there's only one slash then it's the root.
- // Not too sure about the robustness of this code.
- if (collPath.equals("/") || collPath.equals("")) {
- return null;
- }
-
- try {
- return new CollectionImpl(db, collPath.substring(0,
- collPath.lastIndexOf('/')));
- }
- catch(XMLDBException e) {
- if(e.errorCode == ErrorCodes.NO_SUCH_COLLECTION) {
- // per getParentCollection contract, return null if no parent
- return null;
- }
- throw e;
- }
- }
-
- /**
- * Removes a (XML) resource from this collection.
- *
- * The resource object itself is still valid after removal, and can be used
- * to modify the resource and possibly store it back to the database again.
- *
- * @param resource resource to remove from the databasew
- * @exception XMLDBException thrown if the resource couldn't be located, or
- * in case of some other error
- */
- public void removeResource(Resource resource) throws XMLDBException {
+ /**
+ * Returns the parent collection for this collection or null if no parent
+ * collection exists.
+ *
+ * @return the parent <code>Collection</code> instance.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrorCodes.COLLECTION_CLOSED</code> if the <code>close</code>
+ * method has been called on the <code>Collection</code><br />
+ */
+ public org.xmldb.api.base.Collection getParentCollection() throws XMLDBException {
+ // If there's only one slash then it's the root.
+ // Not too sure about the robustness of this code.
+ if (collPath.equals("/") || collPath.equals("")) {
+ return null;
+ }
+
+ try {
+ return new CollectionImpl(db, collPath.substring(0,
+ collPath.lastIndexOf('/')));
+ }
+ catch (XMLDBException e) {
+ if (e.errorCode == ErrorCodes.NO_SUCH_COLLECTION) {
+ // per getParentCollection contract, return null if no parent
+ return null;
+ }
+ throw e;
+ }
+ }
+
+ /**
+ * Removes the <code>Resource</code> from the database.
+ *
+ * @param res the resource to remove.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrorCodes.INVALID_RESOURCE</code> if the <code>Resource</code> is
+ * not valid.<br />
+ * <code>ErrorCodes.NO_SUCH_RESOURCE</code> if the <code>Resource</code> is
+ * not known to this <code>Collection</code>.
+ * <code>ErrorCodes.COLLECTION_CLOSED</code> if the <code>close</code>
+ * method has been called on the <code>Collection</code><br />
+ */
+ public void removeResource(Resource res) throws XMLDBException {
- if (!(resource instanceof XMLResource)) {
+ if (!(res instanceof XMLResource)) {
throw new XMLDBException(ErrorCodes.INVALID_RESOURCE,
"Only XML resources supported");
}
- if (resource.getId() == null) {
+ if (res.getId() == null) {
throw new XMLDBException(ErrorCodes.VENDOR_ERROR,
"This resource is a query result and can " +
"not be removed from the database.");
@@ -325,18 +350,25 @@
checkOpen();
try {
- col.remove(resource.getId());
+ col.remove(res.getId());
} catch (Exception e) {
throw new XMLDBException(ErrorCodes.NO_SUCH_RESOURCE, e);
}
}
- /**
- * Lists the available child collections of this collection
- *
- * @return array containing child collection names
- * @exception XMLDBException thrown in case of unknwon error condition
- */
+ /**
+ * Returns a list of collection names naming all child collections
+ * of the current collection. If no child collections exist an empty list is
+ * returned.
+ *
+ * @return an array containing collection names for all child
+ * collections.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrorCodes.COLLECTION_CLOSED</code> if the <code>close</code>
+ * method has been called on the <code>Collection</code><br />
+ */
public String[] listChildCollections() throws XMLDBException {
checkOpen();
@@ -347,12 +379,17 @@
}
}
- /**
- * Returns number of child collections in this collection
- *
- * @return the number of child collections
- * @exception XMLDBException thrown in case of unknwon error condition
- */
+ /**
+ * Returns the number of child collections under this
+ * <code>Collection</code> or 0 if no child collections exist.
+ *
+ * @return the number of child collections.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrorCodes.COLLECTION_CLOSED</code> if the <code>close</code>
+ * method has been called on the <code>Collection</code><br />
+ */
public int getChildCollectionCount() throws XMLDBException {
checkOpen();
@@ -363,12 +400,17 @@
}
}
- /**
- * Lists the available documents of this collection
- *
- * @return array containing resource names
- * @exception XMLDBException thrown in case of unknwon error condition
- */
+ /**
+ * Returns a list of the ids for all resources stored in the collection.
+ *
+ * @return a string array containing the names for all
+ * <code>Resource</code>s in the collection.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrorCodes.COLLECTION_CLOSED</code> if the <code>close</code>
+ * method has been called on the <code>Collection</code><br />
+ */
public String[] listResources() throws XMLDBException {
checkOpen();
@@ -379,17 +421,7 @@
}
}
- /**
- * Queries a specific document or the entire collection and returns result
- *
- * @param name name of document to query, or <code>null</code> to query
- * entire collection.
- * @param queryLang <code>XUpdate</code> or <code>XPath</code>.
- * @param query the text of the query statement
- * @param nsMap namespace bindings to use when evaluating query
- * @return set containing result of query
- * @throws XMLDBException thrown in case of invalid query or other error
- */
+ /* see superclass for documentation */
public ResourceSet query(String name, String queryLang, String query, Hashtable nsMap)
throws XMLDBException {
@@ -433,14 +465,7 @@
}
}
- /**
- * Creates a new child collection in this collection
- *
- * @param childName name for new child collection
- * @return object representing newly created collection
- * @exception XMLDBException thrown if collection createion fails for some
- * reason
- */
+ /* see superclass for documentation */
public org.xmldb.api.base.Collection createCollection(String name)
throws XMLDBException {
@@ -464,9 +489,7 @@
}
}
- /**
- * Creates a new collection.
- */
+ /* see superclass for documentation */
public org.xmldb.api.base.Collection createCollection(String name, Document configuration) throws XMLDBException {
checkOpen();
try {
@@ -480,13 +503,8 @@
"Cannot create child collection", e);
}
}
-
- /**
- * Removes child collection from this collection
- *
- * @param childName name of child collection
- * @exception XMLDBException if an error occurs or the collection does not exist
- */
+
+ /* see superclass for documentation */
public void removeCollection(String childName) throws XMLDBException {
checkOpen();
@@ -498,12 +516,7 @@
}
}
- /**
- * Returns a list of all indexers for this collection.
- *
- * @return the list of indexers
- * @exception XMLDBException
- */
+ /* see superclass for documentation */
public String[] listIndexers() throws XMLDBException {
checkOpen();
try {
@@ -514,13 +527,7 @@
}
}
- /**
- * Creates a new Indexer for this collection.
- *
- * @param name The name for this indexer
- * @param configuration The configuration to use for this indexer.
- * @exception XMLDBException
- */
+ /* see superclass for documentation */
public void createIndexer(Document configuration) throws XMLDBException {
checkOpen();
try {
@@ -531,12 +538,7 @@
}
}
- /**
- * Drops the indexer from the collection
- *
- * @param indexer The indexer to drop.
- * @exception XMLDBException
- */
+ /* see superclass for documentation */
public void dropIndexer(String name) throws XMLDBException {
checkOpen();
try {
@@ -547,12 +549,7 @@
}
}
- /**
- * Shutsdown the Database instance
- *
- * @return the result of the shutdown operation
- * @exception XMLDBException
- */
+ /* see superclass for documentation */
public void shutdown() throws XMLDBException {
try {
db.close();
@@ -561,4 +558,5 @@
throw FaultCodes.createXMLDBException(e);
}
}
+
}
1.7 +66 -36 xml-xindice/java/src/org/apache/xindice/client/xmldb/embed/DatabaseImpl.java
Index: DatabaseImpl.java
===================================================================
RCS file: /home/cvs/xml-xindice/java/src/org/apache/xindice/client/xmldb/embed/DatabaseImpl.java,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- DatabaseImpl.java 19 Nov 2002 05:23:03 -0000 1.6
+++ DatabaseImpl.java 21 Nov 2002 07:44:35 -0000 1.7
@@ -81,10 +81,9 @@
* implements XML:DB's <code>Database</code> interface providing
* embedded access to a Xindice database.
*
- * @author Kimbro Staken <ks...@xmldatabases.org>
- * @author James Bates <ja...@amplexor.com>
+ * @author <a href="mailto:kstaken@xmldatabases.org">Kimbro Staken</a>
+ * @author <a href="mailto:james.bates@amplexor.com">James Bates</a>
* @author <a href="mailto:vladimir@apache.org">Vladimir R. Bossicard</a>
- * @version 1
*/
public class DatabaseImpl extends CommonConfigurable implements org.xmldb.api.base.Database {
@@ -147,48 +146,66 @@
db.setConfig(config);
}
- /**
- * Checks whether this driver can handle the <code>xmldbURI</code> collection
- * URI.
- *
- * @param xmldbURI XML:DB URI to check, without the 'xmldb:' prefix
- * @return whether this driver can handle it
- */
- public boolean acceptsURI(String xmldbURI) throws XMLDBException {
+ /**
+ * Determines whether this <code>Database</code> implementation can handle
+ * the URI. It should return true if the Database instance knows how to
+ * handle the URI and false otherwise.
+ *
+ * @param uri the URI to check for.
+ * @return true if the URI can be handled, false otherwise.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrroCodes.INVALID_URI</code> If the URI is not in a valid format. <br />
+ */
+ public boolean acceptsURI(String uri) throws XMLDBException {
- return ((xmldbURI != null) && xmldbURI.startsWith(getName() + "://"));
+ return ((uri != null) && uri.startsWith(getName() + "://"));
}
- /**
- * Returns the collection referred to by <code>xmldbURI</code>, attempting
- * to authenticate access to it using <code>userName</code> and
- * <code>password</code> credentials.
- *
- * @param xmldbURI XML:DB URI to collection, without the 'xmldb:' prefix
- * @param userName username used to log into database server
- * @param password password used to log into database server
- * @exception XMLDBException thrown in case a connection could not be
- * established
- */
- public Collection getCollection(String xmldbURI, String userName, String password)
+ /**
+ * Retrieves a <code>Collection</code> instance based on the URI provided
+ * in the <code>uri</code> parameter. The format of the URI is defined in the
+ * documentation for DatabaseManager.getCollection().<p/>
+ *
+ * Authentication is handled via username and password however it is not
+ * required that the database support authentication. Databases that do not
+ * support authentication MUST ignore the
+ * <code>username</code> and <code>password</code> if those provided are not
+ * null.
+ *
+ * @param uri the URI to use to locate the collection.
+ * @param password The password to use for authentication to the database or
+ * null if the database does not support authentication.
+ * @return A <code>Collection</code> instance for the requested collection or
+ * null if the collection could not be found.
+ * @return The <code>Collection</code> instance
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrroCodes.INVALID_URI</code> If the URI is not in a valid format. <br />
+ * <code>ErrroCodes.PERMISSION_DENIED</code> If the <code>username</code>
+ * and <code>password</code> were not accepted by the database.
+ */
+ public Collection getCollection(String uri, String userName, String password)
throws XMLDBException {
/* TODO: introduce authentication some day */
- if (!acceptsURI(xmldbURI)) {
+ if (!acceptsURI(uri)) {
throw new XMLDBException(ErrorCodes.INVALID_URI);
}
/* Chop off driver prefix, and '://' */
- xmldbURI = xmldbURI.substring(getName().length() + 3);
+ uri = uri.substring(getName().length() + 3);
/* Extract host name & port, if present */
- int firstSlash = xmldbURI.indexOf('/');
+ int firstSlash = uri.indexOf('/');
if (firstSlash == -1) {
throw new XMLDBException(ErrorCodes.INVALID_URI);
}
- String collPath = xmldbURI.substring(firstSlash);
+ String collPath = uri.substring(firstSlash);
// The path must start with a /
if ( collPath.startsWith( "/" ) ) {
@@ -227,18 +244,31 @@
"Collection name must begin with a '/'" );
}
}
-
- /**
- * Returns the prefix used in XML:DB to denote URI's that this driver can
- * handle.
- *
- * @return the prefix driver name
- */
+
+ /**
+ * Returns the prefix used in XML:DB to denote URI's that this driver can
+ * handle.
+ *
+ * @return the prefix driver name
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ */
public String getName() throws XMLDBException {
return DRIVER_NAME;
}
+ /**
+ * Returns the XML:DB API Conformance level for the implementation. This can
+ * be used by client programs to determine what functionality is available to
+ * them.
+ *
+ * @return the XML:DB API conformance level for this implementation.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ */
public String getConformanceLevel() throws XMLDBException {
return CONFORMANCE_LEVEL;
1.5 +5 -11 xml-xindice/java/src/org/apache/xindice/client/xmldb/services/CollectionManagementServiceImpl.java
Index: CollectionManagementServiceImpl.java
===================================================================
RCS file: /home/cvs/xml-xindice/java/src/org/apache/xindice/client/xmldb/services/CollectionManagementServiceImpl.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- CollectionManagementServiceImpl.java 7 Nov 2002 06:46:01 -0000 1.4
+++ CollectionManagementServiceImpl.java 21 Nov 2002 07:44:35 -0000 1.5
@@ -72,9 +72,8 @@
* XML:DB CollectionManagementService implementation using XML-RPC to
* communicate with Xindice.
*
- * @author James Bates <ja...@amplexor.com>
- * @author Kimbro Staken <ks...@xmldatabases.org>
- * @version 1.0
+ * @author <a href="mailto:james.bates@amplexor.com">James Bates</a>
+ * @author <a href="mailto:kstaken@xmldatabases.org">Kimbro Staken</a>
*/
public class CollectionManagementServiceImpl extends CommonConfigurable
implements CollectionManagementService, CollectionManager, DatabaseInstanceManager {
@@ -241,13 +240,8 @@
throw FaultCodes.createXMLDBException(e);
}
}
-
- /**
- * Drops the indexer from the collection
- *
- * @param name The name of the indexer to drop.
- * @exception XMLDBException
- */
+
+ /* see superclass for documentation */
public void dropIndexer(String name) throws XMLDBException {
try {
((XindiceCollection) coll).dropIndexer(name);
1.6 +2 -2 xml-xindice/java/src/org/apache/xindice/client/xmldb/services/CollectionManager.java
Index: CollectionManager.java
===================================================================
RCS file: /home/cvs/xml-xindice/java/src/org/apache/xindice/client/xmldb/services/CollectionManager.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- CollectionManager.java 31 Oct 2002 06:58:48 -0000 1.5
+++ CollectionManager.java 21 Nov 2002 07:44:35 -0000 1.6
@@ -129,7 +129,7 @@
/**
* Drops the indexer from the collection
*
- * @param indexer The indexer to drop.
+ * @param name The name of the indexer to drop.
* @exception XMLDBException
*/
public void dropIndexer(String name)
1.4 +2 -3 xml-xindice/java/src/org/apache/xindice/client/xmldb/services/QueryService.java
Index: QueryService.java
===================================================================
RCS file: /home/cvs/xml-xindice/java/src/org/apache/xindice/client/xmldb/services/QueryService.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- QueryService.java 31 Oct 2002 06:58:48 -0000 1.3
+++ QueryService.java 21 Nov 2002 07:44:35 -0000 1.4
@@ -75,8 +75,7 @@
* service, as the interface for these queries on the XML-RPC API is more
* or less identical.
*
- * @author James Bates <ja...@amplexor.com>
- * @version 1.0
+ * @author <a href="mailto:james.bates@amplexor.com">James Bates</a>
*/
public abstract class QueryService extends CommonConfigurable implements Service {
1.5 +2 -3 xml-xindice/java/src/org/apache/xindice/client/xmldb/services/XPathQueryServiceImpl.java
Index: XPathQueryServiceImpl.java
===================================================================
RCS file: /home/cvs/xml-xindice/java/src/org/apache/xindice/client/xmldb/services/XPathQueryServiceImpl.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- XPathQueryServiceImpl.java 31 Oct 2002 06:58:48 -0000 1.4
+++ XPathQueryServiceImpl.java 21 Nov 2002 07:44:35 -0000 1.5
@@ -65,8 +65,7 @@
* XML:DB XPathQueryService implementation that uses XML-RPC communication
* with server
*
- * @author James Bates <ja...@amplexor.com>
- * @version 1.0
+ * @author <a href="mailto:james.bates@amplexor.com">James Bates</a>
*/
public class XPathQueryServiceImpl extends QueryService implements XPathQueryService {
1.8 +2 -3 xml-xindice/java/src/org/apache/xindice/client/xmldb/services/XUpdateQueryServiceImpl.java
Index: XUpdateQueryServiceImpl.java
===================================================================
RCS file: /home/cvs/xml-xindice/java/src/org/apache/xindice/client/xmldb/services/XUpdateQueryServiceImpl.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- XUpdateQueryServiceImpl.java 19 Nov 2002 05:21:06 -0000 1.7
+++ XUpdateQueryServiceImpl.java 21 Nov 2002 07:44:35 -0000 1.8
@@ -68,8 +68,7 @@
* XML:DB XUpdateQueryService implementation that uses XML-RPC communication
* with server
*
- * @author James Bates <ja...@amplexor.com>
- * @version 1.0
+ * @author <a href="mailto:james.bates@amplexor.com">James Bates</a>
*/
public class XUpdateQueryServiceImpl extends QueryService implements XUpdateQueryService {
1.16 +200 -198 xml-xindice/java/src/org/apache/xindice/client/xmldb/xmlrpc/CollectionImpl.java
Index: CollectionImpl.java
===================================================================
RCS file: /home/cvs/xml-xindice/java/src/org/apache/xindice/client/xmldb/xmlrpc/CollectionImpl.java,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- CollectionImpl.java 19 Nov 2002 05:21:26 -0000 1.15
+++ CollectionImpl.java 21 Nov 2002 07:44:35 -0000 1.16
@@ -89,9 +89,8 @@
* Implementation of XML:DB's <code>Collection</code> interface using
* XML-RPC to interact with database server
*
- * @author James Bates <ja...@amplexor.com>
- * @author Kimbro Staken <ks...@xmldatabases.org>
- * @version 1
+ * @author <a href="mailto:james.bates@amplexor.com">James Bates</a>
+ * @author <a href="mailto:kstaken@xmldatabases.org">Kimbro Staken</a>
*/
public class CollectionImpl extends XindiceCollection {
/* path to XML-RPC service on database */
@@ -169,12 +168,19 @@
return ((Hashtable) client.execute("run",v)).get(RPCDefaultMessage.RESULT);
}
- /**
- * Returns the named resource in this collection
- *
- * @param resourceName resource name
- * @return the resource
- */
+ /**
+ * Retrieves a <code>Resource</code> from the database. If the
+ * <code>Resource</code> could not be
+ * located a null value will be returned.
+ *
+ * @param id the unique id for the requested resource.
+ * @return The retrieved <code>Resource</code> instance.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrorCodes.COLLECTION_CLOSED</code> if the <code>close</code>
+ * method has been called on the <code>Collection</code><br />
+ */
public Resource getResource(String resourceName) throws XMLDBException {
checkOpen();
@@ -205,13 +211,17 @@
}
}
- /**
- * Returns number of resources in this collection.
- *
- * @return the number of resources
- * @exception XMLDBException thrown if count could not be obtained for
- * some unexpected reason
- */
+ /**
+ * Returns the number of resources currently stored in this collection or 0
+ * if the collection is empty.
+ *
+ * @return the number of resource in the collection.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrorCodes.COLLECTION_CLOSED</code> if the <code>close</code>
+ * method has been called on the <code>Collection</code><br />
+ */
public int getResourceCount() throws XMLDBException {
checkOpen();
@@ -227,22 +237,29 @@
}
}
- /**
- * Stores contents of reource back to database
- *
- * @param resource the resource to store in database
- * @exception XMLDBException thrown if resource was of incompatible type,
- * or if some other error condition arises.
- */
- public void storeResource(Resource resource) throws XMLDBException {
+ /**
+ * Stores the provided resource into the database. If the resource does not
+ * already exist it will be created. If it does already exist it will be
+ * updated.
+ *
+ * @param res the resource to store in the database.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrorCodes.INVALID_RESOURCE</code> if the <code>Resource</code> is
+ * not valid.
+ * <code>ErrorCodes.COLLECTION_CLOSED</code> if the <code>close</code>
+ * method has been called on the <code>Collection</code><br />
+ */
+ public void storeResource(Resource res) throws XMLDBException {
- if (!(resource instanceof XMLResource)) {
+ if (!(res instanceof XMLResource)) {
throw new XMLDBException(ErrorCodes.INVALID_RESOURCE,
"Only XML resources supported");
}
- if (resource.getContent() == null) {
+ if (res.getContent() == null) {
throw new XMLDBException(ErrorCodes.INVALID_RESOURCE,
"no resource data");
@@ -252,11 +269,11 @@
Hashtable params = new Hashtable();
params.put(RPCDefaultMessage.COLLECTION, collPath);
- params.put(RPCDefaultMessage.NAME, resource.getId());
- params.put(RPCDefaultMessage.DOCUMENT, resource.getContent());
+ params.put(RPCDefaultMessage.NAME, res.getId());
+ params.put(RPCDefaultMessage.DOCUMENT, res.getContent());
String name = (String) runRemoteCommand("InsertDocument", params);
- ((XMLResourceImpl) resource).setId(name);
+ ((XMLResourceImpl) res).setId(name);
} catch (Exception e) {
@@ -264,61 +281,60 @@
}
}
- /**
- * Checks if the collection is still open. Only open collections are safe
- * to work with.
- *
- * @return whether the collection is still open
- */
+ /* see superclass for documentation */
public boolean isOpen() {
return (client != null);
}
- /**
- * Returns XML:DB URI that would retrieve this collection
- *
- * @return a complete XML:DB URI
- */
+ /* see superclass for documentation */
public String getURI() {
return "xmldb:" + DatabaseImpl.DRIVER_NAME + "://"
+ hostPort + collPath;
}
-
- /**
- * Returns child collection of this collection with specified name
- *
- * @param colName child's name
- * @return the child collection or null if not found
- * @exception XMLDBException if an error occurs
- */
- public Collection getChildCollection(String collName) throws XMLDBException {
- if (collName.indexOf('/') != -1) {
-
- throw new XMLDBException(ErrorCodes.INVALID_COLLECTION);
- }
-
- try {
- return new CollectionImpl(hostPort, collPath + "/" + collName);
- }
- catch(XMLDBException e) {
- if(e.errorCode == ErrorCodes.NO_SUCH_COLLECTION) {
- // per getChildCollection contract, return null if not found
- return null;
- }
- throw e;
- }
- }
-
- /**
- * Creates a new identifier that can be used as name for a resource in this
- * collection.
- *
- * @return the new identifier name
- * @exception XMLDBException thrown in case of some unknwon error condition
- */
+ /**
+ * Returns a <code>Collection</code> instance for the requested child collection
+ * if it exists.
+ *
+ * @param name the name of the child collection to retrieve.
+ * @return the requested child collection or null if it couldn't be found.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrorCodes.COLLECTION_CLOSED</code> if the <code>close</code>
+ * method has been called on the <code>Collection</code><br />
+ */
+ public Collection getChildCollection(String name) throws XMLDBException {
+
+ if (name.indexOf('/') != -1) {
+
+ throw new XMLDBException(ErrorCodes.INVALID_COLLECTION);
+ }
+
+ try {
+ return new CollectionImpl(hostPort, collPath + "/" + name);
+ }
+ catch (XMLDBException e) {
+ if (e.errorCode == ErrorCodes.NO_SUCH_COLLECTION) {
+ // per getChildCollection contract, return null if not found
+ return null;
+ }
+ throw e;
+ }
+ }
+
+ /**
+ * Creates a new unique ID within the context of the <code>Collection</code>
+ *
+ * @return the created id as a string.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrorCodes.COLLECTION_CLOSED</code> if the <code>close</code>
+ * method has been called on the <code>Collection</code><br />
+ */
public String createId() throws XMLDBException {
checkOpen();
@@ -333,64 +349,76 @@
}
}
- /**
- * Closes physical connection to server containing this collection.
- *
- * After calling this method, most methods will throw a <code>XMLDBException</code>
- * exception with code <code>ErrorCodes.COLLECTION_CLOSED</code>. The collection
- * object will in effect become useless.
- */
- public void close() throws org.xmldb.api.base.XMLDBException {
+ /**
+ * Releases all resources consumed by the <code>Collection</code>.
+ * The <code>close</code> method must
+ * always be called when use of a <code>Collection</code> is complete. It is
+ * not safe to use a <code>Collection</code> after the <code>close</code>
+ * method has been called.
+ *
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ */
+ public void close() throws org.xmldb.api.base.XMLDBException {
client = null;
}
-
- /**
- * Returns the parent collection, if any, of this collection
- *
- * @return the parent collectionm
- * @exception XMLDBException thrown if this is the root collection (which
- * has no parent), or in case of some other unknown error.
- */
- public Collection getParentCollection() throws XMLDBException {
- // If there's only one slash then it's the root.
- if (collPath.lastIndexOf("/") == 0) {
- return null;
- }
-
- try {
- return new CollectionImpl(hostPort, collPath.substring(0,
- collPath.lastIndexOf('/')));
- }
- catch(XMLDBException e) {
- if(e.errorCode == ErrorCodes.NO_SUCH_COLLECTION) {
- // per getParentCollection contract, return null if no parent
- return null;
- }
- throw e;
- }
- }
-
- /**
- * Removes a (XML) resource from this collection.
- *
- * The resource object itself is still valid after removal, and can be used
- * to modify the resource and possibly store it back to the database again.
- *
- * @param resource resource to remove from the databasew
- * @exception XMLDBException thrown if the resource couldn't be located, or
- * in case of some other error
- */
- public void removeResource(Resource resource) throws XMLDBException {
+ /**
+ * Returns the parent collection for this collection or null if no parent
+ * collection exists.
+ *
+ * @return the parent <code>Collection</code> instance.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrorCodes.COLLECTION_CLOSED</code> if the <code>close</code>
+ * method has been called on the <code>Collection</code><br />
+ */
+ public Collection getParentCollection() throws XMLDBException {
+
+ // If there's only one slash then it's the root.
+ if (collPath.lastIndexOf("/") == 0) {
+ return null;
+ }
+
+ try {
+ return new CollectionImpl(hostPort, collPath.substring(0,
+ collPath.lastIndexOf('/')));
+ }
+ catch (XMLDBException e) {
+ if (e.errorCode == ErrorCodes.NO_SUCH_COLLECTION) {
+ // per getParentCollection contract, return null if no parent
+ return null;
+ }
+ throw e;
+ }
+ }
+
+ /**
+ * Removes the <code>Resource</code> from the database.
+ *
+ * @param res the resource to remove.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrorCodes.INVALID_RESOURCE</code> if the <code>Resource</code> is
+ * not valid.<br />
+ * <code>ErrorCodes.NO_SUCH_RESOURCE</code> if the <code>Resource</code> is
+ * not known to this <code>Collection</code>.
+ * <code>ErrorCodes.COLLECTION_CLOSED</code> if the <code>close</code>
+ * method has been called on the <code>Collection</code><br />
+ */
+ public void removeResource(Resource res) throws XMLDBException {
- if (!(resource instanceof XMLResource)) {
+ if (!(res instanceof XMLResource)) {
throw new XMLDBException(ErrorCodes.INVALID_RESOURCE,
"Only XML resources supported");
}
- if (resource.getId() == null) {
+ if (res.getId() == null) {
throw new XMLDBException(ErrorCodes.VENDOR_ERROR,
"This resource is a query result and can " +
"not be removed from the database.");
@@ -401,19 +429,26 @@
Hashtable params = new Hashtable();
params.put(RPCDefaultMessage.COLLECTION, collPath);
- params.put(RPCDefaultMessage.NAME, resource.getId());
+ params.put(RPCDefaultMessage.NAME, res.getId());
runRemoteCommand("RemoveDocument", params);
} catch (Exception e) {
throw new XMLDBException(ErrorCodes.NO_SUCH_RESOURCE, e);
}
}
-
- /**
- * Lists the available child collections of this collection
- *
- * @return array containing child collection names
- * @exception XMLDBException thrown in case of unknwon error condition
- */
+
+ /**
+ * Returns a list of collection names naming all child collections
+ * of the current collection. If no child collections exist an empty list is
+ * returned.
+ *
+ * @return an array containing collection names for all child
+ * collections.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrorCodes.COLLECTION_CLOSED</code> if the <code>close</code>
+ * method has been called on the <code>Collection</code><br />
+ */
public String[] listChildCollections() throws XMLDBException {
checkOpen();
@@ -429,13 +464,18 @@
throw new XMLDBException(ErrorCodes.UNKNOWN_ERROR, e);
}
}
-
- /**
- * Returns number of child collections in this collection
- *
- * @return the number of child collections
- * @exception XMLDBException thrown in case of unknwon error condition
- */
+
+ /**
+ * Returns the number of child collections under this
+ * <code>Collection</code> or 0 if no child collections exist.
+ *
+ * @return the number of child collections.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrorCodes.COLLECTION_CLOSED</code> if the <code>close</code>
+ * method has been called on the <code>Collection</code><br />
+ */
public int getChildCollectionCount() throws XMLDBException {
checkOpen();
@@ -450,13 +490,18 @@
throw new XMLDBException(ErrorCodes.UNKNOWN_ERROR, e);
}
}
-
- /**
- * Lists the available documents of this collection
- *
- * @return array containing resource names
- * @exception XMLDBException thrown in case of unknwon error condition
- */
+
+ /**
+ * Returns a list of the ids for all resources stored in the collection.
+ *
+ * @return a string array containing the names for all
+ * <code>Resource</code>s in the collection.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrorCodes.COLLECTION_CLOSED</code> if the <code>close</code>
+ * method has been called on the <code>Collection</code><br />
+ */
public String[] listResources() throws XMLDBException {
checkOpen();
@@ -471,19 +516,9 @@
throw new XMLDBException(ErrorCodes.UNKNOWN_ERROR, e);
}
- }
+ }
- /**
- * Queries a specific document or the entire collection and returns result
- *
- * @param name name of document to query, or <code>null</code> to query
- * entire collection.
- * @param queryLang <code>XUpdate</code> or <code>XPath</code>.
- * @param query the text of the query statement
- * @param nsMap namespace bindings to use when evaluating query
- * @return set containing result of query
- * @throws XMLDBException thrown in case of invalid query or other error
- */
+ /* see superclass for documentation */
public ResourceSet query(String name, String queryLang, String query, Hashtable nsMap)
throws XMLDBException {
@@ -527,15 +562,8 @@
throw FaultCodes.createXMLDBException(FaultCodes.QRY_PROCESSING_ERROR, "Query error", e);
}
}
-
- /**
- * Creates a new child collection in this collection
- *
- * @param childName name for new child collection
- * @return object representing newly created collection
- * @exception XMLDBException thrown if collection createion fails for some
- * reason
- */
+
+ /* see superclass for documentation */
public Collection createCollection(String childName)
throws XMLDBException {
@@ -555,6 +583,7 @@
}
}
+ /* see superclass for documentation */
public Collection createCollection(String name, Document configuration) throws XMLDBException {
checkOpen();
try {
@@ -573,14 +602,8 @@
"Cannot create child collection", e);
}
}
-
- /**
- * Removes child collection from this collection
- *
- * @param childName name of child collection
- * @exception XMLDBException thrown if collection createion fails for some
- * reason
- */
+
+ /* see superclass for documentation */
public void removeCollection(String childName) throws XMLDBException {
checkOpen();
@@ -597,12 +620,7 @@
}
}
- /**
- * Returns a list of all indexers for this collection.
- *
- * @return the list of indexers
- * @exception XMLDBException
- */
+ /* see superclass for documentation */
public String[] listIndexers() throws XMLDBException {
checkOpen();
try {
@@ -617,13 +635,7 @@
}
}
- /**
- * Creates a new Indexer for this collection.
- *
- * @param name The name for this indexer
- * @param configuration The configuration to use for this indexer.
- * @exception XMLDBException
- */
+ /* see superclass for documentation */
public void createIndexer(Document configuration) throws XMLDBException {
checkOpen();
try {
@@ -639,12 +651,7 @@
}
}
- /**
- * Drops the indexer from the collection
- *
- * @param indexer The indexer to drop.
- * @exception XMLDBException
- */
+ /* see superclass for documentation */
public void dropIndexer(String name) throws XMLDBException {
checkOpen();
try {
@@ -659,12 +666,7 @@
}
}
- /**
- * Shutsdown the Database instance
- *
- * @return the result of the shutdown operation
- * @exception XMLDBException
- */
+ /* see superclass for documentation */
public void shutdown() throws XMLDBException {
checkOpen();
try {
1.7 +59 -29 xml-xindice/java/src/org/apache/xindice/client/xmldb/xmlrpc/DatabaseImpl.java
Index: DatabaseImpl.java
===================================================================
RCS file: /home/cvs/xml-xindice/java/src/org/apache/xindice/client/xmldb/xmlrpc/DatabaseImpl.java,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- DatabaseImpl.java 5 Nov 2002 05:55:48 -0000 1.6
+++ DatabaseImpl.java 21 Nov 2002 07:44:35 -0000 1.7
@@ -71,8 +71,7 @@
* Note this class is a database <em>driver</em>, and one class of this database
* could be used to connect to <em>many</em> different databases.
*
- * @author James Bates <ja...@amplexor.com>
- * @version 1
+ * @author <a href="mailto:james.bates@amplexor.com">James Bates</a>
*/
public class DatabaseImpl extends CommonConfigurable implements Database {
@@ -82,51 +81,69 @@
/* XML:DB conformance level of this driver */
private String CONFORMANCE_LEVEL = "0";
- /**
- * Checks whether this driver can handle the <code>xmldbURI</code> collection
- * URI.
- *
- * @param xmldbURI XML:DB URI to check, without the 'xmldb:' prefix
- * @return whether this driver can handle it
- */
- public boolean acceptsURI(String xmldbURI) throws XMLDBException {
+ /**
+ * Determines whether this <code>Database</code> implementation can handle
+ * the URI. It should return true if the Database instance knows how to
+ * handle the URI and false otherwise.
+ *
+ * @param uri the URI to check for.
+ * @return true if the URI can be handled, false otherwise.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrroCodes.INVALID_URI</code> If the URI is not in a valid format. <br />
+ */
+ public boolean acceptsURI(String uri) throws XMLDBException {
- return ((xmldbURI != null) && xmldbURI.startsWith(getName() + "://"));
+ return ((uri != null) && uri.startsWith(getName() + "://"));
}
- /**
- * Returns the collection referred to by <code>xmldbURI</code>, attempting
- * to authenticate access to it using <code>userName</code> and
- * <code>password</code> credentials.
- *
- * @param xmldbURI XML:DB URI to collection, without the 'xmldb:' prefix
- * @param userName username used to log into database server
- * @param password password used to log into database server
- * @exception XMLDBException thrown in case a connection could not be
- * established
- */
- public Collection getCollection(String xmldbURI, String userName, String password)
+ /**
+ * Retrieves a <code>Collection</code> instance based on the URI provided
+ * in the <code>uri</code> parameter. The format of the URI is defined in the
+ * documentation for DatabaseManager.getCollection().<p/>
+ *
+ * Authentication is handled via username and password however it is not
+ * required that the database support authentication. Databases that do not
+ * support authentication MUST ignore the
+ * <code>username</code> and <code>password</code> if those provided are not
+ * null.
+ *
+ * @param uri the URI to use to locate the collection.
+ * @param password The password to use for authentication to the database or
+ * null if the database does not support authentication.
+ * @return A <code>Collection</code> instance for the requested collection or
+ * null if the collection could not be found.
+ * @return The <code>Collection</code> instance
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ * <code>ErrroCodes.INVALID_URI</code> If the URI is not in a valid format. <br />
+ * <code>ErrroCodes.PERMISSION_DENIED</code> If the <code>username</code>
+ * and <code>password</code> were not accepted by the database.
+ */
+ public Collection getCollection(String uri, String userName, String password)
throws XMLDBException {
/* TODO: introduce authentication some day */
- if (!acceptsURI(xmldbURI)) {
+ if (!acceptsURI(uri)) {
throw new XMLDBException(ErrorCodes.INVALID_URI);
}
/* Chop off driver prefix, and '://' */
- xmldbURI = xmldbURI.substring(getName().length() + 3);
+ uri = uri.substring(getName().length() + 3);
/* Extract host name & port, if present */
- int firstSlash = xmldbURI.indexOf('/');
+ int firstSlash = uri.indexOf('/');
if (firstSlash == -1) {
throw new XMLDBException(ErrorCodes.INVALID_URI);
}
- String hostPort = xmldbURI.substring(0, firstSlash);
- String collPath = xmldbURI.substring(firstSlash);
+ String hostPort = uri.substring(0, firstSlash);
+ String collPath = uri.substring(firstSlash);
/* Absent host defaults to localhost and standard Xindice HTTP port */
if (hostPort.equals("")) {
@@ -151,12 +168,25 @@
* handle.
*
* @return the prefix driver name
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
*/
public String getName() throws XMLDBException {
return DRIVER_NAME;
}
+ /**
+ * Returns the XML:DB API Conformance level for the implementation. This can
+ * be used by client programs to determine what functionality is available to
+ * them.
+ *
+ * @return the XML:DB API conformance level for this implementation.
+ * @exception XMLDBException with expected error codes.<br />
+ * <code>ErrorCodes.VENDOR_ERROR</code> for any vendor
+ * specific errors that occur.<br />
+ */
public String getConformanceLevel() throws XMLDBException {
return CONFORMANCE_LEVEL;
1.8 +2 -2 xml-xindice/java/src/org/apache/xindice/server/XindiceServlet.java
Index: XindiceServlet.java
===================================================================
RCS file: /home/cvs/xml-xindice/java/src/org/apache/xindice/server/XindiceServlet.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- XindiceServlet.java 17 Nov 2002 20:32:47 -0000 1.7
+++ XindiceServlet.java 21 Nov 2002 07:44:36 -0000 1.8
@@ -91,7 +91,7 @@
* database instance.
*
* @author <a href="mailto:kstaken@xmldatabases.org">Kimbro Staken</a>
- * @author <a href="mailto:vladimir@bossicard.com">Vladimir R. Bossicard</a>
+ * @author <a href="mailto:vladimir@apache.org">Vladimir R. Bossicard</a>
*/
public class XindiceServlet
extends HttpServlet {
1.5 +2 -3 xml-xindice/java/src/org/apache/xindice/server/rpc/RPCDefaultMessage.java
Index: RPCDefaultMessage.java
===================================================================
RCS file: /home/cvs/xml-xindice/java/src/org/apache/xindice/server/rpc/RPCDefaultMessage.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- RPCDefaultMessage.java 5 Nov 2002 07:26:14 -0000 1.4
+++ RPCDefaultMessage.java 21 Nov 2002 07:44:36 -0000 1.5
@@ -65,7 +65,7 @@
import java.util.Hashtable;
/**
- * @author kstaken
+ * @author <a href="mailto:kstaken@xmldatabases.org">Kimbro Staken</a>
*/
public class RPCDefaultMessage implements RPCMessage {
@@ -104,7 +104,6 @@
* @param name The collection to retrieve
* @return The Collection value
* @exception Exception
- * @author kstaken
*/
protected Collection getCollection( String name ) throws Exception {
// Get rid of any trailling slashes.
1.3 +2 -3 xml-xindice/java/src/org/apache/xindice/server/rpc/messages/GetCollectionCount.java
Index: GetCollectionCount.java
===================================================================
RCS file: /home/cvs/xml-xindice/java/src/org/apache/xindice/server/rpc/messages/GetCollectionCount.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- GetCollectionCount.java 31 Oct 2002 07:00:44 -0000 1.2
+++ GetCollectionCount.java 21 Nov 2002 07:44:36 -0000 1.3
@@ -67,8 +67,7 @@
/**
* XML-RPC message to list number of child collections in a collection
*
- * @author James Bates <ja...@amplexor.com>
- * @version 1
+ * @author <a href="mailto:james.bates@amplexor.com">James Bates</a>
*/
public class GetCollectionCount extends RPCDefaultMessage {
1.5 +3 -5 xml-xindice/java/src/org/apache/xindice/tools/DeploymentTask.java
Index: DeploymentTask.java
===================================================================
RCS file: /home/cvs/xml-xindice/java/src/org/apache/xindice/tools/DeploymentTask.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- DeploymentTask.java 19 Nov 2002 05:21:49 -0000 1.4
+++ DeploymentTask.java 21 Nov 2002 07:44:36 -0000 1.5
@@ -67,10 +67,8 @@
/**
* Handles basic deployment of Xindice services using ant.
*
- * @author kstaken
- * @created October 20, 2000
- **/
-
+ * @author <a href="mailto:kstaken@xmldatabases.org">Kimbro Staken</a>
+ */
public class DeploymentTask extends Task {
private String collection = "test/ocs";
private String db = "Database";
1.7 +32 -30 xml-xindice/java/src/org/apache/xindice/tools/command/ImportTree.java
Index: ImportTree.java
===================================================================
RCS file: /home/cvs/xml-xindice/java/src/org/apache/xindice/tools/command/ImportTree.java,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- ImportTree.java 19 Nov 2002 05:17:34 -0000 1.6
+++ ImportTree.java 21 Nov 2002 07:44:36 -0000 1.7
@@ -148,7 +148,7 @@
baseCollection = createCollection(baseCollection, directory.getName());
// Get a directory listing and loop over
- File[] subdirs = directory.listFiles(new MyFileFilter(ext));
+ File[] subdirs = directory.listFiles(new ExtensionFileFilter(ext));
for (int i = 0; i < subdirs.length; i++) {
// Is this a directory? If so, call ourselves recursively
@@ -197,38 +197,40 @@
return baseCollection + "/" + newCollection;
}
-}
-
-/**
- * Allow us to filter directory listings over certain file extensions
- */
-class MyFileFilter implements FileFilter {
-
- String extension = "";
/**
- * TODO: Constructor for the MyFileFilter object
- *
- * @param ext Description of Parameter
+ * Allow us to filter directory listings over certain file extensions
*/
- public MyFileFilter(String ext) {
- extension = ext;
- }
+ private static class ExtensionFileFilter implements FileFilter {
- /**
- * TODO: Description of the Method
- *
- * @param file Description of Parameter
- * @return Description of the Returned Value
- */
- public boolean accept(File file) {
- if (extension != "") {
- return file.getName().endsWith("." + extension) || file.isDirectory();
- }
- else {
- return true;
+ private String extension = "";
+
+ /**
+ * Constructs an <code>MyFileFiler</code> instance with a specific
+ * extension.
+ *
+ * @param extension The file's extension
+ */
+ public ExtensionFileFilter(String extension) {
+ this.extension = extension;
+ }
+
+ /**
+ * Tests whether or not the specified abstract pathname should be
+ * included in a pathname list.
+ *
+ * @param pathname The abstract pathname to be tested
+ * @return <code>true</code> if and only if <code>pathname</code>
+ * should be included
+ */
+ public boolean accept(File pathname) {
+ if (this.extension != "") {
+ return pathname.getName().endsWith("." + this.extension) || pathname.isDirectory();
+ }
+ else {
+ return true;
+ }
}
}
-}
-
+}
1.5 +1 -2 xml-xindice/java/src/org/apache/xindice/tools/command/StringSerializer.java
Index: StringSerializer.java
===================================================================
RCS file: /home/cvs/xml-xindice/java/src/org/apache/xindice/tools/command/StringSerializer.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- StringSerializer.java 4 Nov 2002 06:39:55 -0000 1.4
+++ StringSerializer.java 21 Nov 2002 07:44:36 -0000 1.5
@@ -71,8 +71,7 @@
* After calling endDocument(), the string becomes available by calling
* <code>toString()</code>
*
- * @author james.bates@amplexor.com
- * @version 1
+ * @author <a href="mailto:james.bates@amplexor.com">James Bates</a>
*/
public class StringSerializer implements ContentHandler, LexicalHandler {