Class Monitor
- java.lang.Object
-
- org.apache.derby.iapi.services.monitor.Monitor
-
public class Monitor extends java.lang.Object
Services
A service is a collection of modules that combine to provide the full functionality defined by the service. A service is defined by three pieces of information:- A fully qualified java class name that identifies the functionality or API that the service must provide. Typically this class represents a java interface. This class name is termed the factory interface.
- The identifier of the service. Services are identified by a String, this may be hard-coded, come from a UUID or any other source.
- An optional java.util.Properties set.
The running functionality of the service is provided by a module that implements the factory interface. The identifier of the this module is not (need not be) the same as the identifier of the service. The identifier of the service is held by the monitor in its service tables.
Each module in a service is keyed by at least one factory interface, identifier} pair. This pair is guaranteed to be unique within the service.
The lifetime of a module in a service is no longer than the lifetime of the service. Thus shutting down a service shuts down all the modules within a service. Optionally - an individual module within a service may be shutdown, this will in turn shutdown any modules it started if those module are not in use by other modules within the service. This would be handled by the monitor, not the module itself.
A service may be persistent, it goes through a boot in create mode, and subsequently boot in non-create mode, or a non-peristent service, it always boots in non-create mode. Persistent services can store their re-start parameters in their properties set, the monitor provides the persistent storage of the properties set. Non-persistent services do not have a properties set.Booting Services
Services can be booted a number of ways- A non-persistent service can be booted by having a property in the application properties
or the system (JVM) set.
derby.service.service name=class name e.g. # Added to the properties automatically by the class org.apache.derby.jdbc.EmbeddedDriver derby.service.jdbc=java.sql.Driver
- A persistent service can be booted by having a property in the application properties
or the system (JVM) set.
derby.service.service name=persistent storage type e.g. derby.service.mydatabase=serviceDirectory
serviceDirectory is a type understood by the monitor which means that there is a directory named mydatabase within the system directory and within it is a properties file service.properties. This properties set is the set for the service and must contain a propertyderby.protocol=class name
This is then the factory interface for the service. Other storage types could be added in the future. - The monitor at start time looks for all persistent services that it can find and starts them. E.g. all directories in the system directory that have a file service.properties are started as services.
- Services are started on demand, e.g. a findService attempts to boot a service if it cannot be found.
System Service
A special service exists, the System Service. This service has no factory interface, no identifier and no Properties set. It allows modules to be started that are required by another service (or the monitor itself) but are not fundamentally part of the service. Modules within this service are unidentified. Typically these modules are system wide types of functionality like streams, uuid creation etc.
The lifetime of a system module is the lifetime of the monitor. Optionally - this could be changed to reference count on individual modules, requires some minor api changes.Modules
A module is found or booted using four pieces of information:- The service the module lives in or will live in.
- A fully qualified java class name that identifies the functionality or API that the module must provide. Typically this class represents a java interface. This class name is termed the factory interface.
- The identifier of the module. Modules are identified by a String, this may be null, be hard-coded, come from a UUID or any other source. If the identifier is null then the module is described as unidentified.
- Boot time only - A java.util.Properties set. This Properties set is service wide and typically contains parameters used to determine module implementation or runtime behaviour.
The service is identified by explicitly identifiying the System Service or by providing a reference to a module that already exists with the required service.
The factory interface is provided by a String constant of the form class.MODULE from the required interface.
The module identifier is provided in a fashion determined by the code, in most cases a unidentified module will suffice.
The Properties set is also determined in a fashion determined by the code at create or add service time.Module Implementations
When creating an instance of a module, an implementation is found through lists of potential implementations.
A list of potential implementations is obtained from a Properties set. Any property within this set that is of the formderby.module.tag=java class name
is seen by the monitor as a possible implementation. tag has no meaning within the monitor, it is only there to provide uniqueness within the properties file. Typically the tag is to provide some description for human readers of the properties file, e.g. derby.module.lockManager for an implementation of a lock manager.
The monitor looks through four properties sets for lists of potential implementations in this order.- The properties set of the service (i.e. that passed into Monitor.createPersistentService() or Monitor.startService()).
- The System (JVM) properties set (i.e. java.lang.System.getProperties()).
- The application properties set (i.e. obtained from the derby.properties file).
- The default implementation properties set (i.e. obtained from the /org/apache/derby/modules.properties resource).
Every request to create an instance of a module searches the four implementation lists in the order above. Which list the current running code or the passed in service module came from is not relevant.
Within each list of potential implementations the search is conducted as follows:- Attempt to load the class, if the class cannot be loaded skip to the next potential implementation.
- See if the factory interface is assignable from the class (isAssignableFrom() method of java.lang.Class), if not skip to the next potential implementation.
- See if an instance of the class can be created without any exceptions (newInstance() method of java.lang.Class), if not skip to the next potential implementation.
- [boot time only] See if the canSupport() method of ModuleControl returns true when called with the Properties set of the service, if not skip to the next potential implementation.
Module Searching
When searching for a module the search space is always restricted to a single service. This service is usually the system service or the service of the module making the search request. It would be very rare (wrong?) to search for a module in a service that was not the current service and not the system service.
Within the list of modules in the service the search is conducted as follows:- See if the instance of the module an instance of the factory interface (isInstance() method of java.lang.Class), if not skip to the next module.
- See if the identifier of the module matches the required identifier, if not skip to the next module.
- See if the canSupport() method of ModuleControl returns true when called with the Properties set of the service, if not skip to the next module.
Also note that a module may be found by a different factory interface to the one it was created under. Thus a class may implement multiple factory interfaces, its boot method has no knowledge of which factory interface it was requested by.Service Properties
Within the service's Properties a module may search for its parameters. It identifies its parameters using a unqiue parameter name and its identifier.
Unique parameter names are made unique through the 'dot' convention of Properties files. A module protocol picks some unique key portion to start, e.g. RawStore for the RawStoreFactory and then extends that for specific parameters, e.g. RawStore.PageSize. Thus parameters that are typically understood by all implementations of that protocol would start with that key portion. Parameters for specific implementations add another key portion onto the protocol key portion, e.g. RawStore.FileSystem for an file system implementation of the raw store, with a specific parameter being RawStore.FileSystem.SectorSize.
These are general guidelines, UUID's could be used as the properties keys but would make the parameters hard to read.
When a module is unidentified it should look for a parameter using just the property key for that parameter, e.g. getProperty("RawStore.PageSize").
When a module has an identifier is should look for a property using the key with a dot and the identifier appended, e.g. getProperty("RawStore.PageSize" + "." + identifier).
In addition to searching for parameters in the service properties set, the system and application set may be searched using the getProperty() method of ModuleFactory.
Should any order be defined for this, should it be automatic?
-
-
Field Summary
Fields Modifier and Type Field Description private static boolean
active
static java.lang.String
DEBUG_FALSE
static java.lang.String
DEBUG_TRUE
private static ModuleFactory
monitor
static java.lang.String
NEW_INSTANCE_FROM_ID_TRACE_DEBUG_FLAG
Global debug flag to turn on tracing of reads calls newInstanceFromIdentifier()static java.lang.String
SERVICE_TYPE_DIRECTORY
static java.lang.Object
syncMe
-
Constructor Summary
Constructors Constructor Description Monitor()
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static java.lang.Object
bootServiceModule(boolean create, java.lang.Object serviceModule, java.lang.String factoryInterface, java.lang.String identifier, java.util.Properties properties)
Boot or find a identified module within a service.static java.lang.Object
bootServiceModule(boolean create, java.lang.Object serviceModule, java.lang.String factoryInterface, java.util.Properties properties)
Boot or find a unidentified module within a service.static InstanceGetter
classFromIdentifier(int identifier)
Obtain the class object for a class that supports the given identifier.static void
clearMonitor()
static java.lang.Object
createPersistentService(java.lang.String factoryInterface, java.lang.String serviceName, java.util.Properties properties)
Create a named service that implements the java interface (or class) fully qualified by factoryInterface.static StandardException
exceptionStartingModule(java.lang.Throwable t)
return a StandardException to indicate that an exception caused starting the module to fail.static java.lang.Object
findService(java.lang.String factoryInterface, java.lang.String serviceName)
Find a service.static java.lang.Object
findServiceModule(java.lang.Object serviceModule, java.lang.String factoryInterface)
Find an unidentified module within a service.static java.lang.Object
findSystemModule(java.lang.String factoryInterface)
Find a module in the system service.static int
getEngineType(java.util.Properties startParams)
static java.util.Locale
getLocaleFromString(java.lang.String localeDescription)
Translate a localeDescription of the form ll[_CC[_variant]] to a Locale object.static ModuleFactory
getMonitor()
Get the monitor.static ModuleFactory
getMonitorLite()
static java.lang.Object
getServiceModule(java.lang.Object serviceModule, java.lang.String factoryInterface)
static java.lang.String
getServiceName(java.lang.Object serviceModule)
Return the name of the service that the passed in module lives in.static HeaderPrintWriter
getStream()
static java.lang.Object
getSystemModule(java.lang.String factoryInterface)
Return a system module.static boolean
isDesiredCreateType(java.util.Properties p, int type)
Return true if the properties set provided contains database creation attributes for a database of the correct typestatic boolean
isDesiredType(int engineType, int desiredType)
Is engineType a match for desiredType.static boolean
isDesiredType(java.util.Properties startParams, int desiredProperty)
static boolean
isFullUpgrade(java.util.Properties startParams, java.lang.String oldVersionInfo)
Single point for checking if an upgrade is allowed.static void
logMessage(java.lang.String messageText)
static void
logTextMessage(java.lang.String messageID, java.lang.Object... args)
static void
logThrowable(java.lang.Throwable t)
Logs the stack trace of the specified throwable object.static StandardException
missingImplementation(java.lang.String implementation)
return a StandardException to indicate a missing implementation.static StandardException
missingProductVersion(java.lang.String productGenusName)
return a StandardException to indicate that a module failed to start because it could not obtain the version of a required product.static java.lang.Object
newInstanceFromIdentifier(int identifier)
Obtain an new instance of a class that supports the given identifier.static void
removePersistentService(java.lang.String name)
static boolean
setMonitor(ModuleFactory theMonitor)
Initialize this class, must only be called by an implementation of the monitor (ModuleFactory).static void
startMonitor(java.util.Properties bootProperties, java.io.PrintWriter logging)
Start a Monitor based software system.static java.lang.Object
startNonPersistentService(java.lang.String factoryInterface, java.lang.String serviceName, java.util.Properties properties)
Start a non-persistent service.static boolean
startPersistentService(java.lang.String serviceName, java.util.Properties properties)
Start a persistent service.static java.lang.Object
startSystemModule(java.lang.String factoryInterface)
Start or find a module in the system service.
-
-
-
Field Detail
-
SERVICE_TYPE_DIRECTORY
public static final java.lang.String SERVICE_TYPE_DIRECTORY
- See Also:
- Constant Field Values
-
syncMe
public static final java.lang.Object syncMe
-
NEW_INSTANCE_FROM_ID_TRACE_DEBUG_FLAG
public static final java.lang.String NEW_INSTANCE_FROM_ID_TRACE_DEBUG_FLAG
Global debug flag to turn on tracing of reads calls newInstanceFromIdentifier()
-
DEBUG_TRUE
public static final java.lang.String DEBUG_TRUE
-
DEBUG_FALSE
public static final java.lang.String DEBUG_FALSE
-
monitor
private static ModuleFactory monitor
-
active
private static boolean active
-
-
Method Detail
-
startMonitor
public static void startMonitor(java.util.Properties bootProperties, java.io.PrintWriter logging)
Start a Monitor based software system. This method will execute the following steps.- Create an instance of a module (monitor) of the required implementation.
- Start the monitor which will in turn start any requested services
- Execute the run() method of startCode (if startCode was not null).
- Return.
If MonitorBoot.start() is called more then once then subsequent calls have no effect.
- Parameters:
bootProperties
- The application propertieslogging
- Where to place initial error output. This location will be used until an InfoStreams module is successfully started.
-
setMonitor
public static boolean setMonitor(ModuleFactory theMonitor)
Initialize this class, must only be called by an implementation of the monitor (ModuleFactory).
-
clearMonitor
public static void clearMonitor()
-
getMonitor
public static ModuleFactory getMonitor()
Get the monitor.
-
getMonitorLite
public static ModuleFactory getMonitorLite()
-
getStream
public static HeaderPrintWriter getStream()
-
getServiceName
public static java.lang.String getServiceName(java.lang.Object serviceModule)
Return the name of the service that the passed in module lives in.
-
startSystemModule
public static java.lang.Object startSystemModule(java.lang.String factoryInterface) throws StandardException
Start or find a module in the system service. This call allows modules to explictly start services they require. If no module matching the criteria is found (see this class's prologue for details) then an instance will be created (see prologue) and booted as follows.((ModuleControl) instance).boot(false, (String) null, (Properties) null);
- Returns:
- a reference to a module.
- Throws:
StandardException
- An attempt to start the module failed.- See Also:
ModuleControl.boot(boolean, java.util.Properties)
-
findSystemModule
public static java.lang.Object findSystemModule(java.lang.String factoryInterface) throws StandardException
Find a module in the system service.- Returns:
- a reference to a module or null if one cannot be found.
- Throws:
StandardException
-
getSystemModule
public static java.lang.Object getSystemModule(java.lang.String factoryInterface)
Return a system module. If it cannot be found or the monitor is not running then null is returned.
-
bootServiceModule
public static java.lang.Object bootServiceModule(boolean create, java.lang.Object serviceModule, java.lang.String factoryInterface, java.util.Properties properties) throws StandardException
Boot or find a unidentified module within a service. This call allows modules to start or create any modules they explicitly require to exist within their service. If no module matching the criteria is found (see this class's prologue for details) then an instance will be created (see prologue) and booted as follows.((ModuleControl) instance).boot(create, (String) null, properties);
The service is defined by the service that the module serviceModule lives in, typically this call is made from the boot method of a module and thus 'this' is passed in for serviceModule.- Returns:
- a reference to a module.
- Throws:
StandardException
- An attempt to start the module failed.
-
bootServiceModule
public static java.lang.Object bootServiceModule(boolean create, java.lang.Object serviceModule, java.lang.String factoryInterface, java.lang.String identifier, java.util.Properties properties) throws StandardException
Boot or find a identified module within a service. This call allows modules to start or create any modules they explicitly require to exist within their service. If no module matching the criteria is found (see this class's prologue for details) then an instance will be created (see prologue) and booted as follows.((ModuleControl) instance).boot(create, identifer, properties);
The service is defined by the service that the module serviceModule lives in, typically this call is made from the boot method of a module and thus 'this' is passed in for serviceModule.- Returns:
- a reference to a module.
- Throws:
StandardException
- An attempt to start the module failed.
-
findServiceModule
public static java.lang.Object findServiceModule(java.lang.Object serviceModule, java.lang.String factoryInterface) throws StandardException
Find an unidentified module within a service.
The service is defined by the service that the module serviceModule lives in.- Returns:
- a reference to a module or null if one cannot be found.
- Throws:
StandardException
-
getServiceModule
public static java.lang.Object getServiceModule(java.lang.Object serviceModule, java.lang.String factoryInterface)
-
findService
public static java.lang.Object findService(java.lang.String factoryInterface, java.lang.String serviceName)
Find a service.- Returns:
- a refrence to a module represeting the service or null if the service does not exist.
-
startPersistentService
public static boolean startPersistentService(java.lang.String serviceName, java.util.Properties properties) throws StandardException
Start a persistent service. The name of the service can include a service type, in the form 'type:serviceName'.
Note that the return type only indicates if the service can be handled by the monitor. It does not indicate the service was started successfully. The cases are- Service type not handled - false returned.
- Service type handled, service does not exist, true returned.
- Service type handled, service exists and booted OK, true returned.
- Service type handled, service exists and failed to boot, exception thrown.
The poperty set passed in is for boot options for the modules required to start the service. It does not support defining different or new modules implementations.
- Parameters:
serviceName
- Name of the service to be startedproperties
- Property set made available to all modules booted for this service, through their ModuleControl.boot method.- Returns:
- true if the service type is handled by the monitor, false if it isn't
- Throws:
StandardException
- An attempt to start the service failed.
-
startNonPersistentService
public static java.lang.Object startNonPersistentService(java.lang.String factoryInterface, java.lang.String serviceName, java.util.Properties properties) throws StandardException
Start a non-persistent service.Context
A context manager will be created and installed at the start of this method and destroyed just before this method returns.- Returns:
- The module from the service if it was started successfully.
- Throws:
StandardException
- An exception was thrown trying to start the service.
-
createPersistentService
public static java.lang.Object createPersistentService(java.lang.String factoryInterface, java.lang.String serviceName, java.util.Properties properties) throws StandardException
Create a named service that implements the java interface (or class) fully qualified by factoryInterface. The Properties object specifies create time parameters to be used by the modules within the service. Any module created by this service may add or remove parameters within the properties object in their ModuleControl.boot() method. The properties set will be saved by the Monitor for later use when the monitor is started.Context
A context manager will be created and installed at the start of this method and destroyed just before this method returns.- Returns:
- The module from the service if it was created successfully, null if a service already existed.
- Throws:
StandardException
- An exception was thrown trying to create the service.
-
removePersistentService
public static void removePersistentService(java.lang.String name) throws StandardException
- Throws:
StandardException
-
classFromIdentifier
public static InstanceGetter classFromIdentifier(int identifier) throws StandardException
Obtain the class object for a class that supports the given identifier. If no class has been registered for the identifier then a StandardException is thrown with no attached java.lang exception (nextException). If a problem loading or accessing the class is obtained then a StandardException is thrown with the real java.lang exception attached.- Returns:
- a valid class object
- Throws:
StandardException
- See text above.
-
newInstanceFromIdentifier
public static java.lang.Object newInstanceFromIdentifier(int identifier) throws StandardException
Obtain an new instance of a class that supports the given identifier. If no class has been registered for the identifier then a StandardException is thrown with no attached java.lang exception (getNestedException). If a problem loading or accessing the class or creating the object is obtained then a StandardException is thrown with the real java.lang exception attached.- Returns:
- a reference to a newly created object
- Throws:
StandardException
- See text above.
-
missingProductVersion
public static StandardException missingProductVersion(java.lang.String productGenusName)
return a StandardException to indicate that a module failed to start because it could not obtain the version of a required product.- Parameters:
productGenusName
- The genus name of the product.- Returns:
- The exception.
-
missingImplementation
public static StandardException missingImplementation(java.lang.String implementation)
return a StandardException to indicate a missing implementation.- Parameters:
implementation
- the module name of the missing implementation.- Returns:
- The exception.
-
exceptionStartingModule
public static StandardException exceptionStartingModule(java.lang.Throwable t)
return a StandardException to indicate that an exception caused starting the module to fail.- Parameters:
t
- the exception which caused starting the module to fail.- Returns:
- The exception.
-
logMessage
public static void logMessage(java.lang.String messageText)
-
logTextMessage
public static void logTextMessage(java.lang.String messageID, java.lang.Object... args)
-
getLocaleFromString
public static java.util.Locale getLocaleFromString(java.lang.String localeDescription) throws StandardException
Translate a localeDescription of the form ll[_CC[_variant]] to a Locale object.- Throws:
StandardException
-
isFullUpgrade
public static boolean isFullUpgrade(java.util.Properties startParams, java.lang.String oldVersionInfo) throws StandardException
Single point for checking if an upgrade is allowed.- Returns:
- true a full upgrade has been requested, false soft upgrade mode is active.
- Throws:
StandardException
-
isDesiredType
public static boolean isDesiredType(java.util.Properties startParams, int desiredProperty)
- Parameters:
startParams
- startup parametersdesiredProperty
- property we're interested in- Returns:
- true type is as desired. false otherwise
-
isDesiredType
public static boolean isDesiredType(int engineType, int desiredType)
Is engineType a match for desiredType. A match exists if the bit intersect of the two values is no zero.
-
getEngineType
public static int getEngineType(java.util.Properties startParams)
- Parameters:
startParams
- startup parameters- Returns:
- type of engine
-
isDesiredCreateType
public static boolean isDesiredCreateType(java.util.Properties p, int type)
Return true if the properties set provided contains database creation attributes for a database of the correct type
-
logThrowable
public static void logThrowable(java.lang.Throwable t)
Logs the stack trace of the specified throwable object.
-
-