## org.xmldb.api.base
Interface Collection

All Superinterfaces:
  Configurable

All Known Subinterfaces:
  CollectionImpl

All Known Implementing Classes:
  LocalCollection, RemoteCollection

public interface Collection
extends Configurable

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`.

Method Summary
`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)` 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.
`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)` 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` `storeResource(Resource res)` Stores the provided resource into the database.

Methods inherited from interface org.xmldb.api.base.Configurable
`getProperty, setProperty`

Method Detail

### getName

    public 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

    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.

  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 name,
                              java.lang.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.

  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`

### getParentCollection

    public 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 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.

  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

  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 the `close` method has been called on the `Collection`

### getChildCollection

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

  Returns a `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`

### getResourceCount

    public 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 the `close` method has been called on the `Collection`

### listResources

    public 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 the `close` method has been called on the `Collection`

### 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.

  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

  Removes the `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`

### 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.

  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

  Retrieves a `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`

### createId

    public java.lang.String createId()
                              throws XMLDBException

  Creates a new unique ID within the context of the `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`

### 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.

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

Copyright (C) Wolfgang Meier. All rights reserved.