org.basex.api.xmldb
Class BXCollection

java.lang.Object
  org.basex.api.xmldb.BXCollection

All Implemented Interfaces:

BXXMLDBText, Collection, Configurable

public final class BXCollection
extends java.lang.Object
implements Collection, BXXMLDBText

Implementation of the Collection Interface for the XMLDB:API.

Author:

Workgroup DBIS, University of Konstanz 2005-08, ISC License, Andreas Weiler

Field Summary

Fields inherited from interface org.basex.api.xmldb.BXXMLDBText

CONFORMANCE_LEVEL, DBURI, ERR_BINARY, ERR_CONT, ERR_DOC, ERR_EMPTY, ERR_ID, ERR_INV, ERR_ITER, ERR_NSURI, ERR_PROP, ERR_RES, ERR_TYPE, ERR_UNKNOWN, ERR_URI, LOCALHOST, XMLDB, XMLDBURI

Constructor Summary

BXCollection(Context c)
Standard constructor.

BXCollection(java.lang.String name)
Constructor to create a collection for the specified document.

Method Summary

void	close() Releases all resources consumed by the Collection.
java.lang.String	createId() Creates a random numeric id and check if it's not already contained in the database.
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) 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.
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.
java.lang.String	getProperty(java.lang.String key) Returns the value of the property identified by name.
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 nm, java.lang.String ver) 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.
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 the Resource from the database.
void	setProperty(java.lang.String key, java.lang.String val) Be aware what you're doing here..
void	storeResource(Resource res) Stores the provided resource into the database.

Methods inherited from class java.lang.Object

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

Constructor Detail

BXCollection

public BXCollection(Context c)

Standard constructor.

Parameters:

c - for Context

BXCollection

public BXCollection(java.lang.String name)
             throws XMLDBException

Constructor to create a collection for the specified document.

Parameters:

name - name of the database

Throws:

XMLDBException - exception

Method Detail

getName

public java.lang.String getName()

Description copied from interface: Collection

Returns the name associated with the Collection instance.

Specified by:

getName in interface Collection

Returns:

the name of the object.

getServices

public Service[] getServices()
                      throws XMLDBException

Description copied from interface: Collection

Provides a list of all services known to the collection. If no services are known an empty list is returned.

Specified by:

getServices in interface 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

getService

public Service getService(java.lang.String nm,
                          java.lang.String ver)
                   throws XMLDBException

Description copied from interface: Collection

Returns a Service instance for the requested service name and version. If no Service exists for those parameters a null value is returned.

Specified by:

getService in interface Collection

Parameters:

nm - Description of Parameter

ver - 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

getParentCollection

public Collection getParentCollection()
                               throws XMLDBException

Description copied from interface: Collection

Returns the parent collection for this collection or null if no parent collection exists.

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

getChildCollection

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

Description copied from interface: Collection

Returns a Collection instance for the requested child collection if it exists.

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

getChildCollectionCount

public int getChildCollectionCount()
                            throws XMLDBException

Description copied from interface: Collection

Returns the number of child collections under this Collection or 0 if no child collections exist.

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

Description copied from interface: Collection

Returns a list of collection names naming all child collections of the current collection. If no child collections exist an empty list is returned.

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

getResourceCount

public int getResourceCount()
                     throws XMLDBException

Description copied from interface: Collection

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.
ErrorCodes.COLLECTION_CLOSED if the close method has been called on the Collection

listResources

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

Description copied from interface: Collection

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.
ErrorCodes.COLLECTION_CLOSED if the close method has been called on the Collection

createResource

public Resource createResource(java.lang.String id,
                               java.lang.String type)
                        throws XMLDBException

Description copied from interface: Collection

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. ErrorCodes.COLLECTION_CLOSED if the close method has been called on the Collection

removeResource

public void removeResource(Resource res)
                    throws XMLDBException

Description copied from interface: Collection

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. ErrorCodes.COLLECTION_CLOSED if the close method has been called on the Collection

storeResource

public void storeResource(Resource res)
                   throws XMLDBException

Description copied from interface: Collection

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. ErrorCodes.COLLECTION_CLOSED if the close method has been called on the Collection

getResource

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

Description copied from interface: Collection

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.
ErrorCodes.COLLECTION_CLOSED if the close method has been called on the Collection

createId

public java.lang.String createId()
                          throws XMLDBException

Creates a random numeric id and check if it's not already contained in the database. Collisions can still occur, if resources are not immediately stored in the database, so it's advisable in general to specify your own IDs.

Specified by:

createId in interface Collection

Returns:

id

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

isOpen

public boolean isOpen()

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.

close

public void close()

Description copied from interface: Collection

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.

Specified by:

close in interface Collection

getProperty

public java.lang.String getProperty(java.lang.String key)
                             throws XMLDBException

Description copied from interface: Configurable

Returns the value of the property identified by name.

Specified by:

getProperty in interface Configurable

Parameters:

key - the name of the property to retrieve.

Returns:

the property value or null if no property exists.

Throws:

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

setProperty

public void setProperty(java.lang.String key,
                        java.lang.String val)
                 throws XMLDBException

Be aware what you're doing here..

Specified by:

setProperty in interface Configurable

Parameters:

key - the name of the property to set.

val - the value to set for the property.

Throws:

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