devNote d061101 info.odma.odmjni100 Java-OdmNative Bridge

ODMdev>devNotes> 2006>11> d061101> 0.06 2008-04-23 21:12 -0700

{Preliminary Material.  Recast this and move the progression information somewhere else, or include it in the individual pages where it comes into play.  The is material might be better included in the deployment treatment and in project documents also.}

1. Overview

ODMJNI 1.0 is developed via evolutionary prototyping of components along multiple tracks:

• practical100 Pure Java: The Java info.odma.practical100 package of interfaces and null connections.
    

• OdmNative100 Native Windows: The C/C++ native Windows implementation of OdmNative100 classes and interfaces that provide coordinated use of the ODMA Connection Manager and the ODMA-compliant DMSs that are reached via the connection manager.
    

• This Material: odmjni100 Java with odmjni100.dll JNI: The Java and C/C++ implementation of the Java info.odma.odmjni100 package and the odmjni100.dll that provides native implementations for the native methods of the package classes.

  • The odmjni100 package is developed in Java.  It makes use of and enhances the practical100 components.   The odmjni100 classes and implementations of practical100 interfaces are used from Java applications.
      

  • The odmjni100.dll provides native implementations for some private methods of odmnji100.  Functions in the DLL are used by the Java virtual machine to obtain those implementations.  The implementations satisfy the Java Native Interface (JNI) protocol for native methods.  The odmnji100.dll functions make use of OdmNative100 classes and interfaces.  The DLL is implemented in Visual C++ and is only meant to be used by the Java Virtual Machine operating on Win32 i86 platforms running Windows 2000 or later. 
        

• ODMJNI 1.0 Packaging: A separate activity that brings together the run-time redistributable, the Java development package, and the ODMJNI source code and test utilities in a layered set of packages for deployment to developers and with applications to their adopters.

In the evolution on each track, there are both free-standing and integrated confirmation tests.  The results of the free-standing tests are designed to establish that there is a worked solution that the integrated case should be verifiable against.

The major integration and coordination effort involves odmjni100, where all tracks come together.  Here is the greatest need for careful synchronization.  The odmjni100 progression is constrained by the current levels of practical100.  The needs of odmjni100 introduce requirements for new levels of OdmNative100.

2. Progression

info.odma.odmjni100 is a Java package of classes that deliver ODMA-aware operations to applications via the info.odma.practical100 interfaces:

1. The odmjni100 classes use private native methods and the Java Native Interface (JNI) to access native Windows and ODMA functions.
     
The implementations of the native methods are provided by the odmjni100.dll Dynamic-Link Library (DLL).
  
3. Functions implemented in odmjni100.dll construct instances of OdmNative100 objects and their IodmNative100 interfaces.
     
4. The odmjni100 classes implement their practical100 ODMA-aware operations by requests to IodmNative100 methods.  These requests are via native odmjni100 "helper" methods.
     
5. The linkage between odmjni100 methods and IodmNative100 methods is by retaining pointers to the IodmNative100 interfaces in the odmjni100 objects.  These pointers are disguised as Java long values.
     
6. odmjni100 classes are designed to hold onto those disguised pointer values so long as any native helper method might be called. 
      
7. IodmNative100 operations are obtained by passing the disguised interface pointer to each native helper method as one of the parameters.  The native helper method's implementation in odmjni100.dll uses the passed-back pointer to find the IodmNative100 interface that was created for the odmjni100 object to use (3, above).
     
8. When the odmjni100 object releases its resources, no later than finalization, it uses helper methods to release all IodmNative100 interfaces being held, setting the Java long values back to 0 to signify that no interface is being held.  Any subsequent access to odmjni100 native helper methods of the object will result in null responses. 

In this manner, the lifetime of resources held by OdmNative100 objects is synchronized with the lifetime and usage of the odmjni100 objects.  The retention of odmjni100.dll in computer memory is managed by the Java Virtual Machine.

3. References and Resources

Liang, Sheng.

The Java Native Interface: Programmer's Guide and Specification.  Addison-Wesley (Reading, MA: 1999).  ISBN 0-201-32577-2 pbk.  Available at <http://java.sun.com/docs/books/jni/> with different electronic editions and downloadable examples.  The HTML version pages are dated 2002-03-07. Accessed 2006-11-11.
    

Sun Microsystems.

Java Native Interface Tips.  Web page, updated 1999 December 2.  Available at <http://java.sun.com/products/jdk/faq/jnifaq.html>.  Accessed 2006-11-11.
   

Sun Microsystems.

Java Native Interface 5.0 Specification.  Undated on-line document.  Available at <http://java.sun.com/j2se/1.5.0/docs/guide/jni/spec/jniTOC.html>.  This document, as of 2005-08-26, is also available in the 2005-11-18 jdk_1.5.0_doc.zip download of the J2SE (TM) Development Kit Documentation 5.0 (English) available via <http://java.sun.com/javase/downloads/index.jsp>.  Accessed 2006-09-08.

4. Available Material

• d061101b: odmjni100 Implementation [latest]
• d061101o: 0.59beta Transition Candidate Implementation
• d061101n: Runtime Packaging: 0.58beta Integration
• d061101m: KnownDocument: 0.57beta Regression
• d061101k: CodePages: 0.54beta Integration
• d061101j: CheckSwing: 0.52beta Integration
• d061101i: Check04: 0.50beta Integration
• d061101h: Check03: 0.40alpha Integration
• d061101g: Check03: 0.30alpha Integration
• d061101f: Check03: 0.25alpha Integration
• d061101e: Setup02: 0.20alpha Integration
• d061101d: Setup01: JNI Master Cases
• d061101c: Setup00: The JNI "Hello World"

• d061101a: Diary & Job Jar

• see also:
  • d061001: info.odma.practical100 Component Development
  • d061003: ODMJNI 1.0 OdmNative100 ODMA-Access Implementation
  • d070901: ODMJNI 1.0 Packaging
  • d061201: ODMJNI 1.0 Deployment
  • d071001: ODMJNI 1.0 Confirmation Tests
  • d070701: ODMJNI 1.0 Public Beta
  • p061001d: Development Progression: 0.20 Critical First Steps.  ODMJNI 1.0 Java-ODMA Reference Integration project document, 2006-10-26.

Revision History:

0.06 2007-12-01-13:48 Added Link to Confirmation Tests

0.05 2007-09-25-13:55 Reflect Initiation of 0.59beta

The 0.59beta Integration is introduced and the text and links are revised to tie directly to the related developments and the separate packaging project.

0.04 2007-03-05-17:30 Correct the placeholders for the substitution of 0.57beta for 0.56beta

This is done to accelerate availability of an openKnownDocument implementation for testing with the Java application

0.03 2007-02-24-18:13 Update with placeholders for the progression through 0.58beta.

0.02 2006-12-20-19:03 Link to 0.300.25alpha Integration

This page is badly in need of repaving.  Later.

0.01 2006-11-26-14:55 Complete Summary

Provide basic sketch and context and be a placeholder for tying in the code drops on further pages.

0.00 2006-11-09-13:48 create placeholder to morph into the necessary material

Incorporate job jar and use it to drive the completion of essential items here, providing an initial skeleton for more content.  The first objective is creating a jobjar and placeholder pages to be used while the component is taken through critical feasibility tests.

You are navigating ODMdev. This work is licensed under a Creative Commons Attribution 2.5 License.

created 2006-11-09-13:48 -0800 (pst) by orcmid $$Author: Orcmid $ $$Date: 08-04-23 21:12 $ $$Revision: 78 $