Package org.xmldb.api.base

Interface Collection

  • All Superinterfaces:
    java.lang.AutoCloseable, Configurable, ServiceProvider
    public interface Collection
extends Configurable, java.lang.AutoCloseable, ServiceProvider
    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 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.

      • 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.util.List<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 s 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
        Since:
        2.0

      • getChildCollection

        Collection getChildCollection​(java.lang.String collectionName)
                       throws XMLDBException
        Returns a Collection instance for the requested child collection if it exists.
        Parameters:
        collectionName - 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.util.List<java.lang.String> listResources()
                                        throws XMLDBException
        Returns a list of the ids for all resources stored in the collection. If there are no documents an empty list is being returned.
        Returns:
        a string list 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
        Since:
        2.0

      • createResource

        <R extends Resource> R createResource​(java.lang.String id,
                                      java.lang.Class<R> type)
                               throws XMLDBException
        Creates a new empty Resource with the provided id. The type of Resource returned is determined by the type class parameter. 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.
        Type Parameters:
        R - the final resource type
        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
        Since:
        2.0

      • 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

      • 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.
        Specified by:
        close in interface java.lang.AutoCloseable
        Throws:
        XMLDBException - with expected error codes. ErrorCodes.VENDOR_ERROR for any vendor specific errors that occur.

      • getCreationTime

        java.time.Instant getCreationTime()
                           throws XMLDBException
        Returns the time of creation of the collection.
        Returns:
        the creation date of the current collection
        Throws:
        XMLDBException - with expected error codes. ErrorCodes.VENDOR_ERROR for any vendor specific errors that occur.
        Since:
        2.0