devNote d061101  info.odma.odmjni100 Java-OdmNative Bridge KnownDocument: 0.57beta Integration

ODMdev>devNotes> 2006>11> d061101m> 0.04 2008-04-23 21:12 -0700

• Latest version: The latest info.odma.odmjni100 material can be found via   <http://ODMA.info/dev/devNotes/2006/11/d061101b.htm>.
• Previous version: tbd [the material has not been archived in this folio yet]
• Next Version: Runtime Packaging: 0.58beta (under development) <http://ODMA.info/dev/devNotes/2006/11/d061101n.htm>
           
• This page:  0.04 KnownDocument: 0.57beta Integration <http://ODMA.info/dev/devNotes/2006/11/d061101m.htm>. 
• Downloads:
  • d061101m.txt: 0.00 Manifest for the 0.57beta archive, 10,031 byte file dated 2007-03-11-23:21
  • d061101m-odmjni100-0.57beta.zip: 0.00 archive, 117,165 byte file dated 2007-03-11-23:22.  Review the manifest to determine whether it is worthwhile to download the Zip archive.

Synopsis

{Author Note: this is a placeholder for the 0.57beta Integration.}

1. Objectives

The ODMJNI 1.0 0.57beta distribution is an abbreviated release to provide a functioning OmdConnection.openKnownDocument implementation.   This is intended to be the least that can possibly work and defend the ODMA Connection Manager and DMS integrations from defective ODMA Document IDs. 

2. Change Summary

This version of the info.odma.odmjni100 package introduces the openKnownDocument implementation for use along with an updated practical100 0.56beta drop:

1. A jniKnownDocument static native method is added to OdmJniApp.java.  This implementation is equivalent to the chooseDocument method, except that the docId to use is supplied as a parameter.
      
2. The OdmJniApp.openKnownDocument method is added to use jniKnownDocument and, depending on success, establish an OdjJniWork implementation or return a null OdmWorkingDocument implementation.
      
3. The openKnownDocument implementation uses a revised wfDocId verification to defend against submitting defective ODMA Document IDs to the ODMA Connection Manager and DMS implementations.
       
4. The OdmJniApp provides additional filtering to ensure that the submitted docId parameter is translatable to the single byte character code of the default Windows ANSI code page.
      
5. There will be simple testing with a version of CheckChoice that is converted to CheckKnown.java and used to verify the ability to open with manually-entered Document IDs and also ones retained from a CheckChoice.
       
6. Minimal packaging of this odmjni100 0.57beta, along with an updated 0.56beta practical100, provides early confirmation and experience with openKnownDocument.

3. Developer Notes: Working toward 0.57beta

• 2007-03-05: Define Additional 0.57beta Drop.  After communication with the Java-application developer, it is clear that I seriously misjudged the importance of openKnownDocument in the usage scenario.  Not only is this desired as a way to select documents from the recent-documents list of the application, it is important as a way for a DMS such as GroupWise to be able to launch an application with a selected document as a parameter.  I didn't expect the first case to be urgent, and I had completely overlooked the second.
    
  Some e-mail proposals were submitted on how to prioritize a quick solution and then this additional step on the way to 0.57beta was started without waiting for confirmation.  The idea is that 0.58beta will be used for the implementation of full verification of parameters, and some coverage tests on OmdFormat.  The 0.58beta will involve use of native implementations of the filters from the same library of native code used in odmjni100 (once Native100 is also updated).  This will avoid problems of different verifications being used at different levels of the ODMJNI implementation "stack," subjecting users to inexplicable gap cases whenever the native methods silently fail on a parameter that was accepted by OdmFormat and ODMJNI method.
    
  Because the native verification can check the actual conversion to the default ANSI Code page, the current implementation of OdmFormat cannot match that.   Although the 0.56beta implementation of OdmFormat will be replaced by one that reduces the gap, the gap will not be closed in 0.57beta.  That will happen in 0.58beta later [updated 2007-03-11].
      
  The basic idea is as follows:
     
  • [updated 2007-03-11] For 0.57beta, openKnownDocument will throw an OdmError exception for any docId parameter that does not satisfy OdmFormat.wfDocId(docId).  Even when a Document ID is accepted by wfDocId, openKnownDocument can report failure (but not throw an exception) if the submitted docId does not translate perfectly to the current Windows ANSI code page or if the translated result exceeds the maximum length allowed for Document ID character sequences.  In 0.57beta, openKnownDocument can also fail if there is no default DMS, the Document ID is for a DMS that is not available to the application, or the Document ID is not recognized by the DMS that appears to have issued it.  openKnownDocument will always fail if the specified document is already opened and available in an existing OdmWorkingDocument interface.
      
  • [updated 2007-03-11] The 0.56beta package has been re-issued to have OdmFormat.wfDocId work properly for the above case.  The latest 0.56beta release should always be used until both it and 0.57beta are declared obsolete.
        
  • Later, wfDocId can be tightened to match the native filtering, performing a code translation and check of the translated length.  Then the exception can be thrown under exactly the conditions where the native code will fail its equivalent of the openKnownDocument request.  But there will be no unchecked OdmError exception for anything that there is not an OdmFormat check for first.
       
• 2007-03-18: Move on to Redefined 0.58beta.  The remaining steps to 0.60beta are adjusted.  The completion of format checking and elimination of any gaps is now defined to occur in 0.59beta.   Under no conditions do we want gaps remaining by the time of the 0.60beta public release.

Revision History:

 

0.04 2007-03-18-18:58 Connect 0.58beta

An initial link to the 0.58beta page is added for notification of the work that is underway.  Any impact by the adjusted progression is also reflected in the narrative.

0.03 2007-03-11-23:54 Reflect completion of 0.57beta

0.02 2007-03-05-18:18 Add structure used for 0.56beta

The practical100 0.56beta account at d061001g is used as a boilerplate for this one too.

0.01 2007-03-05-17:24 Change to 0.57beta placeholder

The 0.56beta drop only involved the practical100 package.  However, it is desirable to accelerate availability of openKnownDocument and this slot is being taken for that.

0.00 2007-02-24-18:41 Provide Placeholder for Material

Create placeholder that will be populated with information as the 0.56beta regression tests are performed.

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

created 2007-02-24-18:41 -0800 (pst) by orcmid $$Author: Orcmid $ $$Date: 08-04-23 21:12 $ $$Revision: 38 $