Java Doc for Monitor.java in  » Database-DBMS » db-derby-10.2 » org » apache » derby » iapi » services » monitor » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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:

1. 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.
2. The identifier of the service. Services are identified by a String, this may be hard-coded, come from a UUID or any other source.
3. An optional java.util.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 property

   derby.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:

1. The service the module lives in or will live in.
2. 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.
3. 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.
4. 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.

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 name
 

1. The properties set of the service (i.e. that passed into Monitor.createPersistentService() or Monitor.startService()).
2. The System (JVM) properties set (i.e. java.lang.System.getProperties()).
3. The application properties set (i.e. obtained from the cloudscape.properties file).
4. The default implementation properties set (i.e. obtained from the /org/apache/derby/modules.properties resource).

1. Attempt to load the class, if the class cannot be loaded skip to the next potential implementation.
2. See if the factory interface is assignable from the class (isAssignableFrom() method of java.lang.Class), if not skip to the next potential implementation.
3. 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.
4. [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:

1. 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.
2. See if the identifier of the module matches the required identifier, if not skip to the next module.
3. 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.

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?

1. Create an instance of a module (monitor) of the required implementation.
2. Start the monitor which will in turn start any requested services
3. Execute the run() method of startCode (if startCode was not null).
4. Return.

If MonitorBoot.start() is called more then once then subsequent calls have no effect.
Parameters:
  bootProperties - The application properties
Parameters:
  logging - Where to place initial error output.

 ((ModuleControl) instance).boot(create, (String) null, properties);
 

 ((ModuleControl) instance).boot(create, identifer, properties);
 

Context
A context manager will be created and installed at the start of this method and destroyed just before this method returns. The module from the service if it was created successfully, null if a service already existed.
exception:
  StandardException - An exception was thrown trying to create the service.

1. Create an instance of a module (monitor) of the required implementation.
2. Start the monitor which will in turn start any requested services
3. Execute the run() method of startCode (if startCode was not null).
4. Return.

If MonitorBoot.start() is called more then once then subsequent calls have no effect.
Parameters:
  bootProperties - The application properties
Parameters:
  logging - Where to place initial error output. This location will be useduntil an InfoStreams module is successfully started.

Context
A context manager will be created and installed at the start of this method and destroyed just before this method returns. The module from the service if it was started successfully.
exception:
  StandardException - An exception was thrown trying to start the service.

1. Service type not handled - false returned.
2. Service type handled, service does not exist, true returned.
3. Service type handled, service exists and booted OK, true returned.
4. 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 started
Parameters:
  properties - Property set made available to all modules bootedfor this service, through their ModuleControl.boot method. true if the service type is handled by the monitor, false if it isn't
exception:
  StandardException - An attempt to start the service failed.

 ((ModuleControl) instance).boot(false, (String) null, (Properties) null);