Ubik Batch Server BAR Format

From UbikWiki

Current revision

What is a BAR ?

A BAR is a Batch Archive. It is highly similar to a WAR, it contains:

• Batch Classes
• Their JAR dependencies
• a deployment descriptor (bar.xml)
• a logging configuration file (log4j)

Structure of a BAR file :

• /classes : contains JAVA batches classes. Even if you do not have classes in your BAR (because they are in a jar)
• /lib : contains jars dependencies for batches.Even if you do not have dependencies jars in your BAR (because you do not need to)
• bar.xml : the deployment descriptor file. This file must always be named "bar.xml" and be placed under the root of the BAR file
• log.properties or log.xml: the logging configuration file. This file must always be placed under the root of the BAR file and referenced in bar.xml in element <logging-file>.

Note : this structure should always be respected. Otherwise, your BAR will not be considered as a valid one and the batch server will refuse it at deployment time.

The bar.xml file

This file is the deployment descriptor file. It helps you to configure your BAR.

Empty bar.xml file sample :

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE bar-configuration PUBLIC "-//Ubik-Ingenierie //DTD BAR Configuration 1.0//EN" "http://www.ubik-ingenierie.com/consolebatch/config/bar.dtd">
<bar-configuration>
<!-- The display-name must be unique for all bars deployed in the batch server. 
It is recommanded that display-name is the same as the BAR file name for better convenience. 
Display-name must be unique
-->
<display-name>UNIQUE_PROJECT_NAME_FOR_EXAMPLE</display-name>
<!-- Groups of batches -->
<groups>
<group name="GROUP_NAME">
<batches>
<batch-classname>FULL_QUALIFIED_NAME_OF_THE_BATCH_CLASS</batch-classname>
<batch-classname>FULL_QUALIFIED_NAME_OF_THE_BATCH_CLASS2</batch-classname>
</batches>
</group>
<group name="GROUP_NAME2">
<batches>
<batch-classname>FULL_QUALIFIED_NAME_OF_THE_BATCH_CLASS3</batch-classname>
<batch-classname>FULL_QUALIFIED_NAME_OF_THE_BATCH_CLASS4</batch-classname>
</batches>
</group>
</groups>
<!-- Resources -->
<bar-resources>
<bar-resource name="jdbc/console" type="javax.sql.DataSource" />
<bar-resource name="LOGICAL_POOL_NAME" type="javax.sql.DataSource" />
</bar-resources>
<!-- Log4J Configuration -->
<logging-file>LOGGING_CONFIGURATION_FILE_NAME</logging-file>
<!-- Classes to execute when BarLoader is created -->
<plugin>
<plugin-class>FULL_QUALIFIED_NAME_OF_THE_PLUGIN_CLASS</plugin-class>
</plugin>
</bar-configuration>

Description of bar.xml elements :

Constraints

• You cannot have TWO BARs that have batches for the same group. If it is the case, you should put all these batches in the same BAR.
• Batch names must not contain a "." in their name
• You cannot have TWO BARs that have a same batch. Batch server does not manage duplicate batches.
• You cannot have a "registering" batch that call registerAsBatch methods of other batches. Otherwise these batches will be unknown in the BAR. Indeed, only batches that are described in the bar.xml file are added to the BAR classloader. You will get a ClassNotFoundException when registerAsBatch methods for these unknown batches are called.
• If your BAR uses same dependencies jars as the batch server ones, like hibernate for example, you must use the same version as the batch server one (refer to the classloading part for more informations).
• When updating a jndiConnection for a batch/launch with MC4J, be careful and only use logical names. Indeed, them and only them are bound to physical pools. Putting a physical name will lead you to NamingException because the name will not be found in JNDI context of the BAR this batch belongs to.

What is the difference between logical pool name and physical pool name ?

Logical pool name is the JNDI Context name that is written in your batch code :

DaoSqlBatchStart starter = 
     new DaoSqlBatchStart("jdbc/logicalNameForMasterdatas", "MY SQL QUERY", 
          10, false, new String[] { MyDO.class.getName() });

Physical pool name exists in batch server configuration (i.e in datasource.xml file) : "jdbc/masterdatas1" for example.

Authors

• David Dégardin
• Philippe Mouawad