Project

General

Profile

<xweld/>-runtime

The xweld-runtime module defines the various tools and abstractions used to create setup and deployment utilities for <xweld/>-based applications. It provides a set of design patterns useful for deploying and maintaining <xweld/>-based applications, such as static data initialization, and importing and exporting XML configuration and domain data.

Primary Features and Benefits

The package includes command line utilities for:
  • Setting up and configuring <xweld/> applications
  • Importing and exporting data to/from the system via XML-based files
  • Starting and stopping xweld-services
  • Packaging components and their configurations into runtime environments for deployment

Key Concepts

Creating An Initial Configuration For Your Application

When an application is deployed, the domain model for the application itself must be installed and pre-populated with some domain data. For example, if your application uses the conversion manager with or without custom converters, the conversion manager must be informed of the available conversion classes. In order to use the TaskScheduler, the configuration for the tasks needs to be installed in the JPA data store used by your application. Similarly, the finance module will need to install the set of holiday calendars it needs for date rolling.

The <xweld/> SetupTool is a command-line utility that can install all the pre-built <xweld/> data model components and static data as well as call your application-specific setup code to initialize the data store to a startup state.

Supporting Multiple Configurations Of Your Application In A Single JPA Database

Enterprise applications are typically deployed in several environments, QA, DEV, PROD and PERF for example. Traditionally, Java properties files are used to help customize software for multiple environments. As a general practice, using properties files to store configuration data is not as secure as storing sensitive runtime configuration environments in an application's database. For this reason, the runtime module provides the RuntimeContext class. An application may define several named runtime contexts and switch between them without changing code. This makes it much easier to write code that is not cluttered with conditional statements or worse, supporting multiple copies of code for each environment.

To summarize, the SetupTool is used to define the configuration and static data your application needs at runtime. It is typically run as part of the initial deployment and it saves any instances of RuntimeContext needed by your application.

Packages and Classes

The xweld-runtime classes are contained in the following packages:

  • com.xweld.runtime - the runtime modules that support context configuration, persistent dependency injection modules and system environment settings
  • com.xweld.tools - the runtime command line tools and utilities

runtime setup class diagram

Customizing the SetupTool

The command line SetupTool is a generic harness that initializes all the <xweld/> core components you use in your application, such as type conversions, system configuration, and currency conversions. It installs the JPA data model, and can call your implementation of the interface ISetupTool to install your application-specific components and static/domain data.

In order to use the SetupTool utility, you first define a class that implements the ISetupTool interface. Examples of this include the Setup class from the finance module. The interface defines a method "setup" which is provided with an IPersistenceManager instance as well as the command line arguments specified when the utility was executed from the command line. When you write your implementation of this method you can assume the following:

  • A JPA transaction has already been started and commit will be called after the last configured initialize method has been called
  • The <xweld/> configuration manager has been initialized
  • AppUtils.setProperties has already been called so command line properties files specified with the -properties command line switch have been loaded, parsed and set
  • The conversion manager configuration has been reset to its default state, so if your application requires any converters, your initialize method needs to add them back

If errors occur during initialization, your code should throw a ConfigurationException.

Here is an example implementation for 'MyApp'

public class SetupMyApp implements ISetupTool
{
  public  void setup(IPersistenceManager p, String[] args) throws ConfigurationException
  {
    try
    {
      // save the domain model setup for my application
      // persist or merge entities as needed
    }
    catch (Exception e)
    {
      throw new ConfigurationException("An error has occurred", e);
    }
  }
}

Runtime Components

Using SetupTool In Your Application

The setup tool reads the names of the classes that implement ISetupTool from the property com.xweld.setup.types. You need to add your class that implements ISetupTool to the comma-separated list of values in the property when starting the SetupTool. Suppose I have two application setup implementations called Foo and Bar that I want the setup tool to call, after calling those defined by both the finance and security modules. The following command line could be used to accomplish this:

com.xweld.tools.SetupTool 
  -Dcom.xweld.setup.types=com.xweld.authorization.Setup,com.xweld.finance.setup.Setup,Foo,Bar 
  -Djava.security.policy=${workspace_loc:/xweld-runtime/src/main/resources/xweld.policy}
  -Dcom.xweld.persistence.location=META-INF/persistence.xml

which will initialize the <xweld/> default security provider and the finance module, followed by the setups for Foo and Bar respectively.

The SetupTool also supports the command line argument –handler that may be used to specify an implementation of the ISetupHandler class. The interface defines two methods: preSetup(String args[]) and postSetup(String args[]). The first method is called before the persistence manager is initialized and after the –properties command line argument is processed. The postSetup method is called after the commit and immediately before exit.

The –jta option may be used to specify that the setup tool should not start a JPA entity manager transaction, but rather join an existing JTA transaction.

Using RuntimeContext

com.xweld.runtime class diagram

Let's take the example where your application uses two JMS connections, one inbound queue called "Trade Feed" and one outbound topic for errors called "Errors". If we wanted to make two contexts using the same names, one for QA and one for DEV, we would create two instances of RuntimContext in the ISetupTool. Suppose further that in DEV we are using ActiveMQ for our middleware and in QA we are using TIBCO. We want connections with the same name, but with different connection values for the respective JMS providers:

public class SetupMyApp implements ISetupTool
{
  public  void setup(IPersistenceManager p, String[] args) throws ConfigurationException
  {
    try
    {
      RuntimeContext context = null;
      if ((context = p.get("DEV", RuntimeContext.class)) == null)
      {
        context = ContextFactory.create("DEV");
        p.persist(context);
      }
      JmsTopicWriterConfiguration writer = new JmsTopicWriterConfiguration("Errors");
      // configure this writer to use ActiveMQ settings 
      context.addConfiguration(new JmsTopicWriterConfiguration(writer);
      JmsQueueReaderConfiguration reader = new JmsQueueReaderConfiguration("Trade Feed");
      // configure this reader to use ActiveMQ settings 
      context.addConfiguration(reader);
      p.merge(context);

      if ((context = p.get("QA", RuntimeContext.class)) == null)
      {
        context = ContextFactory.create("QA");
        p.persist(context);
      }
      writer = new JmsTopicWriterConfiguration("Errors");
      // configure this writer to use TIBCO settings 
      context.addConfiguration(new JmsTopicWriterConfiguration(writer);
      reader = new JmsQueueReaderConfiguration("Trade Feed");
      // configure this reader to use TIBCO settings 

      p.merge(context);
    }
    catch (Exception e)
    {
      throw new ConfigurationException("An error has occurred", e);
    }
  }
}

This creates two runtime contexts with the same names for each topic and queue but with different connection settings. When you run your application, you can set the property com.xweld.runtime.context on the command line as follows -Dcom.xweld.runtime.context=DEV to specify that the DEV runtime context be used.

You can obtain the context in your code as follows:

 RuntimeContext context = ContextFactory.get(); 

 // Alternatively you can get the context by name:
 context = ContextFactory.get("DEV");

The RuntimeContext class also defines system property settings and the implementation of the dependency injector to use. When the given runtime context is retrieved at run time, each setting in the collection will be set as a system property before the collection is returned. This eliminates the need for external properties files, which are hard to manage and not secure.

The following system properties are set by default (but you can modify the values as needed for your application or extend the set of properties used by the context):

  • com.xweld.security.factory="com.xweld.security.DefaultSecurityProvider"
  • com.xweld.cryptography.algorithm="PBEWithMD5AndDES"
  • com.xweld.finance.currency.money="com.xweld.finance.currency.Money"

Using the ExportTool Utility

The ExportTool is a command line utility that can export any object from the database that implements IXmlizable and IIdentifiable (which is basically everything stored in the JPA database). The data can be exported to a directory of files (using the –directory and –all flags), or an individual key can be exported to a directory of files (using one of the name or –d flags).

The following example exports all the objects of type User into the specified directory:

  ExportTool –type User –all –directory c:\tmp

The following example shows the Administrator User object on standard out:

  ExportTool –type User –name Administrator

Using the ImportTool Utility

The following example shows how to run the ImportTool to save a previously exported object back into the JPA data store:

ImportTool –file MyFile.xml

Running the ServiceTool

Services and Servers are started using the command line ServiceTool. The ServiceTool injects a named configuration into a process and starts it.

The ServiceTool is run as follows:

com.xweld.tools.ServiceTool -start <service name>  -Djava.security.policy=xweld.policy 
                            -Dcom.xweld.persistence.location=META-INF/persistence.xml

where the service name is the name (primary key) of the ServiceConfiguration defined by the SetupTool.

Contact Us

For more information, please contact us at

Copyright

Copyright © 1999-2012 Free North Alliance Inc. All Rights Reserved.

The contents of this web site, including all images, text, graphics and software, are the sole property of Free North Alliance Inc. and its agents. Unauthorized use or transmission is strictly forbidden by international copyright law.

setup.JPG View - runtime setup class diagram (24.5 KB) John Free, 19 October 2011 06:57 AM

com.xweld.runtime.JPG View - com.xweld.runtime class diagram (22.3 KB) John Free, 18 December 2011 03:01 PM