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:
Booting Services
Services can be booted a number of ways
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
derby.service.service name=persistent storage type e.g. derby.service.mydatabase=serviceDirectoryserviceDirectory 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 property
derby.protocol=class nameThis is then the factory interface for the service. Other storage types could be added in the future.
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:
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 form
derby.module.tag=java class nameis 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.
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:
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?
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 | Description |
---|---|
Monitor() |
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 type
|
static 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.
|
public static final java.lang.String SERVICE_TYPE_DIRECTORY
public static final java.lang.Object syncMe
public static final java.lang.String NEW_INSTANCE_FROM_ID_TRACE_DEBUG_FLAG
public static final java.lang.String DEBUG_TRUE
public static final java.lang.String DEBUG_FALSE
private static ModuleFactory monitor
private static boolean active
public static void startMonitor(java.util.Properties bootProperties, java.io.PrintWriter logging)
If MonitorBoot.start() is called more then once then subsequent calls have no effect.
bootProperties
- The application propertieslogging
- Where to place initial error output. This location will be used
until an InfoStreams module is successfully started.public static boolean setMonitor(ModuleFactory theMonitor)
public static void clearMonitor()
public static ModuleFactory getMonitor()
public static ModuleFactory getMonitorLite()
public static HeaderPrintWriter getStream()
public static java.lang.String getServiceName(java.lang.Object serviceModule)
public static java.lang.Object startSystemModule(java.lang.String factoryInterface) throws StandardException
((ModuleControl) instance).boot(false, (String) null, (Properties) null);
StandardException
- An attempt to start the module failed.ModuleControl.boot(boolean, java.util.Properties)
public static java.lang.Object findSystemModule(java.lang.String factoryInterface) throws StandardException
StandardException
public static java.lang.Object getSystemModule(java.lang.String factoryInterface)
public static java.lang.Object bootServiceModule(boolean create, java.lang.Object serviceModule, java.lang.String factoryInterface, java.util.Properties properties) throws StandardException
((ModuleControl) instance).boot(create, (String) null, properties);
StandardException
- An attempt to start the module failed.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
((ModuleControl) instance).boot(create, identifer, properties);
StandardException
- An attempt to start the module failed.public static java.lang.Object findServiceModule(java.lang.Object serviceModule, java.lang.String factoryInterface) throws StandardException
StandardException
public static java.lang.Object getServiceModule(java.lang.Object serviceModule, java.lang.String factoryInterface)
public static java.lang.Object findService(java.lang.String factoryInterface, java.lang.String serviceName)
public static boolean startPersistentService(java.lang.String serviceName, java.util.Properties properties) throws StandardException
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.
serviceName
- Name of the service to be startedproperties
- Property set made available to all modules booted
for this service, through their ModuleControl.boot method.StandardException
- An attempt to start the service failed.public static java.lang.Object startNonPersistentService(java.lang.String factoryInterface, java.lang.String serviceName, java.util.Properties properties) throws StandardException
Context
A context manager will be created and installed at the start of this method and destroyed
just before this method returns.
StandardException
- An exception was thrown trying to start the service.public static java.lang.Object createPersistentService(java.lang.String factoryInterface, java.lang.String serviceName, java.util.Properties properties) throws StandardException
Context
A context manager will be created and installed at the start of this method and destroyed
just before this method returns.
StandardException
- An exception was thrown trying to create the service.public static void removePersistentService(java.lang.String name) throws StandardException
StandardException
public static InstanceGetter classFromIdentifier(int identifier) throws StandardException
StandardException
- See text above.public static java.lang.Object newInstanceFromIdentifier(int identifier) throws StandardException
StandardException
- See text above.public static StandardException missingProductVersion(java.lang.String productGenusName)
productGenusName
- The genus name of the product.public static StandardException missingImplementation(java.lang.String implementation)
implementation
- the module name of the missing implementation.public static StandardException exceptionStartingModule(java.lang.Throwable t)
t
- the exception which caused starting the module to fail.public static void logMessage(java.lang.String messageText)
public static void logTextMessage(java.lang.String messageID, java.lang.Object... args)
public static java.util.Locale getLocaleFromString(java.lang.String localeDescription) throws StandardException
StandardException
public static boolean isFullUpgrade(java.util.Properties startParams, java.lang.String oldVersionInfo) throws StandardException
StandardException
public static boolean isDesiredType(java.util.Properties startParams, int desiredProperty)
startParams
- startup parametersdesiredProperty
- property we're interested inpublic static boolean isDesiredType(int engineType, int desiredType)
public static int getEngineType(java.util.Properties startParams)
startParams
- startup parameterspublic static boolean isDesiredCreateType(java.util.Properties p, int type)
public static void logThrowable(java.lang.Throwable t)
Apache Derby V10.14 Internals - Copyright © 2004,2018 The Apache Software Foundation. All Rights Reserved.