Interface PersistentService

  • All Known Implementing Classes:
    StorageFactoryService

    public interface PersistentService
    A PersistentService modularises the access to persistent services, abstracting out details such as finding the list of services to be started at boot time, finding the service.properties file and creating and deleting the persistent storage for a service.

    These modules must only be used by the monitor.

    Possible examples of implementations are:

    • Store services in a directory in the file system.
    • Store services in a zip file
    • Service data is provided by a web server
    • Service data is stored on the class path.

    This class also serves as the registry the defined name for all the implementations of PersistentService. These need to be kept track of as they can be used in JDBC URLS.

    An implementation of PersistentService can implement ModuleSupportable but must not implement ModuleControl. This is because the monitor will not execute ModuleControl methods for a PersistentService.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String CLASSPATH
      Service stored on the class path (can be in a zip/jar on the class path).
      static java.lang.String DB_README_FILE_NAME
      The readme file cautioning users against touching the files in the database directory
      static java.lang.String DIRECTORY
      Service stored in a directory.
      static java.lang.String HTTP
      Service stored in a web server .
      static java.lang.String HTTPS  
      static java.lang.String INMEMORY
      Service stored in memory only (not persistent), virtual file memory.
      static java.lang.String JAR
      Service stored in a jar/zip archive.
      static java.lang.String PROPERTIES_NAME
      The typical name for the service's properties file.
      static java.lang.String ROOT
      The root of any stored data.
      static java.lang.String TYPE
      The type of PersistentService used to boot the service.
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void createDataWarningFile​(StorageFactory sf)
      Put a readme file in database directory which will caution users against touching any files in the directory.
      java.lang.String createServiceRoot​(java.lang.String name, boolean deleteExisting)
      Returns the canonical name of the service.
      java.util.Enumeration getBootTimeServices()
      Return an Enumeration of service names descriptors (Strings) that should be be started at boot time by the monitor.
      java.lang.String getCanonicalServiceName​(java.lang.String name)
      Convert a service name into its canonical form.
      java.util.Properties getServiceProperties​(java.lang.String serviceName, java.util.Properties defaultProperties)
      For a service return its service properties, typically from the service.properties file.
      StorageFactory getStorageFactoryInstance​(boolean useHome, java.lang.String databaseName, java.lang.String tempDirName, java.lang.String uniqueName)
      Get an initialized StorageFactoryInstance
      java.lang.String getType()
      Return the type of this service.
      java.lang.String getUserServiceName​(java.lang.String serviceName)
      Return the user form of a service name.
      boolean hasStorageFactory()  
      boolean isSameService​(java.lang.String serviceName1, java.lang.String serviceName2)  
      boolean removeServiceRoot​(java.lang.String serviceName)
      Remove a service's root and its contents.
      void saveServiceProperties​(java.lang.String serviceName, java.util.Properties properties)
      Save to a backup file.
      void saveServiceProperties​(java.lang.String serviceName, StorageFactory storageFactory, java.util.Properties properties, boolean replace)  
    • Field Detail

      • DIRECTORY

        static final java.lang.String DIRECTORY
        Service stored in a directory.
        See Also:
        Constant Field Values
      • CLASSPATH

        static final java.lang.String CLASSPATH
        Service stored on the class path (can be in a zip/jar on the class path).
        See Also:
        Constant Field Values
      • JAR

        static final java.lang.String JAR
        Service stored in a jar/zip archive.
        See Also:
        Constant Field Values
      • HTTP

        static final java.lang.String HTTP
        Service stored in a web server .
        See Also:
        Constant Field Values
      • INMEMORY

        static final java.lang.String INMEMORY
        Service stored in memory only (not persistent), virtual file memory.
        See Also:
        Constant Field Values
      • DB_README_FILE_NAME

        static final java.lang.String DB_README_FILE_NAME
        The readme file cautioning users against touching the files in the database directory
        See Also:
        Constant Field Values
      • PROPERTIES_NAME

        static final java.lang.String PROPERTIES_NAME
        The typical name for the service's properties file.
        See Also:
        Constant Field Values
      • TYPE

        static final java.lang.String TYPE
        The type of PersistentService used to boot the service.
        See Also:
        Constant Field Values
    • Method Detail

      • getType

        java.lang.String getType()
        Return the type of this service.
      • getBootTimeServices

        java.util.Enumeration getBootTimeServices()
        Return an Enumeration of service names descriptors (Strings) that should be be started at boot time by the monitor. The monitor will boot the service if getServiceProperties() returns a Properties object and the properties does not indicate the service should not be auto-booted.

        This method may return null if there are no services that need to be booted automatically at boot time.

        The service name returned by the Enumeration must be in its canonical form.

      • createDataWarningFile

        void createDataWarningFile​(StorageFactory sf)
                            throws StandardException
        Put a readme file in database directory which will caution users against touching any files in the directory. This file will be created at database creation time.
        Parameters:
        sf - StorageFactory will be used to create the file
        Throws:
        StandardException - File can't be created
      • getServiceProperties

        java.util.Properties getServiceProperties​(java.lang.String serviceName,
                                                  java.util.Properties defaultProperties)
                                           throws StandardException
        For a service return its service properties, typically from the service.properties file.
        Returns:
        A Properties object or null if serviceName does not represent a valid service.
        Throws:
        StandardException - Service appears valid but the properties cannot be created.
      • saveServiceProperties

        void saveServiceProperties​(java.lang.String serviceName,
                                   StorageFactory storageFactory,
                                   java.util.Properties properties,
                                   boolean replace)
                            throws StandardException
        Throws:
        StandardException - Properties cannot be saved.
      • saveServiceProperties

        void saveServiceProperties​(java.lang.String serviceName,
                                   java.util.Properties properties)
                            throws StandardException
        Save to a backup file.
        Throws:
        StandardException - Properties cannot be saved.
      • createServiceRoot

        java.lang.String createServiceRoot​(java.lang.String name,
                                           boolean deleteExisting)
                                    throws StandardException
        Returns the canonical name of the service.
        Throws:
        StandardException - Service root cannot be created.
      • removeServiceRoot

        boolean removeServiceRoot​(java.lang.String serviceName)
        Remove a service's root and its contents.
      • getCanonicalServiceName

        java.lang.String getCanonicalServiceName​(java.lang.String name)
                                          throws StandardException
        Convert a service name into its canonical form. Returns null if the name cannot be converted into a canonical form.
        Throws:
        StandardException - if an error happens when converting the name (name probably invalid)
      • getUserServiceName

        java.lang.String getUserServiceName​(java.lang.String serviceName)
        Return the user form of a service name. This name is only valid within this system. The separator character used must be '/'
      • isSameService

        boolean isSameService​(java.lang.String serviceName1,
                              java.lang.String serviceName2)
      • hasStorageFactory

        boolean hasStorageFactory()
        Returns:
        true if the PersistentService has a StorageFactory, false if not.
      • getStorageFactoryInstance

        StorageFactory getStorageFactoryInstance​(boolean useHome,
                                                 java.lang.String databaseName,
                                                 java.lang.String tempDirName,
                                                 java.lang.String uniqueName)
                                          throws StandardException,
                                                 java.io.IOException
        Get an initialized StorageFactoryInstance
        Parameters:
        useHome - If true and the database name is not absolute then the database directory will be relative to the home directory, if one is defined in the properties file.
        databaseName - The name of the database (directory). The name does not include the subSubProtocol. If null then the storage factory will only be used to deal with the directory containing the databases.
        tempDirName - The name of the temporary file directory set in properties. If null then a default directory should be used. Each database should get a separate temporary file directory within this one to avoid collisions.
        uniqueName - A unique name that can be used to create the temporary file directory for this database. If null then temporary files will not be created in this StorageFactory instance.
        Returns:
        An initialized StorageFactory.
        Throws:
        StandardException
        java.io.IOException