org.xmldb.api.base.Collection Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of xmldb-api Show documentation
Show all versions of xmldb-api Show documentation
XML:DB API patched for eXist-db
The newest version!
package org.xmldb.api.base;
/*
* The XML:DB Initiative Software License, Version 1.0
*
*
* Copyright (c) 2000-2003 The XML:DB Initiative. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution,
* if any, must include the following acknowledgment:
* "This product includes software developed by the
* XML:DB Initiative (http://www.xmldb.org/)."
* Alternately, this acknowledgment may appear in the software itself,
* if and wherever such third-party acknowledgments normally appear.
*
* 4. The name "XML:DB Initiative" must not be used to endorse or
* promote products derived from this software without prior written
* permission. For written permission, please contact [email protected].
*
* 5. Products derived from this software may not be called "XML:DB",
* nor may "XML:DB" appear in their name, without prior written
* permission of the XML:DB Initiative.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the XML:DB Initiative. For more information
* on the XML:DB Initiative, please see Collection represents a collection of Resources
* stored within an XML
* database. An XML
* database MAY expose collections as a hierarchical set of parent and child
* collections.
*
* A Collection provides access to the Resources
* stored by the Collection and to Service instances
* that can operate against the Collection and the
* Resources stored within it. The Service mechanism
* provides the ability to extend the functionality of a Collection
* in ways that allows optional functionality to be enabled for the Collection.
*/
public interface Collection extends Configurable {
/**
* Returns the name associated with the Collection instance.
*
* @return the name of the object.
* @exception XMLDBException with expected error codes.
* ErrorCodes.VENDOR_ERROR for any vendor
* specific errors that occur.
*/
String getName() 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 Service implementations.
* @exception XMLDBException with expected error codes.
* ErrorCodes.VENDOR_ERROR for any vendor
* specific errors that occur.
* ErrorCodes.COLLECTION_CLOSED if the close
* method has been called on the Collection
*/
Service[] getServices() throws XMLDBException;
/**
* Returns a Service instance for the requested service name and version. If
* no Service 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.
* ErrorCodes.VENDOR_ERROR for any vendor
* specific errors that occur.
* ErrorCodes.COLLECTION_CLOSED if the close
* method has been called on the Collection
*/
Service getService(String name, String version) throws XMLDBException;
/**
* Returns the parent collection for this collection or null if no parent
* collection exists.
*
* @return the parent Collection instance.
* @exception XMLDBException with expected error codes.
* ErrorCodes.VENDOR_ERROR for any vendor
* specific errors that occur.
* ErrorCodes.COLLECTION_CLOSED if the close
* method has been called on the Collection
*/
Collection getParentCollection() throws XMLDBException;
/**
* Returns the number of child collections under this
* Collection or 0 if no child collections exist.
*
* @return the number of child collections.
* @exception XMLDBException with expected error codes.
* ErrorCodes.VENDOR_ERROR for any vendor
* specific errors that occur.
* ErrorCodes.COLLECTION_CLOSED if the close
* method has been called on the Collection
*/
int getChildCollectionCount() throws XMLDBException;
/**
* 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.
* ErrorCodes.VENDOR_ERROR for any vendor
* specific errors that occur.
* ErrorCodes.COLLECTION_CLOSED if the close
* method has been called on the Collection
*/
String[] listChildCollections() throws XMLDBException;
/**
* Returns a Collection 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.
* ErrorCodes.VENDOR_ERROR for any vendor
* specific errors that occur.
* ErrorCodes.COLLECTION_CLOSED if the close
* method has been called on the Collection
*/
Collection getChildCollection(String name) throws XMLDBException;
/**
* 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.
* ErrorCodes.VENDOR_ERROR for any vendor
* specific errors that occur.
* ErrorCodes.COLLECTION_CLOSED if the close
* method has been called on the Collection
*/
int getResourceCount() throws XMLDBException;
/**
* Returns a list of the ids for all resources stored in the collection.
*
* @return a string array containing the names for all
* Resources in the collection.
* @exception XMLDBException with expected error codes.
* ErrorCodes.VENDOR_ERROR for any vendor
* specific errors that occur.
* ErrorCodes.COLLECTION_CLOSED if the close
* method has been called on the Collection
*/
String[] listResources() throws XMLDBException;
/**
* Creates a new empty Resource with the provided id.
* The type of Resource
* returned is determined by the type parameter. The XML:DB API currently
* defines "XMLResource" and "BinaryResource" as valid resource types.
* The id provided must be unique within the scope of the
* collection. If
* id is null or its value is empty then an id is generated by
* calling createId(). The
* Resource created is not stored to the database until
* storeResource() is called.
*
* @param id the unique id to associate with the created Resource.
* @param type the Resource type to create.
* @return an empty Resource instance.
* @exception XMLDBException with expected error codes.
* ErrorCodes.VENDOR_ERROR for any vendor
* specific errors that occur.
* ErrorCodes.UNKNOWN_RESOURCE_TYPE if the type
* parameter is not a known Resource type.
* ErrorCodes.COLLECTION_CLOSED if the close
* method has been called on the Collection
*/
Resource createResource(String id, String type) throws XMLDBException;
/**
* Removes the Resource from the database.
*
* @param res the resource to remove.
* @exception XMLDBException with expected error codes.
* ErrorCodes.VENDOR_ERROR for any vendor
* specific errors that occur.
* ErrorCodes.INVALID_RESOURCE if the Resource is
* not valid.
* ErrorCodes.NO_SUCH_RESOURCE if the Resource is
* not known to this Collection.
* ErrorCodes.COLLECTION_CLOSED if the close
* method has been called on the Collection
*/
void removeResource(Resource res) 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.
* ErrorCodes.VENDOR_ERROR for any vendor
* specific errors that occur.
* ErrorCodes.INVALID_RESOURCE if the Resource is
* not valid.
* ErrorCodes.COLLECTION_CLOSED if the close
* method has been called on the Collection
*/
void storeResource(Resource res) throws XMLDBException;
/**
* Retrieves a Resource from the database. If the
* Resource could not be
* located a null value will be returned.
*
* @param id the unique id for the requested resource.
* @return The retrieved Resource instance.
* @exception XMLDBException with expected error codes.
* ErrorCodes.VENDOR_ERROR for any vendor
* specific errors that occur.
* ErrorCodes.COLLECTION_CLOSED if the close
* method has been called on the Collection
*/
Resource getResource(String id) throws XMLDBException;
/**
* Creates a new unique ID within the context of the Collection
*
* @return the created id as a string.
* @exception XMLDBException with expected error codes.
* ErrorCodes.VENDOR_ERROR for any vendor
* specific errors that occur.
* ErrorCodes.COLLECTION_CLOSED if the close
* method has been called on the Collection
*/
String createId() throws XMLDBException;
/**
* Returns true if the Collection is open false otherwise.
* Calling the close method on
* Collection will result in isOpen
* returning false. It is not safe to use Collection instances
* that have been closed.
*
* @return true if the Collection is open, false otherwise.
* @exception XMLDBException with expected error codes.
* ErrorCodes.VENDOR_ERROR for any vendor
* specific errors that occur.
*/
boolean isOpen() throws XMLDBException;
/**
* Releases all resources consumed by the Collection.
* The close method must
* always be called when use of a Collection is complete. It is
* not safe to use a Collection after the close
* method has been called.
*
* @exception XMLDBException with expected error codes.
* ErrorCodes.VENDOR_ERROR for any vendor
* specific errors that occur.
*/
void close() throws XMLDBException;
}