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