org.xmldb.api.base
public interface Collection extends Configurable
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.
| Method Summary | |
|---|---|
| void | close()
Releases all resources consumed by the Collection.
|
| String | createId()
Creates a new unique ID within the context of the Collection
|
| Resource | createResource(String id, String type)
Creates a new empty Resource with the provided id.
|
| Collection | getChildCollection(String name)
Returns a Collection instance for the requested child collection
if it exists.
|
| int | getChildCollectionCount()
Returns the number of child collections under this
Collection or 0 if no child collections exist.
|
| String | getName()
Returns the name associated with the Collection instance.
|
| Collection | getParentCollection()
Returns the parent collection for this collection or null if no parent
collection exists.
|
| Resource | getResource(String id)
Retrieves a Resource from the database. |
| int | getResourceCount()
Returns the number of resources currently stored in this collection or 0
if the collection is empty.
|
| Service | getService(String name, String version)
Returns a Service instance for the requested service name and version. |
| Service[] | getServices()
Provides a list of all services known to the collection. |
| boolean | isOpen()
Returns true if the Collection is open false otherwise.
|
| String[] | listChildCollections()
Returns a list of collection names naming all child collections
of the current collection. |
| String[] | listResources()
Returns a list of the ids for all resources stored in the collection.
|
| void | removeResource(Resource res)
Removes the Resource from the database.
|
| void | storeResource(Resource res)
Stores the provided resource into the database. |
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.
Throws: XMLDBException with expected error codes.
ErrorCodes.VENDOR_ERROR for any vendor
specific errors that occur.
Collection
Returns: the created id as a string.
Throws: 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 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.
Parameters: id the unique id to associate with the created Resource. type the Resource type to create.
Returns: an empty Resource instance.
Throws: 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
Collection instance for the requested child collection
if it exists.
Parameters: name the name of the child collection to retrieve.
Returns: the requested child collection or null if it couldn't be found.
Throws: 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 or 0 if no child collections exist.
Returns: the number of child collections.
Throws: 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
Returns: the name of the object.
Throws: XMLDBException with expected error codes.
ErrorCodes.VENDOR_ERROR for any vendor
specific errors that occur.
Returns: the parent Collection instance.
Throws: 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 from the database. If the
Resource could not be
located a null value will be returned.
Parameters: id the unique id for the requested resource.
Returns: The retrieved Resource instance.
Throws: 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
Returns: the number of resource in the collection.
Throws: 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 instance for the requested service name and version. If
no Service exists for those parameters a null value is returned.
Parameters: name Description of Parameter version Description of Parameter
Returns: the Service instance or null if no Service could be found.
Throws: 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
Returns: An array of registered Service implementations.
Throws: 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 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.
Returns: true if the Collection is open, false otherwise.
Throws: XMLDBException with expected error codes.
ErrorCodes.VENDOR_ERROR for any vendor
specific errors that occur.
Returns: an array containing collection names for all child collections.
Throws: 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
Returns: a string array containing the names for all
Resources in the collection.
Throws: 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 from the database.
Parameters: res the resource to remove.
Throws: 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
Parameters: res the resource to store in the database.
Throws: 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