PSS Module User Guide

Compiling OMG PSDL files and generating associated Java mapping implementations

The psdl_java script allows you to compile an OMG PSDL file and generate associated Java mapping implementations:

• Java interfaces and classes
• The JDO descriptor

$ cat test/sample.psdl
// This file is the OMG PSDL example used in the OpenCCM User's Guide.
#pragma prefix "ccm.objectweb.org"
module sample
{
  storagetype ST {};
  storagehome SH of ST {};
};
$
$ psdl_java test/sample.psdl
psdl_java 0.9.0: Reading from file test/sample.psdl...
psdl_java 0.9.0: Preprocessing file test/sample.psdl...
psdl_java 0.9.0: File test/sample.psdl preprocessed.
psdl_java 0.9.0: Compiling test/sample.psdl file...
psdl_java 0.9.0: Compilation completed: 0 warning.
psdl_java 0.9.0: Generating Java mapping from test/sample.psdl ...
File '.../generated/org/objectweb/ccm/sample/sample.jdo' has been generated
File '.../generated/org/objectweb/ccm/sample/ST.java' has been generated
File '.../generated/org/objectweb/ccm/sample/SH.java' has been generated
psdl_java 0.9.0: Java mapping generated.
$

The generated classes are the Java mapping associated to the OMG PSDL definitions. The .jdo file contains JDO information allowing a JDO enhancer to inject code related to persistence automatically.

$ ls generated/org/objectweb/ccm/sample/
sample.jdo  SH.java  ST.java
$

The psdl_java script supports the following options:

To obtain usage and help information, do:

$ psdl_java --help
Usage: psdl_java [-h|--help] [--version] [--silent]
                 [--cpp path] [-P] [-DNAME|-DNAME=DEF] [-UNAME] [-IDIR]
                 [-d outputdir] file
                 [-jdoprop jdo_properties_file]

Options:
  -h, --help         Display this information and exit
  --version          Output version information and exit
  --silent           Silent output messages
  --cpp path         Set the path to the external C preprocessor used
  -P                 Inhibit generation of #-lines with line-number information
  -DNAME, -DNAME=DEF Define NAME as DEF, default is 1
  -UNAME             Remove any definition for NAME
  -IDIR              Put DIR in the include file search path
  -d outputdir       Generate Java mapping in directory <outputdir>,
                     default is generated/
  -jdoprop jdo_properties_file Get user classes definition from the properties file <jdo_properties_file>
                               default is "jdouser.properties"

Description:
  Compile an OMG PSDL file and generate its associated Java mapping

$

To obtain version information, do:

$ psdl_java --version
OpenCCM psdl_java 0.9.0

Copyright (C) 2000-2003 INRIA - USTL - LIFL - GOAL
. . .
$

By default, the psdl_java script displays messages. To silent these output messages, do:

$ psdl_java --silent test/sample.psdl
$

By default, the psdl_java script uses an internal preprocessor written in Java. However, it is possible to use any external C/C++ preprocessor, e.g.:

$ psdl_java --cpp /usr/bin/cpp test/sample.psdl
. . .
$

Let's note that the standard -P, -D, -U and -I options for the C/C++ preprocessor could be passed as arguments to psdl_java before the file name, e.g.:

$ psdl_java -DFOO -Itest test/sample.psdl
. . .
$

When some preprocessing options are often used, e.g. -IAnIncludeDir, -DTheMacro, then they could be set by default in the xml/launcher/PSDLtoJava.xml file if they are specific to the psdl_java script or in the xml/launcher/Compiler.xml file if they are required by all OpenCCM compilation scripts.

By default, the __OMG_IDL_3__ macro is defined by the OpenCCM OMG IDL/PSDL/CIDL compiler. This macro could be used to distinguish if used OMG IDL modules should be imported from the OpenCCM Interface Repository or if their associated files should be included, e.g.

// An OMG PSDL file.

#ifdef __OMG_IDL_3__

// This file is compiled by an OMG IDL 3.x compliant compiler.

import CORBA;

#else

// This file is compiled by a non OMG IDL 3.x compliant compiler.

#include <CORBA.idl>

#endif

// ...

By default, the psdl_java script generates the Java mapping into the generated/ directory. However, the -d outputdir option allows you to specify another directory, e.g.:

$ psdl_java -d mapping test/sample.psdl
. . .
$ ls mapping/org/objectweb/ccm/sample/
sample.jdo  SH.java  ST.java
$

When user classes inherit from generated classes for OMG PSDL, this is required with JDO to enhance these user classes. The -jdoprop jdo_properties_file option allows you to specify which user classes must be enhanced. jdo_properties_file is the name of the properties file used to specify user classes inheritance. This file must define properties as following:

my_user_class = its_super_class 

This means that my_user_class inherits from its_super_class. If there are multiple inheritance levels, you must specify all classes that are not defined in the OMG PSDL file.

Then the psdl_java script can produce specific tags for JDO or generate a full JDO file if the user classes are in another packages.