
  O p e n O R B  n a t i v e


  What is it?
  -----------

  This native package provides a collection of native libraries
  that are used by OpenORB to achieve tasks that are currently
  not possible to achieve in pure Java. This project has been
  started because of bugs in VMs that made the various methods 
  inaccessible. In such cases this set of native libraries can
  be used to circumvent the problem until the bug has been fixed.

  The problem in RMI-IIOP marshaling is that classes with
  final members must be read from the IIOP stream and restored
  into a Java instance of the class. When the class type is read
  an instance must be created. At this time the members are yet
  to be read from the stream. That leads to the situation that
  you have to assign a value from a final member to an already
  instantiated class. This is not allowed within Java. For this
  to work you need to enter the JNI level, create an empty hull
  of a Java class with AllocateObject() and assign the members
  via setXYZField() functions. This functionality is provided
  by each VM that supports RMI-IIOP, but unfortunately those
  methods are not in a public API, allowing a VM vendor to change
  the internal API from version to version.
  In order to keep OpenORB a pure Java CORBA ORB we need to get
  access to these internal methods via reflection. The challenge
  is to adapt the DeserializationKernel classes so that a new
  VM can be supported.
  Due to beforementioned bugs in VMs it became obvious that we
  need a native fallback solution for those cases when the
  reflection approach does not work.

  For a list of currently supported VMs please check the Javadoc
  for the interface org.openorb.orb.rmi.DeserializationKernel.

  So when you are facing marshaling troubles when using RMI-IIOP 
  you should give this set of native libraries a try.


  Build
  -----

  The native module must be at the same level as all the other
  modules.

    CURRENT_DIR
      ./OpenORB
      ./NotificationService
      ...
      ./native
      ...

  In order to build one of the modules, just change into the native
  folder and call ./build.sh or ./build.bat.
  From this location the build scipts assume that the tools module
  can be found in "../tools".


  The Latest Version
  ------------------

  Details of the latest version can be found on the SourceForge
  Project web site <http://openorb.sf.net/>.


  Documentation
  -------------

  Use the checkLibrary script to find out whether marshalling will
  work for you. This script tries to access the necessary methods
  via reflection. If during the execution of the program any reports
  are reported then you can use the testLibrary script to check
  whether the problem can be solved by using the native library.
  When you decide to use the library you need to check whether a
  library for your platform has already been compiled. Just look
  into the jar file in the lib folder to see whether the combination
  of your operating system and architecture is present.
  When you find the library you can just execute

      ./build.sh install-library 

  This extracts the library from the jar file and places it into
  the path specified by install.path (see local.properties). The
  default location is the lib folder of this module.
  If no appropriate library was found you need to compile it
  yourself. We are using the Ant Cpptask extension for the build
  process. It uses a gcc compiler which should be available for
  most platforms out there. When you manage to compile a library
  it is automatically updated into openorb_native-x.y.z.jar.
  Please send us the jar file containing the library for the new
  OS/architecture so that we can it to CVS and other users can
  benefit from you contribution.


  Licensing
  ---------

  This software is licensed under the terms you may find in the file
  named "LICENSE.txt". See the file LICENSE.txt in the lib filder for
  license information on the third party software delivered by this
  package.


  Thanks for using OpenORB native.

                                         The Community OpenORB Project
                                            <http://openorb.sf.net/>



