NeXusBeans: beta release including new NeXusBeans Java generator tool

This is the beta release of NeXusBeans, as developed by Dr Darren Kelly from 2005 - 2007 for the Bragg Institute, ANSTO (under project management of NIAC member Dr Nick Hauser, and initially within the Data Analysis Team lead by Paul Hathaway).

Java NeXusBeans bring true Java component engineering, UML graphical engineering, and XML Schema validation (under development) to the NeXus neutron science data format. A prototype of the system was presented to to the NeXus International Advisory Committee (NIAC) in Feb 2006 at Grenoble, France.

The beta release will only be "supported" within the Bragg Institute at ANSTO for trials, and may be subject to frequent change (with post-beta versioning). The planned 1.0 release will be supported by the Bragg Institute for the benefit of the wider NeXus community.

In order to use this release of NeXusBeans you will need:

A modern Java IDE like Netbeans or Eclipse
The au.gov.ansto.bragg.nexus.beta.jar library developed by Darren Kelly, which includes:
- the latest NeXusBeans (converted from Meta-DTD templates streamed directly from the NeXus SVN repository).
- the NeXusBean generator tool that was used to create the NeXusBeans
  (you do not need to use the generator tool to explore the provided NeXusBeans)
The provided jnexus.jar library developed by Mark Koennecke of PSI - only used for access to official NX primitive type definitions. (This is an older version, sufficient for operation of the NeXusBeans system. The latest version - which also requires the Mini-XML libs - can be obtained via the NeXus downloads page, however you are strongly encouraged to use THE OLDER VERSION DISTRIBUTED HERE.)
The au.gov.ansto.bragg.forward.beta.jar library developed by Darren Kelly, for forward engineering of Java via a UML-like metamodel with Java extensions (iff you want to regenerate the NeXusBeans fresh from the NeXus Meta-DTD XML repository using the generator tool).

Notes on this release

The NeXusBeans provided with this release:

Were generated on 2007-04-09 automatically from NeXus XML Meta-DTD template files streamed directly from the NeXus SVN: http://svn.nexusformat.org/definitions/trunk/base_classes/
DO enable representation of NeXus XML templates (a.k.a. Meta-DTDs) as Java beans.
DO enable construction of a NeXus representation of neutron bean instruments and data in Java (as presented at NIAC 2006, and to colleagues and guests at ANSTO).
DO NOT provide notifications from setters. Under Darren Kelly's Bragg base framework (not supplied with this release) that is achieved by an introspective global notification mechanism available by wrapping AND/OR inheritance.
DO NOT yet provide extensive assistance in dimensioning of data items. They simply offer an Object that the user may populate as desired, as it is difficult to interpret NeXus array instructions like 'NX_FLOAT[i,j,?k,?l]' sufficiently generally. This crucial matter is being addressed in the next release.
DO NOT include the JavaBeans serialization technology presented at NIAC 2006. The XStream-based reader/writer system developed by Darren Kelly and student Hugh Rayner (which we customised to meet the NeXus format) will be included in future NeXML tools project releases. This is because the developmental NeXus XStream converter depends on the handling of tricky dimensioned data, which is work in progress.
DO NOT currently include Java annotations to enable hibernation (database persistence using Hibernate). This is planned for future releases, and will be incorporated as an option in the next version of the NeXusBean generation tool.

The base package is only partially documented, as there are still many issues concerning handling of dimensioned data. The UML overview of the base package is out-of-date, yet nevertheless quite informative.

The metamodel-driven Java forward-engineering system is extensively documented in UML, and will be released as a separate educational demonstration project for the Magicdraw UML tool.

How to generate fresh NeXusBeans using the provided tool

The class NeXusXmlTemplateToNeXusBean_ generates NeXusBeans from remote NeXus SVN repository of XML Meta-DTD templates to a project base directory of your choice. The base directory for project output must already exist, and so must all directories under it with the following deliberately fixed structure reflecting the enforced Bragg Institute package structure:

$base/src/au/gov/ansto/bragg/nexus/auto

The current policy is to deliberately NOT create the directory structure for you, automatically in the tool, you must create it by hand first !

To execute from the command line use:

java au.gov.ansto.bragg.nexus.tool.NeXusXmlTemplateToNeXusBean_ $base

Where $base is something like:

/home/somebody/project/nexus/

You must have the following libraries in your classpath (or versioned equivalents):

au.gov.ansto.bragg.forward.beta.jar (supplied with this release)
au.gov.ansto.bragg.nexus.beta.jar (this release)
jnexus.jar (please use the out-of-date version supplied with this release)
dom4j.jar (version 1.6.1 or greater)

In order to compile and use the generated NeXusBeans you will then need only:

au.gov.ansto.bragg.nexus.beta.jar (this release)
jnexus.jar (please use the out-of-date version supplied with this release)

Please BEWARE that if you have the distributed NeXusBeans in au.gov.ansto.bragg.nexus.auto AND your newly generated and compiled NeXusBeans in au.gov.ansto.bragg.nexus.auto with the same packaging on the same classpath you WILL get a strange clash.