src/java/org/apache/turbine/services/package.html - turbine-core - Git at Google

 <html>
 <head>
 <!-- head part is ignored -->
 </head>

 <body>
 Contains the Service framework for Turbine.
 <p>
 Services are singletons that have pluggable implementation
 and can participate in Turbine startup and shutdown.
 <p>
 <table><tr><td width="100%">

 <h3>What is a service?</h3>
 <ul>
 <li> Is a singleton -  there is only one instance of it in the system
      i.e. memory or connections are allocated once only, and the internal
      state is common to all requesting clients.
 <li> Has pluggable implementation - you can use your own implementation
      if you need, just change  an entry in TurbineResources.properties,
      and there you go.
 <li> Can access ServletConfig at system startup time to process
      relative paths and the like.
 <li> Can access RunData on the first Turbine doGet execution to
      get URL we're running under and the like.
 <li> Can initialize itself (allocate memory, make connctions)
      just before the client requests it for the first time. Services that
      are never used by the application will not allocate resources.
 <li> Can execute some action upon system shutdown e.g. close the
      opened connections.
 </ul>
 <h3>The life cycle of a Service</h3>
 <p>
 A Service (or any other Initable, if we had any) is not supposed
 to do much in it's constructor. Especialy it should not allocate
 any costly resources like large memory structures, DB or network
 connections and the like. It may well happen that the Service
 is sitting in the config file, but the application does not
 need it, so allocating all resources at system startup might
 be a loss.
 <p>
 Early initialization is similar to the constructor. It is used
 to pass some information that the Service will need in it's
 future operation.
 UniqueId Service uses the HttpRequest object from the first Turbine
 invocation to determine URL this instance is runnign under, to
 generate instance ID.
 Early initialization method should process the configuration, store
 some values, but NOT allocate resources. There is still a chance
 that the Service will not be used.
 If the Service is ready to work (i.e. does not need any more objects
 being sent to it), and does not to allocate any resources during
 late initialization, the internal state can be changed so that
 getInit() returns true.
 <p>
 Late initialization happens when the Service is requested by the
 application for the first time. It should allocate any resources
 needed and chnge the state so that getInit() returns true.
 If getInit() returns false after init() is executed, the Service
 has malfunctioned.
 <p>
 After late initialization, the Service is ready to perform actions
 on behalf of the application.
 <p>
 When the Service is no longer needed (this usually happens when
 system is shutting down), the shutdown() method is called.
 shutdown() should deallocate all resources. If any error conditions
 occur they are ignored.
 <h3>Initialization of services outside of the Turbine servlet</h3>
 <p>
 In the case where specific Turbine services are desired outside the
 context of the <code>Turbine</code> servlet, a Turbine JAR file can be
 used in conjunction with a <i>properly configured</i>
 <code>TurbineResources.properties</code> file to initialize a specific
 set of services to use in your application.  The following sample
 code performs such initialization:
 <p>
 <blockquote><code><pre>
 String webAppRoot = "/var/httpd/webapps";
 String trProps = "/var/httpd/TurbineResources.properties";
 try
 {
     TurbineConfig cfg = new TurbineConfig(webAppRoot, trProps);
     cfg.init();
 }
 catch (Exception e)
 {
     // If Turine fails to initialize, no logging service will be available.
     String msg = "Failed to initialize Turbine: " + e.getMessage();
     // Write directly to stderr to preserve the full stack trace.
     System.err.println(msg);
     e.printStackTrace();
     throw new Error(msg);
 }
 </pre></code></blockquote>
 </td></tr></table>
 <br>
 <font size="-2">$Id$</font>
 </body>
 </html>
	<html>
	<head>
	<!-- head part is ignored -->
	</head>

	<body>
	Contains the Service framework for Turbine.
	<p>
	Services are singletons that have pluggable implementation
	and can participate in Turbine startup and shutdown.
	<p>
	<table><tr><td width="100%">

	<h3>What is a service?</h3>
	<ul>
	<li> Is a singleton - there is only one instance of it in the system
	i.e. memory or connections are allocated once only, and the internal
	state is common to all requesting clients.
	<li> Has pluggable implementation - you can use your own implementation
	if you need, just change an entry in TurbineResources.properties,
	and there you go.
	<li> Can access ServletConfig at system startup time to process
	relative paths and the like.
	<li> Can access RunData on the first Turbine doGet execution to
	get URL we're running under and the like.
	<li> Can initialize itself (allocate memory, make connctions)
	just before the client requests it for the first time. Services that
	are never used by the application will not allocate resources.
	<li> Can execute some action upon system shutdown e.g. close the
	opened connections.
	</ul>
	<h3>The life cycle of a Service</h3>
	<p>
	A Service (or any other Initable, if we had any) is not supposed
	to do much in it's constructor. Especialy it should not allocate
	any costly resources like large memory structures, DB or network
	connections and the like. It may well happen that the Service
	is sitting in the config file, but the application does not
	need it, so allocating all resources at system startup might
	be a loss.
	<p>
	Early initialization is similar to the constructor. It is used
	to pass some information that the Service will need in it's
	future operation.
	UniqueId Service uses the HttpRequest object from the first Turbine
	invocation to determine URL this instance is runnign under, to
	generate instance ID.
	Early initialization method should process the configuration, store
	some values, but NOT allocate resources. There is still a chance
	that the Service will not be used.
	If the Service is ready to work (i.e. does not need any more objects
	being sent to it), and does not to allocate any resources during
	late initialization, the internal state can be changed so that
	getInit() returns true.
	<p>
	Late initialization happens when the Service is requested by the
	application for the first time. It should allocate any resources
	needed and chnge the state so that getInit() returns true.
	If getInit() returns false after init() is executed, the Service
	has malfunctioned.
	<p>
	After late initialization, the Service is ready to perform actions
	on behalf of the application.
	<p>
	When the Service is no longer needed (this usually happens when
	system is shutting down), the shutdown() method is called.
	shutdown() should deallocate all resources. If any error conditions
	occur they are ignored.
	<h3>Initialization of services outside of the Turbine servlet</h3>
	<p>
	In the case where specific Turbine services are desired outside the
	context of the <code>Turbine</code> servlet, a Turbine JAR file can be
	used in conjunction with a <i>properly configured</i>
	<code>TurbineResources.properties</code> file to initialize a specific
	set of services to use in your application. The following sample
	code performs such initialization:
	<p>
	<blockquote><code><pre>
	String webAppRoot = "/var/httpd/webapps";
	String trProps = "/var/httpd/TurbineResources.properties";
	try
	{
	TurbineConfig cfg = new TurbineConfig(webAppRoot, trProps);
	cfg.init();
	}
	catch (Exception e)
	{
	// If Turine fails to initialize, no logging service will be available.
	String msg = "Failed to initialize Turbine: " + e.getMessage();
	// Write directly to stderr to preserve the full stack trace.
	System.err.println(msg);
	e.printStackTrace();
	throw new Error(msg);
	}
	</pre></code></blockquote>
	</td></tr></table>
	<br>
	<font size="-2">$Id$</font>
	</body>
	</html>