Home » db-derby-10.5.3.0 » org.apache.derby.iapi.services.monitor » [javadoc | source]

    1   /*
    2   
    3      Derby - Class org.apache.derby.iapi.services.monitor.Monitor
    4   
    5      Licensed to the Apache Software Foundation (ASF) under one or more
    6      contributor license agreements.  See the NOTICE file distributed with
    7      this work for additional information regarding copyright ownership.
    8      The ASF licenses this file to you under the Apache License, Version 2.0
    9      (the "License"); you may not use this file except in compliance with
   10      the License.  You may obtain a copy of the License at
   11   
   12         http://www.apache.org/licenses/LICENSE-2.0
   13   
   14      Unless required by applicable law or agreed to in writing, software
   15      distributed under the License is distributed on an "AS IS" BASIS,
   16      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   17      See the License for the specific language governing permissions and
   18      limitations under the License.
   19   
   20    */
   21   
   22   package org.apache.derby.iapi.services.monitor;
   23   
   24   import org.apache.derby.iapi.error.StandardException;
   25   import org.apache.derby.iapi.services.i18n.MessageService;
   26   import org.apache.derby.iapi.services.sanity.SanityManager;
   27   import org.apache.derby.iapi.services.stream.HeaderPrintWriter;
   28   import org.apache.derby.iapi.services.info.ProductGenusNames;
   29   import org.apache.derby.iapi.services.info.ProductVersionHolder;
   30   import org.apache.derby.iapi.reference.EngineType;
   31   import org.apache.derby.iapi.reference.Attribute;
   32   import org.apache.derby.iapi.services.property.PropertyUtil;
   33   
   34   import org.apache.derby.iapi.services.loader.InstanceGetter;
   35   
   36   import org.apache.derby.iapi.reference.SQLState;
   37   import org.apache.derby.iapi.reference.Property;
   38   
   39   import java.util.Properties;
   40   import java.util.Locale;
   41   import java.io.PrintStream;
   42   
   43   /**
   44   	<P><B>Services</B><BR>
   45   
   46   	A service is a collection of modules that combine to provide
   47   	the full functionality defined by the service. A service is defined
   48   	by three pieces of information:
   49   	<OL>
   50   	<LI>A fully qualified java class name that identifies the functionality or API
   51   	that the service must provide. Typically this class represents a java interface.
   52   	This class name is termed the <EM>factory interface</EM>.
   53   	<LI>The <EM>identifier</EM> of the service. Services are identified by a String, this may
   54   	be hard-coded, come from a UUID or any other source.
   55   	<LI>An optional java.util.Properties set.
   56   	</OL>
   57   	<BR>
   58   	The running functionality of the service is provided by a module
   59   	that implements the factory interface. The identifier of the this module
   60   	is not (need not be) the same as the identifier of the service. The identifier
   61   	of the service is held by the monitor in its service tables.
   62   	<BR>
   63   	Each module in a service is keyed by at least one factory interface, identifier}
   64   	pair. This pair is guaranteed to be unique within the service.
   65   	<BR>
   66   	The lifetime of a module in a service is no longer than the lifetime of the service.
   67   	Thus shutting down a service shuts down all the modules within a service.
   68   	<B>Optionally - </B> an individual module within a service may be shutdown, this will
   69   	in turn shutdown any modules it started if those module are not in use by other
   70   	modules within the service. This would be handled by the monitor, not the module itself.
   71   	<BR>
   72   	A service may be persistent, it goes through a boot in create mode, and subsequently boot
   73   	in non-create mode, or a non-peristent service, it always boots in non-create mode.
   74   	Persistent services can store their re-start parameters in their properties set, the monitor
   75   	provides the persistent storage of the properties set.
   76   	Non-persistent services do not have a properties set.
   77   
   78   	<P><B>Booting Services</B><BR>
   79   	Services can be booted a number of ways
   80   	<UL>
   81   	<LI>A non-persistent service can be booted by having a property in the application properties
   82   	or the system (JVM) set.
   83   	<PRE>
   84   	derby.service.<EM>service name</EM>=<EM>class name</EM>
   85   	e.g.
   86   	# Added to the properties automatically by the class org.apache.derby.jdbc.EmbeddedDriver
   87   	derby.service.jdbc=java.sql.Driver
   88   	</PRE>
   89   	<LI>A persistent service can be booted by having a property in the application properties
   90   	or the system (JVM) set.
   91   	<PRE>
   92   	derby.service.<EM>service name</EM>=<EM>persistent storage type</EM>
   93   	e.g.
   94   	derby.service.mydatabase=serviceDirectory
   95   	</PRE>
   96   	serviceDirectory is a type understood by the monitor which means that there is a directory
   97   	named mydatabase within the system directory and within it is a properties file service.properties. This properties
   98   	set is the set for the service and must contain a property
   99   	<PRE>
  100   	derby.protocol=<EM>class name</EM>
  101   	</PRE>
  102   	This is then the factory interface for the service. Other storage types could be added in
  103   	the future.
  104   	<LI>
  105   	The monitor at start time looks for all persistent services that it can find and starts them.
  106   	E.g. all directories in the system directory that have a file service.properties are started
  107   	as services.
  108   	<LI>Services are started on demand, e.g. a findService attempts to boot a service if it
  109   	cannot be found.
  110   	</UL>
  111   	<B>Any or all of these three latter methods can be implemented. A first release may
  112   	just implement the look for all services and boot them.</B>
  113   	.
  114   	<P><B>System Service</B><BR>
  115   	A special service exists, the System Service. This service has no factory interface,
  116   	no identifier and no Properties set. It allows modules to be started that are required
  117   	by another service (or the monitor itself) but are not fundamentally part of the service.
  118   	Modules within this service are unidentified.
  119   	Typically these modules are system wide types of functionality like streams, uuid creation etc.
  120   	<BR>
  121   	The lifetime of a system module is the lifetime of the monitor.
  122   	<B>Optionally - </B> this could be changed to reference count on individual modules, requires
  123   	some minor api changes.
  124   
  125   	<P><B>Modules</B><BR>
  126   
  127   	A module is found or booted using four pieces of information:
  128   	<OL>
  129   	<LI>The service the module lives in or will live in.
  130   	<LI>A fully qualified java class name that identifies the functionality or API
  131   	that the module must provide. Typically this class represents a java interface.
  132   	This class name is termed the <EM>factory interface</EM>.
  133   	<LI>The <EM>identifier</EM> of the module. Modules are identified by a String, this may
  134   	be null, be hard-coded, come from a UUID or any other source. If the identifier
  135   	is null then the module is described as <EM>unidentified</EM>.
  136   	<LI>Boot time only - A java.util.Properties set. This Properties set is service wide
  137   	and typically contains parameters used to determine module implementation or runtime
  138   	behaviour.
  139   	</OL>
  140   	<BR>
  141   	The service is identified by explicitly identifiying the System Service or
  142   	by providing a reference to a module that already exists with the required service.
  143   	<BR>
  144   	The factory interface is provided by a String constant of the form class.MODULE
  145   	from the required interface.
  146   	<BR>
  147   	The module identifier is provided in a fashion determined by the code, in most
  148   	cases a unidentified module will suffice.
  149   	<BR>
  150   	The Properties set is also determined in a fashion determined by the code at
  151   	create or add service time.
  152   
  153     <P><B>Module Implementations</B><BR>
  154   
  155   	When creating an instance of a module, an implementation is found through lists of
  156   	potential implementations.
  157   	<BR>
  158   	A list of potential implementations is obtained from a Properties set. Any property
  159   	within this set that is of the form
  160   	<PRE>
  161   	derby.module.<EM>tag</EM>=<EM>java class name</EM>
  162   	</PRE>
  163   	is seen by the monitor as a possible implementation. <EM>tag</EM> has no meaning within
  164   	the monitor, it is only there to provide uniqueness within the properties file. Typically
  165   	the tag is to provide some description for human readers of the properties file, e.g.
  166   	derby.module.lockManager for an implementation of a lock manager.
  167   	<BR>
  168   	The monitor looks through four properties sets for lists of potential implementations in this
  169   	order. 
  170   	<OL>
  171   	<LI>The properties set of the service (i.e. that passed into Monitor.createPersistentService()
  172   	or Monitor.startService()).
  173   	<LI>The System (JVM) properties set (i.e. java.lang.System.getProperties()).
  174   	<LI>The application properties set (i.e. obtained from the derby.properties file).
  175   	<LI>The default implementation properties set (i.e. obtained from the
  176   	/org/apache/derby/modules.properties resource).
  177   	</OL>
  178   	Any one of the properties can be missing or not have any implementations listed within it.
  179   	<BR>
  180   	Every request to create an instance of a module searches the four implementation
  181   	lists in the order above. Which list the current running code or the passed in service
  182   	module came from is not relevant.
  183   	<BR>
  184   	Within each list of potential implementations the search is conducted as follows:
  185   	<OL>
  186   	<LI>Attempt to load the class, if the class cannot be loaded skip to the next potential
  187   	implementation.
  188   	<LI>See if the factory interface is assignable from the class (isAssignableFrom() method
  189   	of java.lang.Class), if not skip to the next potential implementation.
  190   	<LI>See if an instance of the class can be created without any exceptions (newInstance() method
  191   	of java.lang.Class), if not skip to the next potential implementation.
  192   	<LI>[boot time only] See if the canSupport() method of ModuleControl returns true when called with the
  193   	Properties set of the service, if not skip to the next potential implementation.
  194   	</OL>
  195   	If all these checks pass then the instance is a valid implementation and its boot() method
  196   	of ModuleControl is called to activate it. Note that the search order within
  197   	the list obtained from a Properties set is not guaranteed.
  198   
  199   	 <P><B>Module Searching</B><BR>
  200   
  201   	When searching for a module the search space is always restricted to a single service.
  202   	This service is usually the system service or the service of the module making the
  203   	search request. It would be very rare (wrong?) to search for a module in a service that
  204   	was not the current service and not the system service.
  205   	<BR>
  206   	Within the list of modules in the service the search is conducted as follows:
  207   	<OL>
  208   	<LI>See if the instance of the module an instance of the factory interface (isInstance() method
  209   	of java.lang.Class), if not skip to the next module.
  210   	<LI>See if the identifier of the module matches the required identifier, if not skip to the next module.
  211   	<LI>See if the canSupport() method of ModuleControl returns true when called with the
  212   	Properties set of the service, if not skip to the next module.
  213   	</OL>
  214   	Note that no search order of the modules is guaranteed.
  215   	<BR>
  216   	Also note that a module may be found by a different factory interface to the one
  217   	it was created under. Thus a class may implement multiple factory interfaces, its boot
  218   	method has no knowledge of which factory interface it was requested by.
  219   
  220     <P><B>Service Properties</B><BR>
  221   
  222   	Within the service's Properties a module may search for its parameters. It identifies
  223   	its parameters using a unqiue parameter name and its identifier.
  224   	<BR>
  225   	Unique parameter names are made unique through the 'dot' convention of Properties
  226   	files. A module protocol picks some unique key portion to start, e.g. RawStore for the RawStoreFactory
  227   	and then extends that for specific parameters, e.g. RawStore.PageSize. Thus
  228   	parameters that are typically understood by all implementations of that protocol would
  229   	start with that key portion. Parameters for specific implementations add another key portion
  230   	onto the protocol key portion, e.g. RawStore.FileSystem for an file system implementation
  231   	of the raw store, with a specific parameter being RawStore.FileSystem.SectorSize.
  232   
  233   	<BR>These are general guidelines, UUID's could be used as the properties keys but
  234   	would make the parameters hard to read.
  235   	<BR>
  236   	When a module is unidentified it should look for a parameter using just
  237   	the property key for that parameter, e.g. getProperty("RawStore.PageSize").
  238   	<BR>
  239   	When a module has an identifier is should look for a property using the
  240   	key with a dot and the identifier appended, e.g. getProperty("RawStore.PageSize" + "." + identifier).
  241   	<BR>
  242   	In addition to searching for parameters in the service properties set, the system and
  243   	application set may be searched using the getProperty() method of ModuleFactory.
  244   	<BR><B>Should any order be defined for this, should it be automatic?</B>
  245   */
  246   public class Monitor {
  247   
  248   	public static final String SERVICE_TYPE_DIRECTORY = "serviceDirectory";
  249   
  250   	public static final Object syncMe = new Object();
  251   
  252   	/**
  253   	  Global debug flag to turn on tracing of reads calls newInstanceFromIdentifier()
  254   	  */
  255   	public final static String
  256   		NEW_INSTANCE_FROM_ID_TRACE_DEBUG_FLAG = SanityManager.DEBUG ? "MonitorNewInstanceFromId" : null;
  257   	
  258   	public static final String DEBUG_TRUE = SanityManager.DEBUG ? "derby.debug.true" : null;
  259   	public static final String DEBUG_FALSE = SanityManager.DEBUG ? "derby.debug.false" : null;
  260   
  261   
  262   	private static ModuleFactory monitor;
  263   	private static boolean active;
  264   
  265   	public Monitor() {
  266   	}
  267   
  268   	/**
  269   		Start a Monitor based software system.
  270   
  271   		This method will execute the following steps.
  272   
  273     <OL>
  274     <LI> Create an instance of a module (monitor) of the required implementation.
  275     <LI> Start the monitor which will in turn start any requested services
  276     <LI> Execute the run() method of startCode (if startCode was not null).
  277     <LI> Return.
  278     </OL>
  279     <P> If MonitorBoot.start() is called more then once then subsequent calls
  280     have no effect.
  281   
  282   		@param bootProperties The application properties
  283   		@param logging Where to place initial error output. This location will be used
  284   			until an InfoStreams module is successfully started.
  285   	*/
  286   
  287   	public static void startMonitor(Properties bootProperties, PrintStream logging) {
  288   
  289   		new org.apache.derby.impl.services.monitor.FileMonitor(bootProperties, logging);			
  290   	}
  291   	/**
  292   		Initialise this class, must only be called by an implementation
  293   		of the monitor (ModuleFactory).
  294   	*/
  295   	public static boolean setMonitor(ModuleFactory theMonitor) {
  296   
  297   		synchronized (syncMe) {
  298   			if (active)
  299   				return false;
  300   
  301   			monitor = theMonitor;
  302   			active = true;
  303   			return true;
  304   		}
  305   	}
  306   
  307   	public static void clearMonitor() {
  308   		// the monitor reference needs to remain valid
  309   		// as there are some accesses to getMonitor()
  310   		// after the system has been shutdown.
  311   		synchronized (syncMe) {
  312   			active = false;
  313   		}
  314   	}
  315   
  316   	/**
  317   		Get the monitor.
  318   	*/
  319   	public static ModuleFactory getMonitor() {
  320   		return monitor;
  321   	}
  322   	public static ModuleFactory getMonitorLite() {
  323   		synchronized (syncMe) {
  324   			if (active && monitor != null)
  325   				return monitor;
  326   		}
  327   
  328   		// initialize a monitor just to get system properties
  329   		// with the right secuirty checks and the correct sematics
  330   		// for lookup of derby.system.home.
  331   		// This instance will be discarded once it is used.				;
  332   
  333   		return new org.apache.derby.impl.services.monitor.FileMonitor();
  334   	}
  335   
  336   	public static HeaderPrintWriter getStream() {
  337   		return monitor.getSystemStreams().stream();
  338   	}
  339   
  340   	/**
  341   		Return the name of the service that the passed in module lives in.
  342   	*/
  343   	public static String getServiceName(Object serviceModule) {
  344   		return monitor.getServiceName(serviceModule);
  345   	}
  346   
  347   
  348   	/**
  349   		Start or find a module in the system service. This call allows modules
  350   		to explictly start services they require.
  351   		If no module matching the criteria is found (see this class's prologue for details)
  352   		then an instance will be created (see prologue) and booted as follows.
  353   		<PRE>
  354   		((ModuleControl) instance).boot(false, (String) null, (Properties) null);
  355   		</PRE>
  356   
  357   		@return a reference to a module.
  358   
  359   		@exception StandardException An attempt to start the module failed.
  360   
  361   		@see ModuleControl#boot
  362   	*/
  363   	public static Object startSystemModule(String factoryInterface)
  364   		throws StandardException {
  365   
  366   		Object module = monitor.startModule(false, (Object) null, factoryInterface, (String) null, (Properties) null);
  367   		
  368   		if (SanityManager.DEBUG) {
  369   			SanityManager.ASSERT(module != null, "module is null - " + factoryInterface);
  370   		}
  371   
  372   		return module;
  373   	}
  374   
  375   	/**
  376   		Find a module in the system service.
  377   
  378   		@return a reference to a module or null if one cannot be found.
  379   	*/
  380   	public static Object findSystemModule(String factoryInterface) throws StandardException
  381   	{
  382   		Object module = getMonitor().findModule((Object) null,
  383   									  factoryInterface, (String) null);
  384   		if (module == null)
  385   			throw Monitor.missingImplementation(factoryInterface);
  386   
  387   		return module;
  388   	}
  389   
  390       /**
  391        * Return a system module. If it cannot be found or the monitor is
  392        * not running then null is returned.
  393        */
  394       public static Object getSystemModule(String factoryInterface)
  395       {
  396           ModuleFactory monitor = getMonitor();
  397           if (monitor == null)
  398               return null;
  399           
  400   		Object module = monitor.findModule((Object) null,
  401   									  factoryInterface, (String) null);
  402   		return module;
  403   	}
  404   
  405   	/**
  406   		Boot or find a unidentified module within a service. This call allows modules
  407   		to start or create any modules they explicitly require to exist within
  408   		their service. If no module matching the criteria is found (see this class's prologue for details)
  409   		then an instance will be created (see prologue) and booted as follows.
  410   		<PRE>
  411   		((ModuleControl) instance).boot(create, (String) null, properties);
  412   		</PRE>
  413   		<BR>
  414   		The service is defined by the service that the module serviceModule lives in,
  415   		typically this call is made from the boot method of a module and thus
  416   		'this' is passed in for serviceModule.
  417   
  418   		@return a reference to a module.
  419   
  420   		@exception StandardException An attempt to start the module failed.
  421   
  422   	*/
  423   	public static Object bootServiceModule(boolean create, Object serviceModule,
  424   		String factoryInterface, Properties properties)
  425   		throws StandardException {
  426   
  427   		Object module = monitor.startModule(create, serviceModule, factoryInterface,
  428   						(String) null, properties);
  429   
  430   		if (SanityManager.DEBUG) {
  431   			SanityManager.ASSERT(module != null, "module is null - " + factoryInterface);
  432   		}
  433   
  434   		return module;
  435   	}
  436   
  437   	/**
  438   		Boot or find a identified module within a service. This call allows modules
  439   		to start or create any modules they explicitly require to exist within
  440   		their service. If no module matching the criteria is found (see this class's prologue for details)
  441   		then an instance will be created (see prologue) and booted as follows.
  442   		<PRE>
  443   		((ModuleControl) instance).boot(create, identifer, properties);
  444   		</PRE>
  445   		<BR>
  446   		The service is defined by the service that the module serviceModule lives in,
  447   		typically this call is made from the boot method of a module and thus
  448   		'this' is passed in for serviceModule.
  449   
  450   		@return a reference to a module.
  451   
  452   		@exception StandardException An attempt to start the module failed.
  453   
  454   	*/
  455   	public static Object bootServiceModule(boolean create, Object serviceModule,
  456   		String factoryInterface, String identifier, Properties properties)
  457   		throws StandardException {
  458   
  459   		Object module = monitor.startModule(create, serviceModule, factoryInterface, identifier, properties);
  460   		
  461   		if (SanityManager.DEBUG) {
  462   			SanityManager.ASSERT(module != null, "module is null - " + factoryInterface);
  463   		}
  464   
  465   		return module;
  466   	}
  467   
  468   	/**
  469   		Find an unidentified module within a service.
  470   		<BR>
  471   		The service is defined by the service that the module serviceModule lives in.
  472   
  473   		@return a reference to a module or null if one cannot be found.
  474   
  475   	*/
  476   	public static Object findServiceModule(Object serviceModule, String factoryInterface)
  477   		throws StandardException {
  478   		Object module = getMonitor().findModule(serviceModule, factoryInterface, (String) null);
  479   		if (module == null)
  480   			throw Monitor.missingImplementation(factoryInterface);
  481   		return module;
  482   	}
  483   	public static Object getServiceModule(Object serviceModule, String factoryInterface)
  484   	{
  485   		Object module = getMonitor().findModule(serviceModule, factoryInterface, (String) null);
  486   		return module;
  487   	}
  488   
  489   	/**
  490   		Find an identified module within a service.
  491   		<BR>
  492   		The service is defined by the service that the module serviceModule lives in.
  493   
  494   		@return a reference to a module or null if one cannot be found.
  495   
  496   	*/
  497   	//public static Object findServiceModule(Object serviceModule, String factoryInterface, String identifier) {
  498   	//	return monitor.findModule(serviceModule, factoryInterface, identifier);
  499   	//}
  500   
  501   
  502   	/**
  503   		Find a service.
  504   
  505   		@return a refrence to a module represeting the service or null if the service does not exist.
  506   
  507   	*/
  508   	public static Object findService(String factoryInterface, String serviceName) {
  509   		return monitor.findService(factoryInterface, serviceName);
  510   	}
  511   
  512   	/**
  513   		Start a persistent service. The name of the service can include a
  514   		service type, in the form 'type:serviceName'.
  515   		<BR>
  516   		Note that the return type only indicates
  517   		if the service can be handled by the monitor. It does not indicate
  518   		the service was started successfully. The cases are
  519   		<OL>
  520   		<LI> Service type not handled - false returned.
  521   		<LI> Service type handled, service does not exist, true returned.
  522   		<LI> Service type handled, service exists and booted OK, true returned.
  523   		<LI> Service type handled, service exists and failed to boot, exception thrown.
  524   		</OL>
  525   
  526   		If true is returned then findService should be used to see if the service
  527   		exists or not.
  528   		
  529   		<P> The poperty set passed in is for boot options for the modules
  530   		required to start the service. It does not support defining different
  531   		or new modules implementations.
  532   		
  533   		@param serviceName Name of the service to be started
  534   		@param properties Property set made available to all modules booted
  535   		for this service, through their ModuleControl.boot method.
  536   
  537   		@return true if the service type is handled by the monitor, false if it isn't
  538   
  539   		@exception StandardException An attempt to start the service failed.
  540   	*/
  541   
  542   	public static boolean startPersistentService(String serviceName, 
  543   												 Properties properties) 
  544   		throws StandardException {
  545   
  546   		if (SanityManager.DEBUG) {
  547   			SanityManager.ASSERT(serviceName != null, "serviceName is null");
  548   		}
  549   
  550   		return monitor.startPersistentService(serviceName, properties);
  551   	}
  552   
  553   	/**
  554   		Start a non-persistent service. 
  555   		<P><B>Context</B><BR>
  556   		A context manager will be created and installed at the start of this method and destroyed
  557   		just before this method returns.
  558   
  559   		@return The module from the service if it was started successfully. 
  560   
  561   		@exception StandardException An exception was thrown trying to start the service.
  562   	*/
  563   	public static Object startNonPersistentService(String factoryInterface, String serviceName, Properties properties)
  564   		throws StandardException {
  565   
  566   		if (SanityManager.DEBUG) {
  567   			SanityManager.ASSERT(factoryInterface != null, "serviceName is null");
  568   			SanityManager.ASSERT(serviceName != null, "serviceName is null");
  569   		}
  570   
  571   		return monitor.startNonPersistentService(factoryInterface, serviceName, properties);
  572   	}
  573   
  574   	/**
  575   		Create a named service that implements the java interface (or class) fully qualified by factoryInterface.
  576   		The Properties object specifies create time parameters to be used by the modules within the
  577   		service. Any module created by this service may add or remove parameters within the
  578   		properties object in their ModuleControl.boot() method. The properties set will be saved
  579   		by the Monitor for later use when the monitor is started.
  580   		<P><B>Context</B><BR>
  581   		A context manager will be created and installed at the start of this method and destroyed
  582   		just before this method returns.
  583   
  584   		@return The module from the service if it was created successfully, null if a service already existed. 
  585   
  586   		@exception StandardException An exception was thrown trying to create the service.
  587   	*/
  588   	public static Object createPersistentService(String factoryInterface, String serviceName, Properties properties) 
  589   		throws StandardException {
  590   
  591   		if (SanityManager.DEBUG) {
  592   			SanityManager.ASSERT(factoryInterface != null, "serviceName is null");
  593   			SanityManager.ASSERT(serviceName != null, "serviceName is null");
  594   		}
  595   		
  596   		return monitor.createPersistentService(factoryInterface, serviceName, properties);
  597   	}
  598       public static void removePersistentService(String name)
  599           throws StandardException
  600       {
  601   		monitor.removePersistentService(name);
  602       }
  603   
  604   	/**
  605   		Obtain the class object for a class that supports the given identifier.
  606   
  607   		If no class has been registered for the identifier then a StandardException
  608   		is thrown with no attached java.lang exception (nextException).
  609   		If a problem loading or accessing the class is obtained then a StandardException
  610   		is thrown with the real java.lang exception attached.
  611   
  612   		@return a valid class object
  613   
  614   		@exception StandardException See text above.
  615   	*/
  616   	public static InstanceGetter classFromIdentifier(int identifier) 
  617   		throws StandardException {
  618   		return monitor.classFromIdentifier(identifier);
  619   	}
  620   
  621   	/**
  622   		Obtain an new instance of a class that supports the given identifier.
  623   
  624   		If no class has been registered for the identifier then a StandardException
  625   		is thrown with no attached java.lang exception (getNestedException).
  626   		If a problem loading or accessing the class or creating the object is obtained
  627   		then a StandardException is thrown with the real java.lang exception attached.
  628   
  629   		@return a reference to a newly created object
  630   
  631   		@exception StandardException See text above.
  632   	*/
  633   	public static Object newInstanceFromIdentifier(int identifier) 
  634   		throws StandardException {
  635   		return monitor.newInstanceFromIdentifier(identifier);
  636   	}
  637   
  638   
  639   	/* 
  640   	** Static methods for startup type exceptions.
  641   	*/
  642   		/**
  643   		return a StandardException to indicate that a module failed to
  644   		start because it could not obtain the version of a required product.
  645   
  646   		@param productGenusName The genus name of the product.
  647   		@return The exception.
  648   	*/
  649   	public static StandardException missingProductVersion(String productGenusName)
  650   	{
  651   		return StandardException.newException(SQLState.MISSING_PRODUCT_VERSION, productGenusName);
  652   	}
  653   
  654   	/**
  655   		return a StandardException to indicate a missing
  656   		implementation.
  657   
  658   		@param implementation the module name of the missing implementation.
  659   
  660   		@return The exception.
  661   	*/
  662   	public static StandardException missingImplementation(String implementation) 
  663   	{
  664   		return StandardException.newException(SQLState.SERVICE_MISSING_IMPLEMENTATION, implementation);
  665   	}
  666   
  667   	/**
  668   		return a StandardException to indicate that an exception caused
  669   		starting the module to fail.
  670   
  671   		@param t the exception which caused starting the module to fail.
  672   
  673   		@return The exception.
  674   	*/
  675   	public static StandardException exceptionStartingModule(Throwable t)
  676   	{
  677   		return StandardException.newException(SQLState.SERVICE_STARTUP_EXCEPTION, t);
  678   	}
  679   
  680   	public static void logMessage(String messageText) {
  681   		getStream().println(messageText);
  682   	}
  683   
  684   	public static void logTextMessage(String messageID) {
  685   		getStream().println(MessageService.getTextMessage(messageID));
  686   	}
  687   	public static void logTextMessage(String messageID, Object a1) {
  688   		getStream().println(MessageService.getTextMessage(messageID, a1));
  689   	}
  690   	public static void logTextMessage(String messageID, Object a1, Object a2) {
  691   		getStream().println(MessageService.getTextMessage(messageID, a1, a2));
  692   	}
  693   	public static void logTextMessage(String messageID, Object a1, Object a2, Object a3) {
  694   		getStream().println(MessageService.getTextMessage(messageID, a1, a2, a3));
  695   	}
  696   	public static void logTextMessage(String messageID, Object a1, Object a2, Object a3, Object a4) {
  697   		getStream().println(MessageService.getTextMessage(messageID, a1, a2, a3, a4));
  698   	}
  699   
  700   	/**
  701   	 *  Translate a localeDescription of the form ll[_CC[_variant]] to
  702   	 *  a Locale object.
  703   	 */
  704   	public static Locale getLocaleFromString(String localeDescription)
  705   								throws StandardException {
  706   		return monitor.getLocaleFromString(localeDescription);
  707   	}
  708   
  709   
  710   	/**
  711   		Single point for checking if an upgrade is allowed.
  712   		@return true a full upgrade has been requested, false soft upgrade mode is active.
  713   	 */
  714   	public static boolean isFullUpgrade(Properties startParams, String oldVersionInfo) throws StandardException {
  715   
  716   		boolean fullUpgrade = Boolean.valueOf(startParams.getProperty(org.apache.derby.iapi.reference.Attribute.UPGRADE_ATTR)).booleanValue();
  717   
  718   		ProductVersionHolder engineVersion = Monitor.getMonitor().getEngineVersion();
  719   
  720   		if (engineVersion.isBeta() || engineVersion.isAlpha()) {
  721   					
  722   			if (!PropertyUtil.getSystemBoolean(Property.ALPHA_BETA_ALLOW_UPGRADE))
  723   			{
  724   				//  upgrade not supported for alpha/beta.
  725   				throw StandardException.newException(SQLState.UPGRADE_UNSUPPORTED,
  726   						oldVersionInfo, engineVersion.getSimpleVersionString());
  727   			}
  728   		}
  729   
  730   		return fullUpgrade;
  731   	}
  732   
  733   	/**
  734   	  *
  735   	  *	@param	startParams			startup parameters
  736   	  *	@param	desiredProperty		property we're interested in
  737   	  *
  738   	  *	@return	true		type is as desired.
  739   	  *			false		otherwise
  740   	  *
  741   	  */
  742   	public static boolean isDesiredType(Properties startParams, int desiredProperty )
  743   	{
  744   		int		engineType = EngineType.STANDALONE_DB;
  745   
  746   		if ( startParams != null )
  747   		{
  748   			engineType = Monitor.getEngineType( startParams );
  749   		}
  750   
  751   		return (engineType & desiredProperty) != 0;
  752   	}
  753       
  754       /**
  755        * Is engineType a match for desiredType. A match exists
  756        * if the bit intersect of the two values is no zero.
  757        */
  758   	public static boolean isDesiredType(int engineType, int desiredType) {
  759   		return (engineType & desiredType) != 0;
  760   	}
  761   	
  762   	/**
  763   	  *	@param	startParams		startup parameters
  764   	  *
  765   	  *	@return	type of engine
  766   	  *
  767   	  */
  768   
  769   	static	public	int	getEngineType(Properties startParams)
  770   	{
  771   		if ( startParams != null )
  772   		{
  773   			String etp = startParams.getProperty(EngineType.PROPERTY);
  774   
  775   			int engineType = etp == null ? EngineType.STANDALONE_DB : Integer.parseInt(etp.trim());
  776   
  777   			return engineType;
  778   		}
  779   
  780   		return EngineType.STANDALONE_DB;
  781   	}
  782   
  783   	/**
  784   	  Return true if the properties set provided contains
  785   	  database creation attributes for a database
  786   	  of the correct type
  787   	  */
  788   	public static boolean isDesiredCreateType(Properties p, int type)
  789   	{
  790   		boolean plainCreate = Boolean.valueOf(p.getProperty(Attribute.CREATE_ATTR)).booleanValue();
  791   
  792   		if (plainCreate) {
  793   			return (type & EngineType.STANDALONE_DB) != 0;
  794   		}
  795   
  796   		// database must already exist
  797   		return isDesiredType(p, type);
  798   	}
  799   
  800       /**
  801        * Logs the stack trace of the specified throwable object.
  802        */
  803       public static void logThrowable(Throwable t) {
  804           t.printStackTrace(getStream().getPrintWriter());
  805       }
  806   }

Home » db-derby-10.5.3.0 » org.apache.derby.iapi.services.monitor » [javadoc | source]