AIDAJNI

AIDAJNI 3.0.4 Release Notes

Release Notes Version: : 1.15 $.

The most recent version of this file is available here.
Release notes for all versions of AIDAJNI are available here.

AIDAJNI is a C++ adapter of AIDA - Abstract Interfaces for Data Analysis which connects to a Java implementation of AIDA, such as JAIDA.

AIDAJNI allows C++ programmers to use any Java AIDA implementation.

It allows for instance Geant4, written in C++, to create histograms and ntuples in Java and store them in .aida files, which can be analyzed using JAS3 - Java Analysis Studio.

Contents

• AIDA Compliance
• Supported Platforms
• Major changes in AIDAJNI 3.0.4
• Documentation
• License
• Installing AIDJNI
• Compiling AIDAJNI
• Building an Application with AIDAJNI
• Running an Application with AIDAJNI
• Using AIDAJNI from Geant4
• Features/Limitations of the Current Release
• Reporting Bugs
• Examples

AIDA Compliance

This adapter connects AIDA-C++ to AIDA-JNI. It almost fully supports the AIDA standard. The C++ side is AIDA 3.0 compliant (for usage in Geant 4.5.x), while the Java side is AIDA 3.2.1 compliant. From the user's perspective the differences between 3.0 and 3.2.1 are minimal.

Supported Platforms

Binaries are available and supported for the following combinations of architectures and compilers:

• Windows NT/2000/XP
  • WIN32-VC: Visual Studio 6.0 Enterprise Edition, Service Pack 5.
    Microsoft (R) 32-bit C/C++ Optimizing Compiler Version 12.00.8804 for 80x86
  • WIN32-VC7: Visual Studio .NET Professional 2003.
    Microsoft (R) 32-bit C/C++ Optimizing Compiler Version 13.10.3077 for 80x86
• Linux
  • Linux-g++2: gcc version 2.95.3 20010315 (release)
  • Linux-g++3: gcc version 3.2.2
• MacOS X
  • Darwin-g++2: Apple Computer, Inc. version gcc-7, based on gcc version 2.95.2 19991024 (release)
  • Darwin-g++3: Apple Computer, Inc. GCC version 1175, based on gcc version 3.1 20020420 (prerelease)
• SUN Solaris
  • SUN-CC: CC: Sun WorkShop 6 update 1 C++ 5.2 Patch 109508-03 2001/04/07

Major changes in AIDAJNI 3.0.4

• Implementation is almost fully compliant with AIDA 3.0.
• Added aidajni-setup scripts and aida-config utility.
• Distribute shareable libraries for Windows only. Unix has both static and shareable libraries.
• Passed AIDA C++ Test cases.
• Added build scripts for example file.
• Removed some unnecessary include files.

For a full list of changes in AIDAJNI 3.0.4 see the AIDAJNI change log.
For a full list of changes in AIDA 3.0 and AIDA 3.2 see the AIDA change log.

Documentation

These release notes list issues specific to the AIDAJNI implementation of AIDA. In general all of the AIDA documentation applies to AIDAJNI, in particular the following are useful:

C++ (3.0)

• AIDA 3.0 Users' Guide
• AIDA 3.0 API documentation

Java (3.2.1)

• AIDA 3.2.1 Users' Guide
• AIDA 3.2.1 API documentation

License

AIDAJNI is part of the FreeHEP Java Library an "Open Source" library distributed under the terms of the LGPL. If you have questions about the licensing please send a mail to: developers@freehep.org.

Installing AIDAJNI

Download and install a Java AIDA Implementation which supports AIDA 3.2.1, for example JAIDA.

Download AIDAJNI for one or more platforms. These distributions overlay on top of each other, adding support for different architectures. The distribution creates the following directory structure:

AIDAJNI-version            containing license and release notes
AIDAJNI-version/bin        containing platform specific directories with setup scripts
AIDAJNI-version/examples   containing examples
AIDAJNI-version/include    containing all necessary include files
AIDAJNI-version/lib        containing platform specific directories with libraries
                           (shareable and static)

Compilation

The current distributions do not contain source files.

To (re-)build AIDAJNI for a particular platform you need to get AIDAJNI-3.0.4-src.zip or .tar.gz file from the ftp://ftp.slac.stanford.edu/software/freehep/AIDAJNI/v3.0.4/ directory.

Follow the instructions in README-src.html contained in that distribution.

Building an Application with AIDAJNI

Set the environment variable AIDAJNI_HOME to your unpacked AIDAJNI distribution. Make sure JDK_HOME is set to your Java Development Kit (1.4 or better), and source the system specific aidajni-setup file (.sh/.csh fro Unix, .bat for Windows, .win32 for Cygwin).

Example for Linux-g++3, using tcsh:

setenv AIDAJNI_HOME /users/tom/AIDAJNI-3.0.4
setenv JDK_HOME /users/tom/j2dsk1.4.1
source /bin/Linux-g++3/aidajni-setup.csh

Now you are able to execute the aida-config utility:

aida-config --version	will display the version you installed.
aida-config --include 	will display the include options 
                        for your compiler.
aida-config --lib 	will display the library link options 
                        for your linker.

To compile (example for Linux-g++3):

g++ -c `aida-config --include` YourApplication.cc
g++ YourApplication.o `aida-config --lib`

Running an Application with AIDAJNI

Once you have run the aidajni-setup script successfully you can just execute your application.

Using AIDAJNI from Geant4

For Geant4 version 4.5.x JAIDA+AIDAJNI is distributed as an overlay product. This new overlay fixes some bugs in the A01 example and uses the setup and aida-config utilities to compile and link A01 with AIDAJNI.

The overlay is available from ftp://ftp.slac.stanford.edu/software/freehep/AIDAJNI/v3.0.4/

For Geant4 version 4.6.x the fixes to the A01 example and the overlay are included in the Geant4 release. One only needs to install JAIDA and AIDAJNI as described above.

IMPORTANT: Make sure you do not link in OPENGL libraries since they pre-load libXt.so, which will make the JavaVM crash when it tries to open its first Window/Frame. This does NOT apply to the Windows Operating System of course. This bug was reported to Sun Microsystems as early as JDK 1.3.1, but will not be fixed until JDK 1.5 comes out. Bugnumber 4638291

Features/Limitations of the Current Release

The following limitations exist:

• On MacOS X the loading of the AWT library seems to fail. This causes the default Plotter not to work. You need to use the DummyPlotter which is included in the BatchAnalysisFactory. To do so, set the environment variable

  setenv JVM_ARGS "-Dhep.aida.IAnalysisFactory=hep.aida.ref.BatchAnalysisFactory"

  to be able to run without plotting. See AIDAJNI-28.

• On Linux RedHat 9 distribution a program using AIDAJNI will finish with a crash, due to some threading problem in the Linux kernel. You need to set LD_ASSUME_KERNEL 2.4.1 to avoid this crash, until the next kernel is distributed. For more information see AIDAJNI-5 in our bug database.
• There may be memory leaks in some places, but we currently cannot run AIDAJNI through valgrind, since valgrind core dumps on running the Java Virtual Machine.
• Many routines will return references to objects which are ONLY valid until the next
  call to the same routine is made.
• CIxxx.cpp and CIxxx.h classes are currently available for experimental use only. They allow a C++ implementation of an object (Histogram for instance) to be passed to and handled by Java. This will eventually allow a C++ histogram to be plotted by a Java plotter.
• ITree.ls() not implemented because we would need an ostream connected to an java.io.OutputStream.
• ITuple.fill on ITupleEntry is implemented but will not work. To be removed for AIDA C++ 3.2.
• ITuple.getObject() will fail if the stored column is not an ITuple.
• ITree.listObjectNames() and ITree.listObjectTypes() return an empty list in case of failure.
• The distribution kits contain some CVS directories and files, please ignore.

Reporting Bugs

For discussion of features or problems related to AIDAJNI please use the AIDA mailing lists. To report bugs or request enhancements you can also use the AIDAJNI bug database.

Examples

The AIDJNI/examples directory contains AidaTest.cc which serves as a small test as well as an example. The subdirectories g++, CC and VC contain build scripts to compile and link AidaTest.cc into an executable. JAIDA and AIDAJNI must have been set up before running the build script.

The standard AIDATest package in C++ is used to test the AIDAJNI adapter. Some minor tweaks are being made to the tests and the JAIDA implementation so that all of them will pass, but we believe the AIDAJNI does not have major errors in it.