org.portico.core
Class Bootstrap

java.lang.Object
  com.lbf.commons.component.AbstractComponent
      org.portico.core.Bootstrap

All Implemented Interfaces:

com.lbf.commons.component.IComponent

Direct Known Subclasses:

JSOPBootstrap, JVMBootstrap

public abstract class Bootstrap
extends com.lbf.commons.component.AbstractComponent

A Bootstrap is a component that is notified when the Portico RTI server is starting up and shutting down. Generally speaking, Bootstrap subclasses have been used by the communications bindings as a way to do any setup and cleanup they require as the RTI is starting or stopping. For example, a socket-based binding would need to start a Server Socket on startup to listen for incoming connections. As Bootstraps are notified when the RTI starts and stops, this is the perfect place to create/destroy the socket.

Although communications bindings are the main reason the Bootstrap facility was created, they are not the only use. Rather, a Bootstrap could be used for ANY facility that need to startup or shutdown with the RTI server.

Bootstraps

Each Bootstrap has a defined lifecycle. All bootstraps *MUST* extend from this class and provide implementations of the startBootstrap() and stopBootstrap() methods.

Although it is not mandatory, Bootstraps can also provide an implementation of the configureBootstrap(Bag) methods. The bag of properties passed to that method will contain with them the XML properties provided with the bootstrap configuration (if it was XML based).

The lifecycle of a bootstrap is (this is the same as an IComponent):

1. configureBootstrap(Bag)
2. startBootstrap()
3. == Server starts to shutdown ==
4. stopBootstrap()

Threading

Many tasks (such as listening on a ServerSocket for incoming connections) are long-lived, requiring a dedicated thread. Under no circumstances should the startBootstrap() method block for any serious length of time. If such behaviour is needed, use startBootstrap() to start a new worker thread (or worker threads).

Configuration

Bootstraps are declared in XML within the Portic configuration file or a plugin configuration file and they look something like this:

 <portico>
   <bootstraps>
     <bootstrap name="jsop" class="org.portico.binding.jsop.rti.JSOPBootstrap"/>
   </bootstraps>
 </portico>
 

However, should additional configuration parameters be needed, they can be passed to the Bootstrap in one of two ways.

Firstly, they could be provided as system properties, which the Bootstrap could then look for during either configureBootstrap(Bag) or startBootstrap(). This approach is clean and requires no real extra effort beyond setting the system properties.

The second approach is to provide the information as part of the bootstrap XML declaration. The listing below shows how this would be done for the bootstrap declaration above:

 <portico>
   <bootstraps>
     <bootstrap name="jsop" class="org.portico.binding.jsop.rti.JSOPBootstrap">
       <configuration>
         <endpoint port="20913"/>
       </configuration>
     </bootstrap>     
   </bootstraps>
 </portico>
 

Here, a child element of the bootstrap called configuration is provided. Beneath it can be any well-formed XML. If this information exists, it is turned into name-value pairs and put into the Bag of information passed to the configureBootstrap(Bag) method. Using the example above, the following code would print out the string "20913":

  public void configureBootstrap( Bag properties ) throws ConfigurationException
  {
      System.out.println( properties.get( "configuration.endpoint.port" );
  }
 

IMPORTANT NOTE

Bootstrap implementations must provide a no-arg constructor so that they can be easily instantiated via reflection. The no-arg constructor should pass a default bootstrap name to the constructor of this abstract class.

Field Summary

protected com.lbf.commons.messaging.IMessageHandler	bootstrapHandler
static String	CONFIG_HANDLER
static String	CONFIG_RTIEXEC
protected RTIExec	execution
protected org.apache.log4j.Logger	logger

Fields inherited from class com.lbf.commons.component.AbstractComponent

executing, name, shutdown

Constructor Summary

protected

Bootstrap(String name) Create a new bootstrap with the given name.

Method Summary

void	configure(com.lbf.commons.utils.Bag<String,?> properties) This method extracts from the given properties a number of requsite components (such as the bootstrap handler, to which create/join/destroy requests should be passed).
void	configureBootstrap(com.lbf.commons.utils.Bag<String,?> properties) Called when the Bootstrap is being configured.
void	execute() This method will invoke the startBootstrap() method, the implementation of which has to be provided by the concrete class.
void	federationCreated(Federation theFederation) This method is called by the RTI when a new Federation has been created.
void	federationDestroyed(String federationName) This method is called by the RTI when a federation has been destroyed.
com.lbf.commons.messaging.IMessageHandler	getBootstrapHandler() Get the bootstrap handler.
RTIExec	getExecution() Gets the RTIExec that this bootstrap is contained within.
org.apache.log4j.Logger	getLogger() Get the logger that should be used for all messages.
void	shutdown() This method will invoke the stopBootstrap() method, the implementation of which has to be provided by the concrete class.
abstract void	startBootstrap() This method tells the component that it is time to start up.
abstract void	stopBootstrap() This method tells the component that it is time to shut down.

Methods inherited from class com.lbf.commons.component.AbstractComponent

cleanup, getName, isExecuting, isShutdown, setName

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CONFIG_HANDLER

public static final String CONFIG_HANDLER

See Also:

Constant Field Values

CONFIG_RTIEXEC

public static final String CONFIG_RTIEXEC

See Also:

Constant Field Values

bootstrapHandler

protected com.lbf.commons.messaging.IMessageHandler bootstrapHandler

execution

protected RTIExec execution

logger

protected org.apache.log4j.Logger logger

Constructor Detail

Bootstrap

protected Bootstrap(String name)

Create a new bootstrap with the given name. Note that names among bootstraps must be unique. When a bootstrap that has the same name as an existing bootstrap is registered, an exception will be thrown and the registration will fail.

Method Detail

startBootstrap

public abstract void startBootstrap()
                             throws com.lbf.commons.component.ComponentException

This method tells the component that it is time to start up. If there is a problem during startup, a ComponentException should be thrown to indicate that the bootstrap didn't start. This method is mandatory in all Bootstraps

Throws:

com.lbf.commons.component.ComponentException

stopBootstrap

public abstract void stopBootstrap()
                            throws com.lbf.commons.component.ComponentException

This method tells the component that it is time to shut down. If there is a problem during shutdown, a ComponentException should be thrown to indicate that the bootstrap didn't stop properly. This method is mandatory in all Bootstraps

Throws:

com.lbf.commons.component.ComponentException

configureBootstrap

public void configureBootstrap(com.lbf.commons.utils.Bag<String,?> properties)
                        throws com.lbf.commons.config.ConfigurationException

Called when the Bootstrap is being configured. If a Bootstrap is created from an XML configuration file and additional configuration data is provided, the contained properties will have that information (but it will be flattened). See the class-level comments for more details. Overriding this method is NOT mandatory.

Throws:

com.lbf.commons.config.ConfigurationException

getBootstrapHandler

public com.lbf.commons.messaging.IMessageHandler getBootstrapHandler()

Get the bootstrap handler. All create/destroy/join requests received from remote clients should be passed to this handler, NOT to the RTIExec.

getExecution

public RTIExec getExecution()

Gets the RTIExec that this bootstrap is contained within.

getLogger

public org.apache.log4j.Logger getLogger()

Get the logger that should be used for all messages. Don't use System.out or System.err, use this logger.

federationCreated

public void federationCreated(Federation theFederation)

This method is called by the RTI when a new Federation has been created. The Federation instance that was created is provided. Override this method in your Bootstrap implementations if you want to receive notifications when a federation is created.

The implementation in this class takes no action on this event (it is empty).

federationDestroyed

public void federationDestroyed(String federationName)

This method is called by the RTI when a federation has been destroyed. It is the inverse of the federationCreated(Federation) method. As the federation has been destroyed, only the name of the federation is provided (you really shouldn't be accessing the destoryed federation instance. If you want to receive these notifications, override this method.

The implementation in this class takes no action on this event (it is empty).

configure

public final void configure(com.lbf.commons.utils.Bag<String,?> properties)
                     throws com.lbf.commons.config.ConfigurationException

This method extracts from the given properties a number of requsite components (such as the bootstrap handler, to which create/join/destroy requests should be passed). The properties also contains any additional XML configuration properties given in the config for the bootstrap (see the class-level comments for more information).

Once the extraction process is complete, this method will call configureBootstrap(Bag), passing the properties it was given.

NOTE: You cannot provide an implementation of this method. If you want to fetch configuration properties, use configureBootstrap(Bag).

Specified by:

configure in interface com.lbf.commons.component.IComponent

Overrides:

configure in class com.lbf.commons.component.AbstractComponent

Throws:

com.lbf.commons.config.ConfigurationException

execute

public final void execute()
                   throws com.lbf.commons.component.ComponentException

This method will invoke the startBootstrap() method, the implementation of which has to be provided by the concrete class. It will catch any exceptions that are thrown and treat such a condition as a failure to start. It also performs the necessary management logic for the IComponent.

Specified by:

execute in interface com.lbf.commons.component.IComponent

Overrides:

execute in class com.lbf.commons.component.AbstractComponent

Throws:

com.lbf.commons.component.ComponentException

shutdown

public final void shutdown()
                    throws com.lbf.commons.component.ComponentException

This method will invoke the stopBootstrap() method, the implementation of which has to be provided by the concrete class. It will catch any exceptions that are thrown and treat such a condition as a failure to shutdown. It also performs the necessary management logic for the IComponent.

Specified by:

shutdown in interface com.lbf.commons.component.IComponent

Overrides:

shutdown in class com.lbf.commons.component.AbstractComponent

Throws:

com.lbf.commons.component.ComponentException