org.xmldb.api.sdk

Class SimpleCollection

java.lang.Object

org.xmldb.api.sdk.SimpleConfigurable

org.xmldb.api.sdk.SimpleCollection

All Implemented Interfaces:

Collection, Configurable

Direct Known Subclasses:

CollectionImpl

public abstract class SimpleCollection
extends SimpleConfigurable
implements Collection

SimpleCollection provides an easy starting point for implementing the Collection interface. It provides a default Service management functionality but all other functionality must be implemented by the extending class.

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	isOpen
protected java.util.Hashtable	services

Constructor Summary

Constructors

Constructor and Description
SimpleCollection()

Method Summary

Modifier and Type	Method and Description
protected void	checkOpen() Throws an exception if the collection is not open.
void	close() Releases all resources consumed by the Collection.
java.lang.String	createId() Creates a new unique ID within the context of the Collection
Resource	createResource(java.lang.String id, java.lang.String type) Creates a new empty Resource with the provided id.
Collection	getChildCollection(java.lang.String name) Default behaviour for a non-hierarchical implementation
int	getChildCollectionCount() Default behaviour for a non-hierarchical implementation
java.lang.String	getName() Returns the name associated with the Configurable object.
Collection	getParentCollection() Default behaviour for a non-hierarchical implementation
Resource	getResource(java.lang.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(java.lang.String name, java.lang.String version) Get a Service instance based on the name and version.
Service[]	getServices() Returns the list of Services supported by this Collection.
boolean	isOpen() Returns true if the Collection is open false otherwise.
java.lang.String[]	listChildCollections() Default behaviour for a non-hierarchical implementation
java.lang.String[]	listResources() Returns a list of the ids for all resources stored in the collection.
void	registerService(Service service) Registers a new Service with this Collection.
void	removeResource(Resource res) Removes the Resource from the database.
void	storeResource(Resource res) Stores the provided resource into the database.

Methods inherited from class org.xmldb.api.sdk.SimpleConfigurable

getProperty, setProperty

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.xmldb.api.base.Configurable

getProperty, setProperty

Field Detail

services

protected java.util.Hashtable services

isOpen

protected boolean isOpen

Constructor Detail

SimpleCollection

public SimpleCollection()

Method Detail

getName

public java.lang.String getName()
                         throws XMLDBException

Returns the name associated with the Configurable object.

Specified by:

getName in interface Collection

Returns:

the name of the object.

Throws:

XMLDBException - with expected error codes.
ErrorCodes.VENDOR_ERROR for any vendor specific errors that occur.

getServices

public Service[] getServices()
                      throws XMLDBException

Returns the list of Services supported by this Collection.

Specified by:

getServices in interface Collection

Returns:

A list of supported Services

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

getService

public Service getService(java.lang.String name,
                          java.lang.String version)
                   throws XMLDBException

Get a Service instance based on the name and version.

Specified by:

getService in interface Collection

Parameters:

name - The Service instance to retrieve

version - The version of the service to retrieve.

Returns:

The Service instance or null if no service was 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

registerService

public void registerService(Service service)
                     throws XMLDBException

Registers a new Service with this Collection.

Parameters:

service - Description of Parameter

Throws:

XMLDBException

getParentCollection

public Collection getParentCollection()
                               throws XMLDBException

Default behaviour for a non-hierarchical implementation

Specified by:

getParentCollection in interface Collection

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

getChildCollectionCount

public int getChildCollectionCount()
                            throws XMLDBException

Default behaviour for a non-hierarchical implementation

Specified by:

getChildCollectionCount in interface Collection

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

listChildCollections

public java.lang.String[] listChildCollections()
                                        throws XMLDBException

Default behaviour for a non-hierarchical implementation

Specified by:

listChildCollections in interface Collection

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

getChildCollection

public Collection getChildCollection(java.lang.String name)
                              throws XMLDBException

Default behaviour for a non-hierarchical implementation

Specified by:

getChildCollection in interface Collection

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

getResourceCount

public int getResourceCount()
                     throws XMLDBException

Returns the number of resources currently stored in this collection or 0 if the collection is empty.

Specified by:

getResourceCount in interface 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.

listResources

public java.lang.String[] listResources()
                                 throws XMLDBException

Returns a list of the ids for all resources stored in the collection.

Specified by:

listResources in interface 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.

createResource

public Resource createResource(java.lang.String id,
                               java.lang.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.

Specified by:

createResource in interface Collection

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.

removeResource

public void removeResource(Resource res)
                    throws XMLDBException

Removes the Resource from the database.

Specified by:

removeResource in interface Collection

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.

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.

Specified by:

storeResource in interface 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.

getResource

public Resource getResource(java.lang.String id)
                     throws XMLDBException

Retrieves a Resource from the database. If the Resource could not be located a null value will be returned.

Specified by:

getResource in interface Collection

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.

createId

public java.lang.String createId()
                          throws XMLDBException

Creates a new unique ID within the context of the Collection

Specified by:

createId in interface Collection

Returns:

the created id as a string.

Throws:

XMLDBException - with expected error codes.
ErrorCodes.VENDOR_ERROR for any vendor specific errors that occur.

isOpen

public boolean isOpen()
               throws XMLDBException

Description copied from interface: Collection

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.

Specified by:

isOpen in interface Collection

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

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.

Specified by:

close in interface Collection

Throws:

XMLDBException - with expected error codes.
ErrorCodes.VENDOR_ERROR for any vendor specific errors that occur.

checkOpen

protected void checkOpen()
                  throws XMLDBException

Throws an exception if the collection is not open.

Throws:

XMLDBException