XMLStorage
Date: 2017-06-10

org.gcube.informationsystem.collector.impl.xmlstorage.exist

## Class XMLStorage

- java.lang.Object
- - org.gcube.informationsystem.collector.impl.xmlstorage.exist.XMLStorage

- Direct Known Subclasses:
    DataManager, QueryManager

      public class XMLStorage
      extends java.lang.Object

  A thread safe manager to interact with the XML Storage repository. RESOURCE the type of the resource to store
  Author:
    Manuele Simi (ISTI-CNR)

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `XMLStorage.XMLStorageNotAvailableException` XMLStorage not initialized exception

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `XMLStorage()` Creates a new manager

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `collectionExists(java.lang.String collectionName)` Checks whether a collection exists or not
    `Collection` | `createCollection(java.lang.String name)` Creates a collection in the XML storage.
    `void` | `deleteCollection(java.lang.String collectionName)` Deletes the collection from the storage
    `void` | `deleteResource(GCUBEXMLResource resource)` Deletes a resource
    `GCUBEXMLResource` | `executeXPathQuery(java.lang.String xpathquery)`
    `org.gcube.informationsystem.collector.impl.xmlstorage.exist.XMLStorage.STATUS` | `getStatus()`
    `void` | `initialize(boolean... lock)` Initializes the local XML Storage repository
    `void` | `initialize(long maxOperationsPerConnection, boolean... lock)` Initializes the local XML Storage repository
    `boolean` | `isLocked()`
    `java.lang.String[]` | `listAllCollectionResourceIDs(java.lang.String collectionName)` Lists all the identifiers of the resources belonging the collection
    `Collection` | `loadAllCollections()` Loads the root collection.
    `void` | `printResourcesIDs()` Prints all the IDs of the Resources stored in the DB instance
    `boolean` | `resourceExists(GCUBEXMLResource resource)` Checks if the resource does exist in the storage
    `void` | `retrieveResourceContent(GCUBEXMLResource resource)` Retrieves a resource's content from the storage
    `void` | `setStatus(org.gcube.informationsystem.collector.impl.xmlstorage.exist.XMLStorage.STATUS status)`
    `boolean` | `shutdown(boolean lock)` Shutdowns the XML Storage repository
    `void` | `storeResource(GCUBEXMLResource resource)` Stores a XMLDBDocument in the current collection.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### XMLStorage

          public XMLStorage()

      Creates a new manager

  - ### Method Detail

    - #### initialize

          public void initialize(boolean... lock)
                          throws XMLStorage.XMLStorageNotAvailableException

      Initializes the local XML Storage repository
      Parameters:
        `lock` - if the storage has to be locked or not during the initalization
      Throws:
        `java.lang.Exception` - if the connection to eXist or its initialization fail
        `XMLStorage.XMLStorageNotAvailableException`

    - #### initialize

          public void initialize(long maxOperationsPerConnection,
                        boolean... lock)
                          throws XMLStorage.XMLStorageNotAvailableException

      Initializes the local XML Storage repository
      Parameters:
        `maxOperationsPerConnection` - max number of operation per active connection
        `lock` - if the storage has to be locked or not during the initalization
      Throws:
        `java.lang.Exception` - if the connection to eXist or its initialization fail
        `XMLStorage.XMLStorageNotAvailableException`

    - #### createCollection

          public Collection createCollection(java.lang.String name)
                                      throws XMLDBException,
                                             XMLStorage.XMLStorageNotAvailableException

      Creates a collection in the XML storage. If the input includes a full path, collections are created recursively
      Parameters:
        `name` - the collection to create
      Returns:
        the created collection
      Throws:
        `XMLDBException`
        `XMLStorage.XMLStorageNotAvailableException`

    - #### shutdown

          public boolean shutdown(boolean lock)

      Shutdowns the XML Storage repository
      Returns:
        true if the operation succeed

    - #### loadAllCollections

          public Collection loadAllCollections()

      Loads the root collection. It must be used when quering all the information maintained by the DB instance at the same time
      Returns:
        the Collection

    - #### storeResource

          public void storeResource(GCUBEXMLResource resource)
                             throws XMLStorage.XMLStorageNotAvailableException,
                                    GCUBEXMLResource.MalformedXMLResourceException

      Stores a XMLDBDocument in the current collection. If the resource already exists in the storage, it is updated.
      Parameters:
        `resource` - the resource to store
      Throws:
        `GCUBEXMLResource.MalformedXMLResourceException`
        `java.lang.Exception` - if the storing fails
        `XMLStorage.XMLStorageNotAvailableException`

    - #### isLocked

          public boolean isLocked()

      Returns:
        true if the connection to eXist is locked

    - #### retrieveResourceContent

          public void retrieveResourceContent(GCUBEXMLResource resource)
                                       throws java.lang.Exception

      Retrieves a resource's content from the storage
      Parameters:
        `resource` -
      Throws:
        `java.lang.Exception`

    - #### resourceExists

          public boolean resourceExists(GCUBEXMLResource resource)
                                 throws GCUBEXMLResource.MalformedXMLResourceException,
                                        XMLStorage.XMLStorageNotAvailableException

      Checks if the resource does exist in the storage
      Parameters:
        `resource` - the resource to check
      Returns:
        true if the resource is stored, false otherwise
      Throws:
        `GCUBEXMLResource.MalformedXMLResourceException` - if the input resource is not valid
        `XMLStorage.XMLStorageNotAvailableException`

    - #### executeXPathQuery

          public GCUBEXMLResource executeXPathQuery(java.lang.String xpathquery)

      Parameters:
        `xpathquery` -
      Returns:

    - #### deleteResource

          public void deleteResource(GCUBEXMLResource resource)
                              throws java.lang.Exception

      Deletes a resource
      Throws:
        `java.lang.Exception`

    - #### printResourcesIDs

          public void printResourcesIDs()

      Prints all the IDs of the Resources stored in the DB instance

    - #### collectionExists

          public boolean collectionExists(java.lang.String collectionName)

      Checks whether a collection exists or not
      Parameters:
        `collectionName` - the name of the collection to check
      Returns:
        true or false, depending if the collection exists or not

    - #### deleteCollection

          public void deleteCollection(java.lang.String collectionName)
                                throws XMLStorage.XMLStorageNotAvailableException

      Deletes the collection from the storage
      Parameters:
        `collectionName` - the name of the collection to delete
      Throws:
        `XMLStorage.XMLStorageNotAvailableException`

    - #### listAllCollectionResourceIDs

          public java.lang.String[] listAllCollectionResourceIDs(java.lang.String collectionName)
                                                          throws XMLStorage.XMLStorageNotAvailableException

      Lists all the identifiers of the resources belonging the collection
      Parameters:
        `collectionName` - the collection name
      Returns:
        the list of identifiers
      Throws:
        `XMLStorage.XMLStorageNotAvailableException`

    - #### getStatus

          public org.gcube.informationsystem.collector.impl.xmlstorage.exist.XMLStorage.STATUS getStatus()

      Returns:
        the status

    - #### setStatus

          public void setStatus(org.gcube.informationsystem.collector.impl.xmlstorage.exist.XMLStorage.STATUS status)

      Parameters:
        `status` - the status to set