AIDAJNI

AIDAJNI 3.2.2 Release Notes

Release Notes Version: : 1.12 $.

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.2.2
• 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++ and Java side are both AIDA 3.2.1 compliant (for usage in Geant 4.6.x).

Supported Platforms

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

• Windows NT/2000/XP
  • WIN32-VC7: Visual Studio .NET Professional 2003.
    Microsoft (R) 32-bit C/C++ Optimizing Compiler Version 13.10.3077 for 80x86
  • WIN32-g++: gcc version 3.3.1 (cygming special)
    Using a cygwin shell.
• Linux Red Hat Linux 7.2 (Enigma) 2.4.20-30.7.legacysmp (2x1396MHz Intel)
  • Linux-g++2: gcc version 2.95.3 20010315 (release)
• Linux Red Hat Linux release 9 (Shrike) 2.4.20-31.9 (1x996MHz PIII)
  • Linux-g++: gcc version 3.2.2 20030222 (Red Hat Linux 3.2.2-5)
  • Linux-icc: Intel(R) C++ Compiler for 32-bit applications, Version 8.0 Build 20031231Z Package ID: l_cc_pc_8.0.058
• MacOS X 10.3
  • Darwin-g++: gcc version 3.3 20030304 (Apple Computer, Inc. build 1495)
• SUN Solaris
  • SUN-CC: CC: Forte Developer 7 C++ 5.4 Patch 111715-13 2003/12/11

Major changes in AIDAJNI 3.2.2

Bug

• [AIDAJNI-37] - Problem with npos type in JITupleFactory.cc on Linux-AMD 64
• [AIDAJNI-39] - Interoperability of JAIDA with PI seems to fail
• [AIDAJNI-40] - tree.commit() does not report errors
• [AIDAJNI-41] - Reuse of wrappers does not work if same CREF is used for new type of C++ object
• [AIDAJNI-43] - FATAL error for ID lookup when plotting DataPointSet

New Feature

• [AIDAJNI-42] - Plotting of functions

Improvement

• [AIDAJNI-38] - Sources should be in native format for different platforms

For a full list of changes in AIDAJNI 3.2.2 see the AIDAJNI change log.
For a full list of changes in AIDA 3.2.1 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:

• 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.2.2-src.zip or .tar.gz file from the ftp://ftp.slac.stanford.edu/software/freehep/AIDAJNI/v3.2.2/ 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++, using tcsh:

setenv AIDAJNI_HOME /users/tom/AIDAJNI-3.2.2
setenv JDK_HOME /users/tom/j2sdk1.4.1
source /bin/Linux-g++/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++):

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 use AIDAJNI 3.0.4 and its Geant4 overlay product. See ReleaseNotes of version 3.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, but 1.5beta does not seem to have it fixed yet. Bugnumber 4638291

Features/Limitations of the Current Release

The following limitations exist:

• On MacOS X there are some complications running the GUI parts of AIDAJNI (Plotter, ...). The problem is that non-bundled applications on MacOS X, such as AIDAJNI, cannot by default interact with the user or open any GUI windows. To overcome this problem there are a number of undocumented (Apple) calls one can do. However it also turns out that one needs to also start Java in the "correct" thread. This all is undocumented by Apple, so there is no easy programmatic way out. Our solution is the following:
  • If you only use the non-GUI parts of AIDAJNI, there should be no problems and you can just compile, link and run your program with AIDAJNI.
  • If you use the GUI parts of AIDAJNI we run your C++ program from Java. This makes sure that the Apple JavaVM will be initialized correctly, on the right thread and as a GUI application. When your program calls AIDAJNI, we will search (and find) the JavaVM which was already started and use that to handle calls to JAIDA. To do so, you application should not be linked into an executable but into a shared library with a statement similar to the following:
    
    g++ -dynamiclib -flatnamespace -o libYourApplicationName.jnilib /lib/Darwin-g++/runs.o ...
    
    You then need to set up the DYLD_LIBRARY_PATH to point to this shared library:
    
    export DYLD_LIBRARY_PATH=/usr/home/duns/YourApplicationsDirectory:
    
    And can then start you application with the command:
    
    java runs YourApplicationName
    
    runs.class implements the small java wrapper around your application.
    
    In future releases of MacOS X this problem may be fixed by apple and this solution will not be needed anymore.
    For more information 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 allows a C++ histogram to be plotted by a Java plotter. Current concrete CI classes do NOT include: CIEvaluator, CIFilter, CIFitData, CIFitParameterSettings, CIFitResult, CIFitter, CIFunctionCatalog, CIPlotter, CIPlotterRegion, and all the Factories. Only classes for which CI classes exist can be passed from C++ to Java.
• ITree.ls() is not implemented because we would need an ostream connected to an java.io.OutputStream.
• ITuple.fill on ITupleEntry is implemented but will not work.
• 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 forum. 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.