devNote d061003 ODMJNI 1.0 OdmNative100 ODMA-Access Implementation

ODMdev>devNotes> 2006>10> d061003> 0.05 2008-04-23 21:12 -0700

{Preliminary Material.}

1. Overview

OdmNative100 is a Microsoft native Windows C++ class.  This class, its IodmNative100 interface, and related helper classes and interfaces are used in the odmjni100.dll to manage the lifetime of an ODMA connection and all subordinate document-access objects that will arise from it.

Although OdmNative100 is useful in other implementations of access to ODMA on the Windows desktop platform, initial development is skewed to the specific needs of ODMJNI and the info.odma.odmjni100 package.  Generalization for reuse in other ODMA integration situations will be considered later.

Initial development of OdmNative100 satisfies Critical First Steps 3.2, Confirm ODMA Connection from C++ Class, in the ODMJNI 1.0 Development Progression.

OdmNative100 delivers a Microsoft Component Object Model (COM) binary interface.  This allows the connection from Java-implemented ODMJNI classes to be managed with a single interface pointer disguised as a Java long data value. Using the reference-counting and interface versioning procedures of COM provides an easy way to correctly synchronize OdmNative100 instance lifecycles with the lifecycle of the Java classes that use OdmNative100 in the JNI implementations of their native methods.

Although IodmNative100 is a COM binary interface, it is only used internal to odmjni100.dll and the Java classes that rely on those DLLs.  There is no independent COM object provided by or visible outside of ODMJNI.  This is an important feature of the way that ODMA connection provide in-process, in-thread binding between Windows desktop applications and ODMA-compliant Document Management System integrations.  In the case of ODMJNI, the Windows desktop application is Java-based.

2. Progression

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

• practical100 Pure Java: The Java info.odma.practical100 package of interfaces and null connections.  These provide a neutral set of interfaces and classes for use by an ODMA-aware Java-based desktop application.
    

• OdmNative100 Native Windows: The C/C++ native Windows implementation of OdmNative100 classes and interfaces that provide the native Windows code for coordinated use of the ODMA Connection Manager and the ODMA-compliant DMSs that reached via the connection manager.   Instances of these classes are are implemented by the odmjni100.dll that implements Java Native Interface (JNI) operations for Java applications.
    

• 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.

Following initial setup, OdmNative100 is evolved in synchronization with stages of the practical100 interfaces and the odmjni100 classes that bridge between the practical100 interfaces and the OdmNative100 implementation.

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.

2.1 Setup Stages

These are the preparatory stages for ensuring a reproducible development setup for OdmNative100 work.

• Setup00: VC++ Command Line.  Configure for command-line use of the Microsoft VC++ 2005 compiler.
    

• Setup01: PSDK Command Line.  Configure for command-line use of the Microsoft Platform SDK in building native C/C++ code that relies on the Windows API.  The setup test demonstrates loading of the ODMA Connection Manager DLL.  The small program can be used to verify that the ODMA Connection Manager is properly installed.
    

• Setup02: Default DMS Access.  Dynamic C Language access to functions of the ODMA Connection Manager is confirmed.  The small program can be used to verify that the ODMA Connection Manager is present and whether there is a default DMS for the special Application ID OdmNativeTest.
    

• Setup03: DMS Dialog.  Dynamic C Language initiation of an ODMA DMS dialog is confirmed.  This program resolves a critical feasibility question, demonstrating whether an ODMA DMS can produce dialogs when a parent window is nonexistent or unknown.  This small program is useful for testing whether a given ODMA DMS is able to produce its dialogs successfully under those conditions.  The TestSetup03 program can be used for confirming whether this is true for an ODMA DMS that is to be accessed from Java-based applications via ODMJNI.
     

• Setup04: 0.20alpha OdmNative100 Integration.  This exercise creates and exercises a complete internal COM object and delivers its interface.  The IodmApplication100 interface delivers the functionality exercised in Setup02 and Setup03, with improved handling of the ODMA SelectDoc function.  This implementation supports selection of a document but has no provision for opening the document for use by the ODMA application.  It is sufficient for the first end-to-end 0.20alpha ODMJNI 1.0 integration.

2.2 Feature Progression

The basic structure is confirmed.  The next stages are for progressive addition of features until the essential functionality for ODMJNI 1.0 is covered.

• Check05: 0.26alpha Regression Check.  In setting up for feature introduction, a new confirmation program was derived from Setup04.  The regression check is to confirm that nothing that worked for Setup04 has been broken.  There is also a modification of the OdmNative implementation designed to find the calling application's main Window more reliably.
     

• Check05: 0.30alpha OdmNative Integration.  This stage creates the IodmWorking100 interface to implementations of working documents.  This provides all functionality required of Working Documents for ODMJNI 1.0, although those methods that are not required for 0.30alpha are represented by null implementations to be replaced by more-active versions on the progression to 0.50beta.  The Check05 program is expanded to demonstrate operation of the 0.30alpha functionality.  This is a breaking change to the OdmNative interfaces and implementations.

Available Material

• d061003b: OdmNative100 Implementation [latest]
• d061003i: Check05: 0.30alpha Integration
• d061003h: Check05: 0.26alpha Regression
• d061003g: Setup04: 0.20alpha OdmNative Integration
• d061003e: Setup02: Default DMS Access
• d061003d: Setup01: PSDK Command Line
• d061003c: Setup00: VC++ Command Line

• d061003a: Diary & Job Jar

see also:

     p061001d: Development Progression: 0.20 Critical First Steps.  ODMJNI 1.0 Java-ODMA Reference Integration project document, 2006-10-26.

 

Revision History:

0.05 2007-01-03-16:34 Update to 0.30alpha Integration

The description of the progression, and link to materials, is updated to reflect the status as of completion of the 0.30alpha integration level of OdmNative100.

0.04 2006-12-20-17:55 Include d061003h 0.26alpha Regression

0.03 2006-11-28-14:19 Include Setup02 Material

The Setup04 material was added previously, but not noted with revision of this page.

0.02 2006-11-08-15:45 Connect to Setup01 Material

0.01 2006-11-05-17:42 Change Title and Expand Preliminary Material

Provide more context and description of the available Setup cases.  Link in the available Setup00 material.

0.00 2006-10-27-15:23 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-10-27-15:23 -0700 (pdt) by orcmid $$Author: Orcmid $ $$Date: 08-04-23 21:12 $ $$Revision: 75 $