Package org.xmldb.api.base

Interface Collection

  • All Superinterfaces:
    Configurable
    All Known Implementing Classes:
    CollectionImpl, SimpleCollection
    public interface Collection
extends Configurable
    A Collection represents a collection of Resources 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 Resources stored by the Collection and to Service instances that can operate against the Collection and the Resources 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

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      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.

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

      • getService

        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

        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

        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

        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

        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

        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

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

        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

        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

        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

        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

        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

        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

        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.