Apache Derby Database Engine and Embedded JDBC Driver 10.17.1.0 · org.apache.derby.iapi.services.monitor.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

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

Method Summary

Modifier and Type	Method and Description
public void	createDataWarningFile(StorageFactory StorageFactory will be used to create the file sf) Put a readme file in database directory which will caution users against touching any files in the directory.
public String	createServiceRoot(String name, boolean deleteExisting) Returns the canonical name of the service.
public Enumeration<E>	getBootTimeServices() Return an Enumeration of service names descriptors (Strings) that should be be started at boot time by the monitor.
public String	getCanonicalServiceName(String name) Convert a service name into its canonical form.
public Properties	Returns: A Properties object or null if serviceName does not represent a valid service. getServiceProperties(String serviceName, Properties defaultProperties) For a service return its service properties, typically from the service.properties file.
public StorageFactory	Returns: An initialized StorageFactory. getStorageFactoryInstance(boolean 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. useHome, String 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. databaseName, String 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. tempDirName, String 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. uniqueName) Get an initialized StorageFactoryInstance
public String	getType() Return the type of this service.
public String	getUserServiceName(String serviceName) Return the user form of a service name.
public boolean	Returns: true if the PersistentService has a StorageFactory, false if not. hasStorageFactory()
public boolean	isSameService(String serviceName1, String serviceName2)
public boolean	removeServiceRoot(String serviceName) Remove a service's root and its contents.
public void	saveServiceProperties(String serviceName, StorageFactory storageFactory, Properties properties, boolean replace)
public void	saveServiceProperties(String serviceName, Properties properties) Save to a backup file.

Field Detail

CLASSPATH	back to summary
public static final String CLASSPATH Service stored on the class path (can be in a zip/jar on the class path).

DB_README_FILE_NAME	back to summary
public static final String DB_README_FILE_NAME The readme file cautioning users against touching the files in the database directory

DIRECTORY	back to summary
public static final String DIRECTORY Service stored in a directory.

HTTP	back to summary
public static final String HTTP Service stored in a web server .

HTTPS	back to summary
public static final String HTTPS

INMEMORY	back to summary
public static final String INMEMORY Service stored in memory only (not persistent), virtual file memory.

JAR	back to summary
public static final String JAR Service stored in a jar/zip archive.

PROPERTIES_NAME	back to summary
public static final String PROPERTIES_NAME The typical name for the service's properties file.

ROOT	back to summary
public static final String ROOT The root of any stored data.

TYPE	back to summary
public static final String TYPE The type of PersistentService used to boot the service.

Method Detail

createDataWarningFile	back to summary
public 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 StorageFactory will be used to create the file Exceptions StandardException: File can't be created

createDataWarningFile

back to summary

public 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: StorageFactory will be used to create the file

Exceptions

StandardException:: File can't be created

createServiceRoot	back to summary
public String createServiceRoot(String name, boolean deleteExisting) throws StandardException Returns the canonical name of the service. Exceptions StandardException: Service root cannot be created.

createServiceRoot

back to summary

public String createServiceRoot(String name, boolean deleteExisting) throws StandardException

Returns the canonical name of the service.

Exceptions

StandardException:: Service root cannot be created.

getBootTimeServices	back to summary
public Enumeration<E> 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.

getBootTimeServices

back to summary

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

getCanonicalServiceName	back to summary
public String getCanonicalServiceName(String name) throws StandardException Convert a service name into its canonical form. Returns null if the name cannot be converted into a canonical form. Exceptions StandardException: if an error happens when converting the name (name probably invalid)

getCanonicalServiceName

back to summary

public String getCanonicalServiceName(String name) throws StandardException

Convert a service name into its canonical form. Returns null if the name cannot be converted into a canonical form.

Exceptions

StandardException:: if an error happens when converting the name (name probably invalid)

getServiceProperties	back to summary
public Properties getServiceProperties(String serviceName, Properties defaultProperties) throws StandardException For a service return its service properties, typically from the service.properties file. Returns:Properties A Properties object or null if serviceName does not represent a valid service. Exceptions StandardException: Service appears valid but the properties cannot be created.

getServiceProperties

back to summary

public Properties getServiceProperties(String serviceName, Properties defaultProperties) throws StandardException

For a service return its service properties, typically from the service.properties file.

Returns:Properties

A Properties object or null if serviceName does not represent a valid service.

Exceptions

StandardException:: Service appears valid but the properties cannot be created.

getStorageFactoryInstance	back to summary
public StorageFactory getStorageFactoryInstance(boolean useHome, String databaseName, String tempDirName, String uniqueName) throws StandardException, IOException Get an initialized StorageFactoryInstance Parameters useHome:boolean 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:String 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:String 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:String 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:StorageFactory An initialized StorageFactory.

getStorageFactoryInstance

back to summary

public StorageFactory getStorageFactoryInstance(boolean useHome, String databaseName, String tempDirName, String uniqueName) throws StandardException, IOException

Get an initialized StorageFactoryInstance

Parameters

useHome:boolean: 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:String: 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:String: 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:String: 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:StorageFactory

An initialized StorageFactory.

getType	back to summary
public String getType() Return the type of this service.

getUserServiceName	back to summary
public String getUserServiceName(String serviceName) Return the user form of a service name. This name is only valid within this system. The separator character used must be '/'

hasStorageFactory	back to summary
public boolean hasStorageFactory() Returns:boolean true if the PersistentService has a StorageFactory, false if not.

isSameService	back to summary
public boolean isSameService(String serviceName1, String serviceName2)

removeServiceRoot	back to summary
public boolean removeServiceRoot(String serviceName) Remove a service's root and its contents.

saveServiceProperties	back to summary
public void saveServiceProperties(String serviceName, StorageFactory storageFactory, Properties properties, boolean replace) throws StandardException Exceptions StandardException: Properties cannot be saved.

saveServiceProperties	back to summary
public void saveServiceProperties(String serviceName, Properties properties) throws StandardException Save to a backup file. Exceptions StandardException: Properties cannot be saved.

saveServiceProperties

back to summary

public void saveServiceProperties(String serviceName, Properties properties) throws StandardException

Save to a backup file.

Exceptions

StandardException:: Properties cannot be saved.

public Interface PersistentService

Field Summary

Method Summary

Field Detail

Method Detail