Package org.xmldb.api.base
Interface Collection
-
- All Superinterfaces:
Configurable
- All Known Implementing Classes:
CollectionImpl
,SimpleCollection
public interface Collection extends Configurable
ACollection
represents a collection ofResource
s stored within an XML database. An XML database MAY expose collections as a hierarchical set of parent and child collections. ACollection
provides access to theResource
s stored by theCollection
and toService
instances that can operate against theCollection
and theResource
s stored within it. TheService
mechanism provides the ability to extend the functionality of aCollection
in ways that allows optional functionality to be enabled for theCollection
.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
close()
Releases all resources consumed by theCollection
.java.lang.String
createId()
Creates a new unique ID within the context of theCollection
Resource
createResource(java.lang.String id, java.lang.String type)
Creates a new emptyResource
with the provided id.Collection
getChildCollection(java.lang.String name)
Returns aCollection
instance for the requested child collection if it exists.int
getChildCollectionCount()
Returns the number of child collections under thisCollection
or 0 if no child collections exist.java.lang.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(java.lang.String id)
Retrieves aResource
from the database.int
getResourceCount()
Returns the number of resources currently stored in this collection or 0 if the collection is empty.Service
getService(java.lang.String name, java.lang.String version)
Returns aService
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 theCollection
is open false otherwise.java.lang.String[]
listChildCollections()
Returns a list of collection names naming all child collections of the current collection.java.lang.String[]
listResources()
Returns a list of the ids for all resources stored in the collection.void
removeResource(Resource res)
Removes theResource
from the database.void
storeResource(Resource res)
Stores the provided resource into the database.-
Methods inherited from interface org.xmldb.api.base.Configurable
getProperty, setProperty
-
-
-
-
Method Detail
-
getName
java.lang.String getName() throws XMLDBException
Returns the name associated with the Collection instance.- Returns:
- the name of the object.
- Throws:
XMLDBException
- with expected error codes.
ErrorCodes.VENDOR_ERROR
for any vendor specific errors that occur.
-
getServices
Service[] getServices() throws XMLDBException
Provides a list of all services known to the collection. If no services are known an empty list is returned.- 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 theclose
method has been called on theCollection
-
getService
Service getService(java.lang.String name, java.lang.String version) throws XMLDBException
Returns aService
instance for the requested service name and version. If noService
exists for those parameters a null value is returned.- Parameters:
name
- Description of Parameterversion
- 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 theclose
method has been called on theCollection
-
getParentCollection
Collection getParentCollection() throws XMLDBException
Returns the parent collection for this collection or null if no parent collection exists.- 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 theclose
method has been called on theCollection
-
getChildCollectionCount
int getChildCollectionCount() throws XMLDBException
Returns the number of child collections under thisCollection
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 theclose
method has been called on theCollection
-
listChildCollections
java.lang.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.- 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 theclose
method has been called on theCollection
-
getChildCollection
Collection getChildCollection(java.lang.String name) throws XMLDBException
Returns aCollection
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 theclose
method has been called on theCollection
-
getResourceCount
int getResourceCount() throws XMLDBException
Returns the number of resources currently stored in this collection or 0 if the collection is empty.- 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 theclose
method has been called on theCollection
-
listResources
java.lang.String[] listResources() throws XMLDBException
Returns a list of the ids for all resources stored in the collection.- Returns:
- a string array containing the names for all
Resource
s in the collection. - Throws:
XMLDBException
- with expected error codes.
ErrorCodes.VENDOR_ERROR
for any vendor specific errors that occur.
ErrorCodes.COLLECTION_CLOSED
if theclose
method has been called on theCollection
-
createResource
Resource createResource(java.lang.String id, java.lang.String type) throws XMLDBException
Creates a new emptyResource
with the provided id. The type ofResource
returned is determined by thetype
parameter. The XML:DB API currently defines "XMLResource" and "BinaryResource" as valid resource types. Theid
provided must be unique within the scope of the collection. Ifid
is null or its value is empty then an id is generated by callingcreateId()
. TheResource
created is not stored to the database untilstoreResource()
is called.- Parameters:
id
- the unique id to associate with the createdResource
.type
- theResource
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 thetype
parameter is not a knownResource
type.ErrorCodes.COLLECTION_CLOSED
if theclose
method has been called on theCollection
-
removeResource
void removeResource(Resource res) throws XMLDBException
Removes theResource
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 theResource
is not valid.
ErrorCodes.NO_SUCH_RESOURCE
if theResource
is not known to thisCollection
.ErrorCodes.COLLECTION_CLOSED
if theclose
method has been called on theCollection
-
storeResource
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.- 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 theResource
is not valid.ErrorCodes.COLLECTION_CLOSED
if theclose
method has been called on theCollection
-
getResource
Resource getResource(java.lang.String id) throws XMLDBException
Retrieves aResource
from the database. If theResource
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 theclose
method has been called on theCollection
-
createId
java.lang.String createId() throws XMLDBException
Creates a new unique ID within the context of theCollection
- 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 theclose
method has been called on theCollection
-
isOpen
boolean isOpen() throws XMLDBException
Returns true if theCollection
is open false otherwise. Calling theclose
method onCollection
will result inisOpen
returning false. It is not safe to useCollection
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.
-
close
void close() throws XMLDBException
Releases all resources consumed by theCollection
. Theclose
method must always be called when use of aCollection
is complete. It is not safe to use aCollection
after theclose
method has been called.- Throws:
XMLDBException
- with expected error codes.
ErrorCodes.VENDOR_ERROR
for any vendor specific errors that occur.
-
-