Ubik Batch Server BAR Format

From UbikWiki

Contents

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 :


Element name
Description
display-name It can be considered as the unique ID of a BAR. The value should be unique for all BARs deployed in the same batch server. As BARs files should also be unique in the same batch server, giving to this value the BAR file name can be a good way to ensure the unicity.
groups A BAR can contain batches of different groups. Child elements of this one are GROUP elements.
group The value is the name of the group of batches. Batches are gathered in groups. For a group, you can have several batches. Child element of this one is the BATCHES element.
batches Child elements of this one are BATCH-CLASSNAME.
batch-classname The value is the full-qualified name (i.e with the package name) of the batch class.
bar-resources It contains a list of BAR-RESOURCE elements
bar-resource Resources are javax.sql.DataSource ones (attribute value), javax.jms.ConnectionFactory, javax.jms.Queue or javax.jms.Topic .Resources you put in this file are logical names for resource(i.e the JNDI Context name that is written in your batch code) and must be bound to a physical resource that exists in batch server.You do not need to precise which batch server pool will be chosen in the bar.xml file but do not forget to add all used pools to this list, otherwise batch will not work (it will not be able to connect to database because binding is not done and logical name is unknown for the BAR).Note that "jdbc/console" will be automatically bound to the physical console pool by default. Even if you do not have resources to bind, please leave this line..
logging-file The value must be the name of the logging configuration file for your BAR that must be placed to the root of your BAR.
plugin It contains a list of PLUGIN-CLASS elements
plugin-class The value of this element must be the full-qualified name of a class placed in your BAR that implements Iplugin interface. When creating the classloader for your BAR, init() method of this class will be called. When destroying the classloader, destroy() method will be called.Note that classes that you put in this list MUST implements IPlugin interface, otherwise a TechnicalException will be thrown when deploying your BAR.

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
Retrieved from "http://wiki.ubik-ingenierie.com/ubikwiki/index.php?title=Ubik_Batch_Server_BAR_Format"
Personal tools