User Manual

1. What is JORM?
2. Getting Started.
• JORM Installation.
• Running the Example.
3. Roles.
4. Architecture Principles.
• Accessor, Binding, and Memory Instance.
• Persistent Names.
• Class Mapping and Binders.
• Mapper.
5. Using JORM.
• Application Development.
• JORM Configuration.
• Application Configuration.
6. Configuring the JORM Generator.
• Overview.
• Running the Compiler.
• Properties Files.
7. Extending JORM.
• Programming a new Mapper.
• Programming a Name Management.

1. What is JORM?

JORM (Java Object Repository Mapping) is an adaptable persistence service. It can be used to offer various personalities, such as one compliant with the CMP EJB specification (TM), another with the OMG PSS specification or another with the JDO (Java Data Objects) specification (TM).

JORM can provide object persistency through different secondary storage supports, such as files, relational databases or object-oriented databases.

2. Getting Started.

The purpose of this tutorial is to explain how to install JORM and to guide the user through the examples provided with JORM.

JORM Installation.

Prerequisites

JORM requires that you have a JDK 1.2.2 or higher installed on your machine. This is enough to use JORM. In order to compile JORM, you will also need to have ant. The examples require that Ant and PostgreSQL be installed on your machine, and currently do not work with the JDK 1.4.

Where to find JORM?

You can find JORM on the ObjectWeb site, at the JORM home page.

What to download?

JORM is an Open Source product of the ObjectWeb community. You can either download the source code or a binary version. The source code of JORM is available through CVS. Binary versions are available for download from the JORM download page.

Setting up the JORM environment

Choose a location for the JORM installation, for example your_install_dir.

Beware that, if you have already installed a previous version of JORM in this location, the new installation will overwrite previous files and previously customized configuration files may be lost. It is thus carefull to save such files before starting the installation process.

The installation process starts with unzipping the downloaded file in the your_install_dir directory. To unzip these files, just go to your_install_dir, and unzip it. You can use gunzip JORM_1_0_src.zip on unix-like systems, or, for example, winzip on Windows systems.

If you start from the JORM source code, please refer to the "Compiling JORM" section to build a JORM distribution. If you start from a binary version of JORM, you are ready to use JORM. Once you have a JORM distribution, you can run the examples. There is no need to set any environment variable.

Compiling JORM

The JORM project, like the other ObjectWeb projects uses the Ant tool for compilation. You must have Ant version 1.4 available on your system. The steps to compile and to obtain a distribution of JORM are the following:

1. Customize the build.properties file. This file permits to specify:
   • where to produce .class files (build property),
   • where the JORM distribution will be created (dist property),
   • where two zip files containing the contents of respectively the dev and dist directories will be created (zip property),
   • as well as several other options.

   The default values create new build, dist and zip directories in the output directory of the project. The example below illustrates a case where the directory dev contains the project files.

   

2. Run ant to compile JORM, ant dist to compile and generate a distribution of JORM or ant zip to produce the two zip files.

Running the Example.

The JORM distribution contains several examples which have the same organization. This section describes the principles for building, configuring and running an example. The same process applies to each example.

Note that there is no need to set any environment variable to run the JORM examples.

The distribution contains an examples directory. This directory contains:

• a README file which explains the organization of directories,
• one directory for each example,
• a build.xml file to launch all examples (does not work currently),
• a lib directory which contains the libraries shared by the examples,
• a etc directory which contains the configuration files shared by the examples and especially the log4j.properties file used to configure the log system.

Each example directory contains:

• a README file which explains the example,
• a build.xml file to compile (ant compile) and run (ant execute) the example,
• a lib directory which contains the libraries specific to the example,
• an etc directory which contains the following example configuration files:
• generation.propeties, used to parameter the generation of JORM classes (xxxAccessor, xxxBinding, xxxMapping) for the example,
• execute.properties, describing which class must be launched (run.classname property) with which parameters (run.parameters property),
• other configuration files specific to the example.
• a src directory which contains the source code and the persistent descriptors (.pd files) of the example.

Building an example

To build an example, go to the directory of this example and execute ant without parameter: ant.

Configuring the database access

All current examples require a database. JORM currently works only with the PostgreSQL database. This is going to be update to take in account other databases such as Oracle, InterBase or MySQL. This evolution should not invole too much effort. As a rule the etc directory of an example contains a runtime.properties which contains the following properties which have to be configured:

• jdbcDriverClassName org.postgresql.Driver
• jdbcUrl jdbc:postgresql:jormTest
• jdbcUserName theUserName
• jdbcUserPassword theUserPassword

These properties are used to specify which database to use (jdbcDriverClassName), what is the url of your the database, what is the user name used for accessing the database, and finally the password of the user.

Running an example

To run an example, first it must have been compiled as shown above and the access to the database must have been also configured for this example. Then go to the directory of this example and execute ant with the parameter execute: ant execute.

3. Roles.

Two types of developers interact with JORM:

• The JORM users develop applications containing persistent objects. See the Application Developpement section for more details.
• The JORM contributors can develop new mappers, for example for other persitent supports than the ones already handled by JORM. See the Extending JORM section for more details.

4. Architecture Principles.

Accessor, Binding, and Memory Instance.

Memory Instance (MI): This is a Java object that holds the variables that are made persistent. It is accessed by a JORM Accessor in order to load/store variables from/to the data store.

JORM Accessor: This is an object that supports an "accessor" pattern (i.e., paSetVar / paGetVar methods) for giving access to the variables that contain persistent data within execution memory. It is used by a JORM Binding for accessing variables of MIs when loading/storing persistent data. It implements a JORM PAccessor interface produced from the JORM definition.

JORM Binding: A JORM Binding is a Java object that implements the PBinding interface. This is the key concept of JORM as this is the mediator object that organizes data transfers between a data store and a particular memory instance within execution memory. Thus the main operations that can be invoked on this object are read (from the data store), and write (to the data store). Before performing these operations, a Binding must have been assigned both a Persistent Name that identifies a data store instance, and a memory instance represented by a PAccessor object.

Object composition

In the compiled JORM implementation (i.e., Accessor interfaces, Bindings and Mapping objects are generated by JORM), the generator gives the possilibity to specify if the generated xxxBinding class extends a given user class. This option allows the user to compose the objects the way s/he wants. The unique constraint is that the Binding must have a link to an object which implements the PAccessor interface. The following table shows different possible compositions for class Toto, where TotoAccessor is the generated Paccessor interface, TotoBinding is the generated PBinding class, TotoImpl is the application class and PAToto is a class implementing the TotoAccessor interface when applicable:

Persistent Names.

Definitions

Persistent Name: A persistent name, or "PName", is an entity, represented by a Java object in execution memory, which uniquely identifies a persistent object within a particular naming context. It can either translate to a Binding giving access to the associated data store instance, or to another persistent name in another persistent naming context (this is recursive).

Persistent Naming Context: This is a persistent entity that keeps the associations between persistent names and their associated Bindings or other persistent names. It is thus used to resolve persistent names into one of the two cases. Within a persistent naming context, a name always translates to a unique Binding or to a unique other persistent name.

Naming contexts used as reference managers

The following example illustrates the use of persistent naming context.

This example represents the simple case where a Client object references a single Equipements object.
Each memory instance is accompanied by its Binding and its Mapping.
In addition, a naming context manages the reference of the Client to the Equipements. Indeed, a PName is used by the Client to identify which Equipements is referenced; this PName is valid into a naming context.

There are several possible solutions.

1. The ClientMapping references a PNamingContext which is in reality the EquipementsMapping instance.
2. In an other solution, the ClientMapping references an intermediate PNamingContext, (EquipementsPNC), which uses another PNamingContext, or as in the figure a particular naming context, which is the PClassMapping itself.

Class Mapping and Binders.

Mapper.

JORM Mapper: A Mapper is a Java object that represents the data store encapsulated by JORM. It assumes that the data store it references complies with JCA. The mapper itself complies with this architecture. Its main function is to give access to mapping of persistent classes. It keeps the associations between the names of JORM persistent definitions and their associated Binder/Binding factory.

5. Using JORM.

Application Development.

JORM users develop applications containing persistent objects. The tasks of the user to add the persitency to its objects are the following:

1. First write the persistent descriptor (.pd files) for each persistent object with respect to the JORM DTD available in all distributions in the etc directory.
2. As the JORM generator permits differents combination between the persistent memory instance, the generated xxxBinding, the xxxAccessor and the xxxMapping, the user has to decide an architecture. In case the generated xxxBinding (or xxxMapping) class extends an existing class, this class has to be written.
3. The third step is the generation of the JORM objects. To generate you have to specify compiler parameters

What is the content of a persistent descriptor?

A persistent descriptor describes the persistence of one class only. This aim of this section is to help a user to write an xml persistent descriptor. To do this we analyse several examples to better understand the JORM DTD.

• The first example illustrated below is provided in all JORM distributions. This example is the most simple class with two primitive fields.
  

  Each xml file must contain a reference to the DTD file.	<!DOCTYPE JORMDef SYSTEM ../../etc/JORM.dtd"> <JORMDef>
  The Schema is the package name of the persistent object. It defines the package in which the generated files will be created. This value does not reference the persistent object class.	<Schema Name="org.objectweb.JORM.examples.basic" />
  All persistent classes must have a name. This name will be used to compose the name of the generated files. In this example the generated Accessor file would be org.objectweb.JORM.examples.basic.ClientAccessor. There is only one class description per .pd file.	<Class Name="Client">
  In this example, this first persistent field is named identifier. The name of a field is important, as it is used to produce a setter and a getter methods in the generated xxxAccessor file. The field description also contains the type of the field. Here, the type is a primitive type, i.e., a simple value. More exactly, the type of the field is the long. Note that the type defined here is the JORM type, and not the Java type directly. A translation table is defined in the JORM specification. However, note that the long JORM type is mapped into the Java primitive long type. Associated to a description of a PrimitiveType , a mapping is defined (ValueMapping). As a persistent descriptor can contain several mapping definitions for different mappers, each mapping is named (here the name is LongNaming). A mapping defines the way a field becomes persistent into the persistent support. This example shows the mapping of the field into a relationnal database (rdbValueMapping ). A rdbValueMapping contains columns descriptors (rdbColumnSpec). Indeed, the field is mapped into a column inside a relation. In a rdbColumnSpec, the column name is required. It is also possible to specify whether the column must be not null, or the sql column type. The type of the column is a SQL type. The second field is named lastName. This field is mapped to the column named LN. The type of this column is VARCHAR(25).	<Field Name="identifier">   <PrimitiveType TypeCat="long">     <ValueMapping>       <rdbValueMapping       MappingName="LongNaming">         <rdbColumnSpec           Name="Id"           NotNull="TRUE" />       </rdbValueMapping>     </ValueMapping>   </PrimitiveType> </Field>
  	<Field Name="lastName">   <PrimitiveType TypeCat="string" Size="25">     <ValueMapping>       <rdbValueMapping         MappingName="LongNaming">           <rdbColumnSpec Name="LN"           Type="VARCHAR(25)" />       </rdbValueMapping>     </ValueMapping>   </PrimitiveType> </Field>
  JORM needs to idendity an object. In JORM, an identifier is a PName. A PName is described in the persistent descriptor by a NameDef section. In this example, the PName of a Client object is composed by a single field, which is the identifier field of the object.	<NameDef>   <UsedByMapping     MapperName="rdb"     MappingName="LongNaming"/>     <FieldName Name="identifier" /> </NameDef>
  This sections describes where the class is stored within the persistent support. In the case of a relational database, the information is the table name.	<ClassMapping>   <rdbClassMapping     MappingName="LongNaming">     <rdbTableName Name="TClient1"/>   </rdbClassMapping > </ClassMapping>
  End of the class description	</Class>
  End of the JORM definition	</JORMDef>

• The second example is also provided in all JORM distributions. This example is more complex than the previous one because it describes a Client object which references an Equipement object:
  

  This example is an extension of the basic example. The first two fields have the same description section.	<!DOCTYPE JORMDef SYSTEM "../../etc/JORM.dtd"> <JORMDef> <Schema Name="org.objectweb.JORM.examples.basic" />  <Class Name="Client">  <Field Name="identifier">   <PrimitiveType TypeCat="long">     <ValueMapping>       <rdbValueMapping>         MappingName="LongNaming">         <rdbColumnSpec Name="Id" NotNull="TRUE" />       </rdbValueMapping>     </ValueMapping>   </PrimitiveType> </Field> <Field Name="lastName">   <PrimitiveType TypeCat="string" Size="25">     <ValueMapping>       <rdbValueMapping MappingName="LongNaming">         <rdbColumnSpec Name="LN" Type="VARCHAR(25)"/>       </rdbValueMapping>     </ValueMapping>   </PrimitiveType> </Field>
  Start of the description of the equipements field.	<Field Name="equipments">
  This field is a reference to another object. In this section, the class name of the referenced class must be indicated.	<RefClass ClassName="org.objectweb.JORM.examples.ref.Equipments" />
  JORM permits to store the reference between objects. The information which is stored for a reference is the PName of the referenced object. This section describes the PName of the reference and how it is mapped into the persistent support. In this example, the reference to Equipements is composed of two field. The first field is named objId. Its type is long and it is mapped onto the column named OI. The second field of the reference is named binderId. Its type is also long and it is mapped onto the column named BI.	<NameDef>   <UsedByMapping MapperName="rdb" MappingName="LongNaming"/>   <ScalarField Name="objId">     <ScalarType Type="long" />       <ValueMapping>         <rdbValueMapping MappingName="LongNaming">           <rdbColumnSpec Name="OI"/>         </rdbValueMapping>       </ValueMapping>   </ScalarField>   <ScalarField Name="binderId">     <ScalarType Type="long"/>       <ValueMapping>         <rdbValueMapping MappingName="LongNaming">           <rdbColumnSpec Name="BI"/>         </rdbValueMapping>       </ValueMapping>   </ScalarField> </NameDef>
  End of the field description	</Field>
  The description of the PName of a Client and the mapping of the class do not change.	<NameDef>   <UsedByMapping MapperName="rdb" MappingName="LongNaming"/>   <FieldName Name="identifier" /> </NameDef> <ClassMapping>   <rdbClassMapping MappingName="LongNaming">     <rdbTableName Name="TClient1" />   </rdbClassMapping > </ClassMapping> </Class> </JORMDef>

JORM Configuration.

The JORM configuration concerns only the naming aspect. This aspect depends on the application and the types of names used. The naming layers are therefore independent of the JORM layer, and can be built over the JORM layer. Before reading this section, it is highly recommended to understand the JORM principles about the naming aspects.

• The JORM distribution provides an implementation of naming based on long identifiers. This solution is used in the examples provided with JORM, and can be used by a JORM user. This section briefly explains the architecture and the actions to perform in order to initialize this naming layer. For more details, read the implementation documentation about this subject.

  This naming implementation based on long identifier provides persistent names (PName) which use a long to identify a memory instance. These PName are LName objects in the implementation. The LName instances are created by a LBinder.

  As a PName can be used as reference to an object, JORM provides a naming context which manages PNLong. This naming context is called LLPnc. Among the roles of a naming context are the support of polymorphism and federation. Thus, the LLPnc references a set of BinderLong, and not a single BinderLong. The following picture illustrates all existent objects when using LLPnc:

  The LLPnc references a set of BinderLong. To each BinderLong, a LongGen is associated to generate unique long identifiers. As these four object are persistent, this diagram also shows their Binding and their Mapping. There is a naming context for each reference of a persistent class to another one (StrBinder objects).

  This folowing table describes the different actions to realize in order to initialize this naming solution:

  Two common variables are used inside the code. The first one is cleanAction. This variable is used to specify whether the data support must be cleaned during a mapping action. Indeed, the first time the application runs, the support must be clean, whereas when the application restarts nothing must be done. The second common field is the persistent support connection. For example in the relational database mapper case, the connection is a java.sql.Connection.	byte cleanAction = ... Object conn = ...
  The first step is the creation of the mapper. The mapper must be initialized with a LoggerFactory to enable tracing. For more details about tracing see the MonoLog specification of ObjectWeb. In this example, the mapper name is "rdb" because this instance represents a mapper to a relational database.	Mapper mapper = new Mapper(); mapper.setMapperName("rdb"); ((Loggable) mapper).setLoggerFactory(loggerFactory);
  The initialisation starts by the element the most at left of the diagram. Then this code section initializes the LonGen family: Allocate a binder for the new LGenerator mapping. Note that the instanciation of the LGenerator Mapping is generic and depends on a string which defines its class name. Indeed the class name depends on the mapper name Link the binder and the mapping, Specify the MIManager wihch in this case is also the mapping, Map the mapping into the mapper (~register).	StrBinder bsoflg = new StrBinder(); PClassMapping lgm = (PClassMapping) newInstance(lGeneratorMappingClassName); lgm.setPBinder(bsoflg); bsoflg.setPClassMapping(lgm); lgm.setMIManager(lgm); mapper.map(conn, lgm, cleanAction );
  This code section initializes the BinderLong family: Allocate a binder for the new LBinder mapping. Note that the instanciation of the LBinder Mapping is generic and depends on a string which defines its class name. Indeed the class name depends on the mapper name Link the binder and the mapping, Specify the MIManager wihch in this case is also the mapping, Map the mapping into the mapper (~register),	StrBinder bsoflb = new StrBinder(); lBinderMapping = (PClassMapping) newInstance(lBinderMappingClassName); lBinderMapping.setPBinder(bsoflb); bsoflb.setPClassMapping(lBinderMapping); lBinderMapping.setMIManager(lBinderMapping); mapper.map(conn, lBinderMapping, cleanAction );
  This code section initializes the Binderset family: Allocate a binder for the new Set mapping. Note that the instanciation of the Set Mapping is generic and depends on a string which defines its class name. Indeed the class name depends on the mapper name Link the binder and the mapping, Link the generic class mapping to the mapping of the referenced object (BinderLongFactory), Specify the MIManager (SetManager), The mapping of a generic class is never map into a mapper.	StrBinder bsofs = new StrBinder(); PClassMapping sm = (PClassMapping) newInstance(setMappingClassName); sm.setPBinder(bsofs); bs3.setClassMappingBinder(rsf); bsofs.setPClassMapping(sm); SetManager setmanager = new SetManager(); sm.setMIManager(setmanager); sm.setGenClassMapping(lBinderMapping);
  This code section initializes the PNCLong family: Allocate a binder for the new LLPnc mapping. Note that the instanciation of the LLPnc Mapping is generic and depends on a string which defines its class name. Indeed the class name depends on the mapper name Link the binder and the mapping, Link the LLPnc class mapping to the mapping of the generic class, Specify the MIManager wihch in this case is also the mapping, Map the mapping into the mapper (~register).	StrBinder bsofpnc = new StrBinder(); llPncMapping = (PClassMapping) newInstance(llPncMappingClassName); llPncMapping.setPBinder(bsofpnc); bsofpnc.setPClassMapping(llPncMapping); llPncMapping.setGenClassMapping("classbinders",sm); llPncMapping.setMIManager(llPncMapping); mapper.map(conn, llPncMapping, cleanAction);
  This code section sets a naming context to manage the reference field. Indeed the LBinder contains a reference to a LGenerator object. The naming context is also the binder associeted to the LGenerator mapping.	lBinderMapping.setPNamingContext("generator", bsoflg, true);
  This code section sets a naming context to manage the reference field. Indeed the GenClass contains a reference to LBinder objects. The naming context is also the binder associeted to the LBinder mapping.	sm.setPNamingContext(bsoflb, true);
  This code section sets a naming context to manage the reference field. Indeed the LLPnc objects contain a reference to a GenClass object. The naming context is also the binder associeted to the Set mapping.	llPncMapping.setPNamingContext("classbinders", bsofs, true);

Application Configuration.

This section explains how to initialize an application. The previous section shows that JORM needs initialization for the naming used within an application. This naming initialization permits to initialize the JORM objects of the application. This section uses the the "refsingle" example available in JORM to describes a possibility to initialize an application.

Reminder:

6. Configuring the JORM Generator.

Overview.

The compiler system is the user entry point. The compiler is a process manager, it reads information, generates files, and compiles them. The following section describes how to use the JORM compiler.

Running the Compiler.

There are two ways to launch the JORM compiler. The first possibility is to use the Java command line, specify parameters on the command line or in a properties file. The properties file is described in the third part of this section. The second possibility is to use the JCompiler interface to set properties, and launch the JORM process, like a sub-project (not in a separate virtual machine).

Java command line

All interactions with the JORM system are organised around a compilation command. This section provides a description of that command along with the way input and output information is organised. This command is very primitive and more advanced tools such as GUI ones should be provided as a different means for interacting with JORM.

This command has mandatory input items, and potentially some outputs. The first mandatory input item is the JORM persistence definition for which to generate the mapping. The file name must be the entity name (interface or class) suffixed by ".pd".

The command line is described below in more details.

NAME

java org.objectweb.jorm.comp.cmdline.CommandLine - the JORM command-line compiler

SYNOPSIS

java org.objectweb.jorm.comp.cmdline.CommandLine [-ext cmdlineparser] [-classpath path[:path]] [-v] [-V] [-h] [-javac jCompiler] [-keepsrc] [-bindingabstract] [-nocompile] [-conf configfile] [-noverify] [-nodtdverify] [-verifier verifier] -mappername mapper [-metainfo metaInformationManager] -mappingname mapping -parser parser -d path -mappingfactory factory file [file] ...

DESCRIPTION

The JORM compiler generates all relevant information for mapping some Java persistent classes to a particular persistent store. The command line must at least specify the name of the mapper, the name of the mapping, the class name of the specific xml parser, the output directory, the class name of the mapping factory to create specific mapping objects, and files to be compiled.
The files to be compiled are XML files that describe the persistent object schemas to be mapped to a persistent store. Its format must be compliant with the DTD described in the source tree (see src/org/objectweb/jorm/parser/api/jorm.dtd). JORM uses theXerces parser to generate a DOM tree and to process it.

OPTIONS

-ext cmdlineparser
This options allows to use a new command line parser to parse specific options. cmdlineparser class must be an implementation of the org.objectweb.jorm.comp.cmdline.api.CmdLineParser interface. After the cmdlineparser class, the user has to specify the specific options to parse. The parsing of the new options is finished when known options are encountered.

-classpath path[;path]
This option allows the specification of the different paths from which the JORM persistence definition files can be searched. Such a file is either the file given as the mandatory input argument of the command line, or the files of schemas specified by import clauses expressed in the previous file, and transitively in imported schema files. This option overrides the equivalent paths specified by the standard Java CLASSPATH environment variable. If not specified, the considered paths are those defined by the previous environment variable. If this variable is also undefined, only the current working directory is considered.

-v
This modifier requests the verbose version of an operation. Many operations display additional information, such as filenames processed, when  the modifier `v' is appended.

-V
This option prints the version number of JORM.

-h
This option displays all the options of the JORM command line.

-javac jCompiler
This option specifies the javac compiler to use in order to compile java file.

-keepsrc
This option allows to keep the java sources, and not to remove them after compilation (not yet implemented).

-bindingabstract
This option allows to generate abstract binding object.

-nocompile
This option allows to disable the compilation part.

-conf configfile
This option gives to JORM a configuration file which contains properties. These properties are read when the -conf option has been set. All properties are processed. A configuration file is not mandatory but is very useful when the command line has numerous parameters and options with many persistence description files.

-noverify
When the meta information has been built, a verifier module verifies data in the meta information. This option allows to disable the verifier and continue the process.

-nodtdverify
This option allows to disable the verification of the XML files with the dtd.

-verifier verifier
There are two levels of meta information verification. The first level verifies common objects in the meta information. This part of the meta information contains global objects. The second level verifies specific objects which are dependant from the mapping. The verifier option allows to specify a verifier class which follows the org.objectweb.jorm.parser.api.MappingParser interface.

-mappername mapper
This option is mandatory. It defines the name of the mapper.
example. : -mappername rdb

-mappingname mapping
This option is mandatory. This option defines the name of the mapping. A mapping name is a sub-part of a mapper. A relational database mapper may contains several mappings, for several database types and actual database instances.

-parser parser
This option is mandatory. It defines the class which manages the XML mapping parsing and fills in the mapping specific part of the meta information. There is one mapping parser delivered with JORM and an RdbParser which is a mapping parser for relational database mapper.

-d path
This option is mandatory. The -d option allows the specification of a path into which the generated Java files are placed.

-mappingfactory factory
This option is mandatory. The mapping factory option is the class name of the factory able to create specific ClassMapping and ValueMapping objects. There is one mapping factory delivered with JORM, an RdbMappingFactory which is a mapping factory for relational database mapper.
example : -mappingfactory org.objectweb.jorm.metainfo.lib.rdb.RdbMappingFactory.

-metainfo metaInformationManager
This option allows to set up a meta information manager system. The parameter must be a class name. This class must implement the Manager api from the metainfo system.
i.e. : -metainfo org.objectweb.jorm.metainfo.lib.BasicManager.

ENVIRONMENT VARIABLES

The following variables could affect the JORM process:

CLASSPATH
The Java CLASSPATH is reused to specify the different paths where the JORM schema files to be compiled can be searched. Its string value has exactly the same format as the one specified by the -I option: a list of path strings separated either by a ':' for Unix systems or by a ';' for Windows systems. It is ignored when the -I option is specified.

JORM compiler

The JORM compiler is the second way to call the JORM process. It is a Javac like call. The JORM compiler is a single class with a list of setter methods to set properties (like a command line or a properties file).
This object is org.objectweb.jorm.comp.compiler.lib.Compiler class. Please refer to its interface: org.objectweb.jorm.com.compiler.api.JCompiler for the description of the methods.
This class has an execute() method to launch the JORM process.

Properties Files.

The properties file can be used on the Java command line with the -conf option, or with the JCompiler interface and its implementation: Compiler(String configFile).

A typical jorm.properties file is :

# keeps the java source files after the javac process
#  true: the java sources are kept
#  false: the java sources are deleted
keepsrc: true

# defines the name of the java compiler. Use absolute path.
javacompiler: /usr/local/java/bin/javac

# defines the verbose mode for the debugging informations.
#  true: all the debugging informations are displayed
#  false: the debugging informations are not sent to the user
verbose: false

# defines the list of the xml files (persistance description files)
inputfile:

# defines the name of the mapper
#  rdb, is the default Object Relationnal mapper.
mappername: rdb

# defines the name of the mapping
mappingname: myDatabaseWithRefToNames

# defines the name of the mapping factory class which is able to create
# mapping object for the meta information.
mappingfactory: org.objectweb.jorm.metainfo.lib.rdb.BasicRDBMappingFactory

# defines the name of the parser class corresponding to the mapping process.
parser: org.objectweb.jorm.parser.lib.rdb.RDBParser

# defines the path+name of the log system file
log.config.file: logSystem.properties

# defines the name of the class which makes the verification of the meta
# information for the mapping specific part.
verifier: org.objectweb.jorm.verifier.lib.rdb.RdbVerifier

# defines the class name of the meta information system
#metainfo:

# defines if the dtd must be used or not to validate xml files.
# If nothing is specified, xml files are checked.
#  true: the dtd is used to check the xml files
#  false: the dtd is not used to check the xml files
#dtdverify: true

7. Extending JORM.

Programming a new Mapper.

Programming a Name Management.