ODMdev: ActiveODMA Development Framework

devNote d061101
 info.odma.odmjni100 Java-OdmNative Bridge
0.59beta Transition Candidate Implementation


0.14 2008-03-30 17:44 -0700


The 0.59 Public Transition Candidate is a complete release in which deprecated interface elements and replacement interface elements are present together.  There are breaking changes around parameter-validation and exception-generation behavior.  Later transition to the 0.60 Stable Candidate is accomplished by removing all deprecated elements and discarding those regression sets that have any dependency on deprecated elements.  The resulting clean interfaces are to be preserved hereafter in all ODMJNI 1.0 releases.

For odmjni100, the changes consist of marking elements as deprecated, adding the notChangeable implementation to both OdmJniView and OdmJniWork, and conforming to the changes made in practical100 for 0.59.   The revisions have been kept straightforward, making the least changes necessary to prepare for finalization with release 0.60.  All of the Java classes in odmjni100 are updated: OdmJniApp, OdmJniBind, OdmJniPend, OdmJniView, and OdmJniWork.  Of these, only OdmJniBind is ever used directly by an ODMA-aware Java-based application.

Because odmjni100 0.59 involves both deprecated, new, and re-organized elements, it is only compatible with practical100 0.59.   It cannot be operated properly with earlier or later versions of practical100 (and vice versa).

One of the challenges is arriving at regression sets that apply to the 0.59 interfaces and earlier along with regression sets that have no dependency on deprecated elements and apply to the 0.59/0.60 interfaces and later.  Improvements in test automation and test coverage are deferred to release 0.60 or later in order to accelerate availability of the public beta release.

1. Description
2. Bugs and Caveats
    2.1 OdmFormatCheck Implementation is the 0.59 practical100 null Implementation
    2.2 viewOnly null Behavior Changed
    2.3 Ambiguous transferToNewDocument Operation
    2.4 Inadequate Confirmation Test Coverage
    2.5 Undocumented Dependency on ODMASAMP Integration and Odma32 Logging
    2.6 All ODMJNI Interfaces Must Be Explicitly Released
    2.7 Do Not Perform ODMJNI Requests on the Java GUI Thread
    2.8 Do Not Multi-Thread ODMJNI Requests
    2.9 Do Not Create Multiple Overlapping ODMJNI Sessions
    2.10 Code Page Inconsistencies Can Corrupt Strings from ODMJNI
    2.11 Maintain GUI appWindow While ODMA Dialogs Are Possible
    2.12 Conservative Format Checks May Be Too Strict
3. Changes to odmjni100 in 0.59beta
    3.1 Organization of Pre-0.59 Regression Tests
    3.2 Remove Parameter-Format Exceptions
    3.3 Implement formatCheck Return of OdmFormatCheck Interfaces
    3.4 Implement Refactoring of Metadata and Document Interface Implementations
    3.5 Refactor Regression Sets
4. Development
    4.1 Outline the Development
    4.2 Freeze odmjni100 0.58 Regression Tests
    4.3 Change odmjni100 Implementation Classes for 0.59
    4.4 Confirm Pre-0.59 Regression Checks
    4.5 Develop odmjni100 0.59/0.60 Regression Tests
    4.6 Package odmjni100 0.59beta Material
    4.7 Final Packaging
5. Developer Notes: Working toward 0.59beta

1. Description

The general approach and results are on the same pattern as for the practical100 interfaces and null implementations that odmjni100 depends upon.  The information is repeated here for completeness.

see also:
d070701d: ODMJNI 1.0 Public Beta 0.59 Transition Candidate
d061001h: info.odma.practical100 0.59beta Transition Candidate

1.1 This 0.59beta stage introduces all odmjni100 changes that are visible to applications.  In 0.60beta and beyond, only those interface elements that are permanent features of ODMJNI 1.0 are preserved.  Elements identified as deprecated in 0.59beta will be removed in 0.60beta.

1.2 With the exception of those changes that eliminate exceptions from format-checking, programs that rely on the 0.58beta level will not see any changes in operation with 0.59beta.  It is unlikely that any existing code will notice this change.

1.3 The preservation of both deprecated interface elements and their replacements is a convenience to developers who have relied upon the 0.58beta release.  Using 0.59beta, developers can take small incremental steps to replace use of deprecated elements with  use of the corresponding replacement.   Compiling with 0.60beta later will serve as a check that all dependencies on deprecated elements have been removed.

1.4 To support evolution toward automated confirmation and regression tests, two regression sets are built as part of 0.59beta:

2. Bugs and Caveats

2.1 OdmFormatCheck Implementation is the 0.59 practical100 null implementation

2.1.1 The OdmFormatCheck interface implemented by odmjni100 0.59 is the same one provided as the practical100 0.59 "null" implementation. 

2.1.2 There is no attempt, in 0.59, to use exactly the same checking that is used in OdmNative100 as part of its defense against ill-formed string-valued parameters.  Although the format requirements are close, agreement is not thoroughly tested for 0.59.

2.1.3 It is possible that a request might fail because a parameter is unacceptable at the OdmNative100 or DMS Integration layer, even though the offending parameter successfully passes an OdmFormatCheck filter.  There is no programmatic way to determine that such a case has arisen.

2.1.4 It is also possible that an OdmFormatCheck and/or a request may fail even though the string-valued parameter was obtained as the result of an earlier request.  It is conceivable that a request could return DMS-provided values that are not accepted as input by OdmFormatCheck and the internal checks in the odmjni100 implementation.  (Cf. section 2.12.)

2.1.5 The long-term remedy is for odmjni100 and OdmNative100 to share a common-code implementation of checks for string-valued parameters.  This is planned for ODMJNI 1.0 release 0.80.  The technical conditions for having common code will not be satisfied until then. 

2.1.6 If this becomes a problem between release 0.60 and release 0.80, an interim solution will be considered.

2.2 viewOnly Null Behavior Changed

2.2.1 The viewOnly method of null-response document interfaces now always returns true.

2.2.2 This change is required by the same breaking change in the practical100 0.59 interface definitions.

2.2.3 The workaround is to locate all use of viewOnly and substitute use of notChangeable when upgrading and testing with 0.59.  Verify that the null-behavior is dealt with properly wherever it can occur.  viewOnly will be removed in 0.60.

2.3 Ambiguous transferToNewDocument Implementation

2.3.1 It is possible for an DMS integration to respond to a transferToNewDocument request with an internal-to-ODMJNI indication that a new document is not created and the original document should be used. 

2.3.2 This case is ambiguous in any odmjni100 release, including 0.59.  The response is a null implementation with operationCancelled set.  The user needs to be consulted to determine whether a save (commitChanges) is desired.  Along with the prospect of a "stuck cancel" condition, this response is too confusing.  

2.3.3 Workaround: The failure and operationCancelled null responses from transferToNewDocument should be treated the same.  The user should be advised that the operation was unsuccessful and offered the opportunity to save the document, either to the DMS or locally.

2.4 Inadequate Confirmation Test Coverage

2.4.1 The tests used to confirm operation of odmjni100 are very weak.  Coverage is poor.  They are also clumsy to use, with considerable manual activity required.  It is better than not having them, but the approach does not scale.

2.4.2 Although the code has been reviewed many times, and there is general stability, this is still beta quality software.  There is no measurable basis for high confidence.

2.4.3 No immediate relief: Improved testing operation and automatic operation will be developed after release 0.60 as part of the development toward 0.90 (hardening).  All tests will be made available as they are developed, independent of other release cycles.

2.5 Undocumented Dependency on ODMASAMP Integration and Odma32 Logging

2.5.1 The regression checks and field confirmations are all performed with the ODMA 2.0 Connection Manager with logging active.  There is little documentation on how to accomplish this and how to interpret the logs.  The development of this documentation is expected in the course of 0.70 (deployment) development.

2.5.2 The current regression checks and the sample results are obtained using the ODMASAMP Sample DMS integration from the ODMA 2.0 SDK.  Installation, use, and carrying out tests with this sample is not documented.  The development of this documentation and any supplementary materials is also expected during the 0.70 (deployment) development.

2.6 All ODMJNI Interfaces Must Be Explicitly Released

2.6.1 By default, the Java Virtual Machine (JVM) does not execute finalizers for those objects that remain alive when an application is terminating. 

2.6.2 The ODMJNI interface implementations coordinate resources with ODMA and the DMS integration.  In order for those resources to be properly released and the ODMA session to be terminated successfully, all interface implementations must either be finalized or have their release operations performed when they are no longer usable, especially before the application terminates.

2.6.3 Confirmation: If the ODMA32 2.0 log for an application's session with ODMA has an entry for a successful OdmRegisterApp operation and no OdmUnRegisterApp termination entry is produced, there are one or more interfaces to ODMJNI implementations that were not released by the time of application termination.   This can be verified by performing the same session with the default behavior of the JVM changed to always finalize.  If OdmUnRegisterApp occurs in the second case and not the first, there is an unreleased-interface "leak."

2.6.4 Temporary Workaround: Although the default behavior of the JVM can be changed by the application software, this should not be viewed as an ideal solution.

2.6.5 Design Concerns: It is always best to ensure that an ODMJNI interface is released as soon as it is known that it can no longer be used in the application.  It is important for the application software design to be architected in a way that there is certainty when that is.  If this is not determined naturally in the structure of the application, and forcing finalization is too costly, it may be important to keep a registry of interfaces and perform their release when the application is terminating.  (Duplicate releases are harmless.)

2.6.6 Risk Mitigation: In the event of a platform (Windows), JVM,  or application crash, it is not possible to ensure that all releases will occur.  In most cases, resilient DMS integrations clean up their incomplete sessions.  To minimize lost user work, the best safeguard is to release interfaces as early as possible after their known-to-be last usage and to have provisions for recovery of local backups of in-process documents that are not known to have been properly saved and closed. 

2.7 Do Not Perform ODMJNI Requests on the Java GUI Thread

2.7.1 Any ODMJNI request may involve communication to another process and use of the network.  While the request is being performed, the thread making the request may be blocked for an indefinite time.  If the request is on the Java GUI thread, no refreshing of the application GUI will be performed until control returns.   If there are extensive network delays or connection failures, this may leave the application blocked.

2.7.2 Any ODMJNI request may lead to a modal dialog from the DMS-integration software.  These dialogs require operator interaction and lead to indefinite delays.  If the ODMJNI request is on the Java GUI thread, no refreshing of the GUI will be performed until control returns, and the GUI will be locked against user interaction until the interaction with the modal dialog (which is refreshed by Windows) is completed.

2.7.3 Mitigation: For smoothest operation, the ODMJNI requests should be made on a worker thread that is separate from the Java GUI thread where GUI events are being processed.  Consider that ODMJNI is part of the managed-document model and should be on a separate thread from the view and interaction-control functions of the desktop application software.  This will require some additional effort to block user interactions while allowing the GUI thread to run until it is known that the ODMJNI request has been processed and its results are available.

2.8 Do Not Multi-Thread ODMJNI Requests

2.8.1 The ODMA API and the ODMA Connection Manager implementations follow a design that originated with 16-bit Windows (versions 3.x), early versions of Microsoft Windows NT, and Windows 95.  Although the ODMA32 2.0 Connection Manager is Win32 software and is generally re-entrant, the prospect of multi-threading in a single ODMA session has not been designed for nor has it been verified in any way.

2.8.2 The ODMA Connection Manager implementations through ODMA32.dll 2.0 are not thread safe.  State is maintained for each session.  Manipulations of that state are not protected against thread collisions.  There are also sequential operations (such as logging) that will be disrupted by multiple requests.  This is not a trivial problem, because input-output blocking at the Connection Manager and below are occasions for advancing a different thread.

2.8.3 There is no assurance that DMS Integrations are thread safe within a single DMS session.  In general, maintaining thread safety has not been emphasized as a design requirement for DMS integrations.  Because threading errors have inscrutable and difficult to isolate transient symptoms, the prudent default assumption is that DMS integrations are not thread safe.

2.8.4 Mitigation: Arrange for ODMJNI requests to be performed sequentially, ideally on a single worker thread.  This can be an useful addition to the approach taken for preventing GUI thread blocking (section 2.7).

2.9 Do Not Create Multiple Overlapping ODMJNI Sessions

2.9.1 The ODMA Specifications have had the following statement about OdmRegisterApp since the ODMA 1.0 Specification:

"A task may call ODMRegisterApp more than once. Each call will return a different handle, each of which must be released with ODMUnRegisterApp."

2.9.2 This statement is accurate with regard to the behavior of the ODMA Connection Manager.  Each entry to OdmRegisterApp creates an independent session and there is no conflict in the operation of the Connection Manager itself, except for possible confusion in the creation of logs (introduced with the ODMA 2.0 Connection manager).

2.9.3 Each ODMJNI session created via info.odma.odmjni100.OdmJniBind.application will lead to at most one successful OdmRegisterApp request at the OdmNative100 level.  In the odmjni100 implementation, these sessions are correctly matched to ODMA Connection Manager sessions.

2.9.4 For ODMJNI, the only useful purpose of multiple ODMJNI sessions is to have different sessions associated with different GUI windows via the info.odma.odmjni100.OdmJniBind.application appWindow parameter.  This has some appeal as a way to deal with multiple application windows, so long as the session is properly tied to the lifetime of that GUI window and all precautions against GUI-thread blocking (section 2.7) and multi-threading (section 2.8) are implemented for each ODMJNI session.

2.9.5 Even though there might be a successful organization (as in 2.9.4) for multiple-session operation, there are difficulties that the application developer cannot control.  Each ODMJNI session will also have a distinct session for each DMS integration that is used in that session, especially for the default DMS.  In addition to the increase of resources and the cost of additional session creation, there are potential risks of conflicts and instabilities in operation when an application uses multiple DMS-integration instances to operate with a single DMS.

2.9.6 Because of the difficulty of managing multiple sessions (as in 2.9.4) and the prospects of extremely-difficult to isolate integration problems (as in 2.9.5), it is strongly recommended that there be at most one ODMJNI session at any point in time.  Ideally, there should be at most one session for the duration of the application program's operation.  

2.10 Code Page Inconsistencies Can Corrupt Strings from ODMJNI

2.10.1 The odmjni100 interfaces and their odmjni100 implementations accept and supply java.lang.String values for document metadata and other string-valued parameters and results.  The intended interpretation of these String values is as the Java-defined support for Unicode.

2.10.2 The ODMA Connection Manager and the DMS integrations accept and supply single-byte character arrays for the same data elements.  It is a requirement of ODMA that these strings be coded in the current system's Windows ANSI Code Page (CP_ACP).

2.10.3 If a DMS integration fails to honor the current Windows ANSI Code Page in the character data that it accepts and delivers, the translation of certain character codes to and from Java Unicode will be corrupted.  There is generally no means for ODMJNI to detect this condition.   ODMJNI has no means to compensate for the inconsistency, even if detected as a translation error. 

2.10.4 Symptoms: Possible, but not uniquely-symptomatic, evidence for code-page inconsistencies include

2.11 Maintain GUI appWindow While ODMA Dialogs Are Possible

2.11.1 For GUI-based Java applications, the info.odma.odmjni100.OdmJniBind.application appWindow parameter is very important.  The Microsoft Windows window that implements the java.awt.Window that appWindow is based on will be the parent for all ODMA dialogs that apply to the running application.

2.11.2 If appWindow is no longer present when an ODMJNI operations leads to an ODMA modal dialog, the dialog will generally have no parent window and will not be forced to display atop the application-program's GUI.  The dialog may be hidden by another GUI window and not be noticed by the computer user.  The application may appear to be unresponsive or it may operate unexpectedly in response to user input because the dialog is not being responded to. 

2.11.3 The choice of appWindow and its use by the application will depend on the design of the application and the approach for coordination of the display of documents and ODMJNI operations applicable to those documents.  It may be useful, in this regard, that an AWT Frame or AWT Dialog can be used.  A Swing JFrame, JDialog, or JWindow is also usable.

2.12 Conservative Format Checks May Be Too Strict

2.12.1 The currently-implemented format checks for string-valued parameters have been defined conservatively.  That is, they tend to be more-restrictive than what may be permissible for the ODMA Connection Manager and, most importantly, connected DMS integrations.

2.12.2 The principle is that it is easier to expand the allowed cases than it is to ever restrict the allowed cases later. 

2.12.3 The liability of this approach, after ODMA has been in use for so long, is that there may be string-valued results from ODMA requests that are not accepted as parameters to other requests.  There are two cases of concern:

2.12.4 We will consider relaxations of these two filters based on reported difficulties in actual operation.  The concern is protection of DMS integrations that are not adequately defensive in what they accept.  Unfortunately, there is no method, at this point, for accessing DMS-supplied validations for these data elements.  This would be preferable to second-guessing the DMS. Currently, it is not possible to determine what DMS constraints are, and only the DMS can communicate any restriction in a way that is useful to the operator an ODMA-aware application.

3. Changes to odmjni100 in 0.59beta

3.1 Organization of pre-0.59 Regression Set

3.1.1 OdmClicker Preserved.  Regression set 0.54-odmjni100 contains the Clicker folder with complete source and compiled code.  This is extracted from the test/CheckSwing set, omitting the pre-OdmClicker confirmation experiments.  Only the latest confirmation results are retained for comparison with those of 0.59 operation.  Finalization of this material occurs as part of the completion of the new regression sets and packaging of odmjni100 0.59:

0.54-odmjni100/            [the Swing-based Clicker regression check]
  |-- Clicker/             [the backward-compatible 0.08 OmdClicker 
        |                   version that was tweaked for 0.58]
        |-- results/       [set of images and text files from
        |                   confirmations using OdmClicker]
        Check04-source.zip [script and source code for the programs]
        OdmClicker$1.class [internal class - also backed up in the .zip]
        OdmClicker.class   [the compiled OdmClicker regression check]
        RunSwingApp.bat    [script for running the regression check]

3.1.2 Check04 Preserved.  Regression set 0.57-odmjni100 contains the Check04 folder with complete source and compiled code.  This is extracted from the test/Check04 set, omitting obsolete Run scripts and old confirmation and test results.  Finalization of this material occurs as part of the completion of the new regression sets and packaging of odmjni100 0.59.  The idea is not to make further investment in the pre-0.59 regression sets except where the material survives into 0.59/0.60 and beyond.

0.57-odmjni100/            [the console-application regression checks]
  |-- Check04/
        |-- results/       [set of images and text files from
        |                   confirmations using Check04 applications]
        Clicker-source.zip [script and source code for OdmClicker]
        CheckChoice.class  [Exercise of chooseDocument cases]
        CheckKnown.class   [Exercise of openKnownDocument cases]
        CheckNew.class     [Exercise of acceptNewDocument cases]
        CheckUtil.class    [Common utility functions for Check apps]
        CheckUtil.dll      [library used for CheckUtil native methods]
        ConIO.class        [prompted-IO classes and interfaces used here]
        RunCheck.bat       [script for running any of the Check exercises]

3.1.3 0.59/0.60 Provisional Regression Started.  Regression set 0.59-odmjni100 is initiated with copies of the pre-0.59 regression-check folders Clicker and Check04.   These and the pre-0.59 regression sets are verified to preserve exactly what is needed to use them with 0.59.  After that point, the 0.59/0.60 regression checks are evolved to make 0.60-specific tests having no use of deprecated interface elements and implementations.

0.59-odmjni100/            [the provisional 0.59/0.60 regression set]
  |-- Clicker/             [starts out the same as in 0.54-odmjni100]
  |-- Check04/             [starts out the same as in 0.57-odmjni100] 
3.1.4 Commencement of ZigZag Development.  From this point on, no further changes are made at any stage until the corresponding adjustments are first reflected in the practical100 0.59beta development and its evolving confirmation tests.  Each time a change is made here, adapting to the confirmed practical100 changes, the pre-0.59 odmjni100 regression sets are confirmed and the provisional 0.59/0.60 regression set is updated to use only non-deprecated features, as necessary.  Zigzagging  in this manner is invaluable.  It provides immediate feedback on practical100 changes being workable with odmjni100.  This also provides confidence that a derivative of odmjni100 could also integrate just as successfully with the practical100 part of the ODMJNI 1.0 "stack."  And, finally, the regression sets evolve as needed in parallel with the changes.

3.2 Remove Parameter-Format Exceptions

3.2.1 Removing Parameter-Format Exceptions involves conforming to the changes in the practical100 interface definitions and class implementations, including the null implementations from which odmjni100 classes are derived.  The following classes and methods are impacted:

        OdmJniApp(rIface) [new protected constructor]

        OdmJniBind.application(appId, appWindow)

        OdmJniPend(rIodmPending, nullDoc) [protected constructor]


3.2.2 As part of these changes, appId is no longer passed to OdmJniApp and it is not retained anywhere after providing (along with any appWindow) to the OdmNative100 constructor for connections.

3.2.3 Some methods are simplified by not having to raise exceptions.  The checking of parameter formats can be deferred to OdmNative100 methods which will then return error codes as part of their built-in "head-check" defensive filters.  [2007-10-31: Until the defense within OdmNative100 is confirmed, a check is retained within openKnownDocument.]

3.3 Implement formatCheck Return of OdmFormatCheck Interfaces

3.3.1 OdmJniBind is changed to extend OdmNullBind.  This allows MAX_APPID_SIZE and the wfAppId methods to be defined by inheritance from OdmNullBind.  This is the only public change directly noticeable to Java via ODMJNI 1.0.  The other changes are delivered via practical100 interfaces.

3.3.2 OdmJniApp is changed to to supply the formatCheck method with implementation via OdmNullCache.nullCheck().  This is a provisional solution to be extended for 0.60.

3.3.3 OdmJniPend, extending OdmNullPendingDocument, supplies the nullDoc.nullCheck() of its constructor to the constructor of the OdmNullPendingDocument instance being extended.  OdmJniPend.formatCheck() is implemented by inheritance.   This is a provisional solution to be extended for 0.60.

3.3.4 OdmJniView, extending OdmNullWorkingDocument, supplies the nullDoc.nullCheck() of its constructor to the constructor of the OdmNullWorkingDocument instance being extended.  OdmJniView.formatCheck() is implemented by inheritance.   This is a provisional solution to be extended for 0.60.

3.3.5 OdmJniWork extends OdmJniView and requires no code changes to function properly.  The commentary and version were updated to reflect the behavior changes that occur entirely via inheritance.

3.4 Implement Refactoring of Metadata and Document Interface Implementations

3.4.1 Modify OdmJniView class declaration to now cover implementation of practical100.OdmBasicDocumentMetadata, practical100.OdmViewingDocument, practical100.OdmEditingDocument, and practical100.OdmWorkingDocument.  (All cases have the notChangeable document behavior.) 

3.4.2 The viewOnly method implementation is deleted from OdmJniView and both viewOnly and notChangeable are implemented by inheritance from OdmNullWorkingDocument.  The null behavior and the OdmJniView behaviors for both viewOnly and notChangeable are the same.

3.4.3 The OdmJniWork class declaration is given an implementation of viewOnly that relies on the implementation of notChangeable.  The notChangeable implementation returns false unless OdmJniWork has been released.   The commentary and organization of OdmJniWork are adjusted to reflect the refactored organization and the changes that will apply for 0.60.

3.5 Refactor Regression Sets

Based on the experience with the provisional regression tests, only one set needs to be split for pre-0.60 and 0.59/0.60.  The regression sets are organized and posted to the d071001: ODMJNI 1.0 Confirmation Tests folio.

3.5.1 Clicker Preserved.  Regression set 0.54-odmjni100 contains the Clicker folder with complete source and compiled code.  This is a repackaging of the set with improved organization, demonstration of results, and easier installation and execution in a location of the users choice.  This regression set works for pre-0.59 releases and for 0.59/0.60 releases.  Details are on the page d071001e: 0.54-odmjni100 Regression Set - Clicker.

3.5.2 Pre-0.60 Check04 Packaged.  Regression set 0.57-odmjni100 contains the Check04 folder with a version of checks that can be used to confirm ODMJNI 1.0 releases from 0.57 through 0.59.  These checks are not applicable for 0.60 and beyond.  Details and downloads are on the page d071001f: 0.57-odmjni100 Regression Set - Check04.

3.5.3 0.59/0.60 Check04 Packaged.  Regression set 0.59-odmjni100 contains the Check04 folder with a version of checks that can be used to confirm ODMJNI 1.0 release 0.59 and beyond.  Details and downloads are on the page d071001g: 0.59-odmjni100 Regression Set - Check04.

4. Development (started 2007-10-04; in progress)

4.1 Outline the Development (started 2007-10-04;  completed 2007-10-04)

Outline the development based on the description in the 2007-09-20 Tracking Report and d070701d: ODMJNI 1.0 Public Beta 0.59 Transition Candidate.  See sections 4.2-4.7 for the current development outline.

4.2 Freeze practical100 pre-0.59 Regression Tests (started 2007-10-04; completed 2007-10-10; revised 2007-10-13)

The available confirmation tests are reviewed and used to create an odmjni100-0.56beta-regression set.   The name of the set may change  This set applies to at least the 0.58beta compiled classes.   The freeze process will determine which level of pre-0.59 implementations each retained test is compatible with.  There will be a rational way to identify, refine and preserve regressions until they are obsoleted by breaking changes and removal of deprecated interface elements.  This is a rehearsal for the pattern to be applied at 0.59beta and beyond.

4.3 Change odmjni100 Implementation Classes for 0.59 (started 2007-10-17; completed 2007-11-15)

In step with each corresponding change in practical100, change the odmjni100 classes and updated regression tests to conform.   The changes will eliminate "throw" cases, identify deprecated elements,  and implement the additional interface elements introduced with practical100 0.59.

4.4 Confirm Pre-0.59 Regression Checks (started 2007-10-10; completed 2007-11-17)

At each step of the way, verify that the pre-0.59 regression set continues to work with the 0.59 version of practical100.  This is done in the course of stage 4.3 and at the conclusion and after any subsequent changes to the 4.3 results.

4.5 Develop odmjni100 0.59/0.60 Regression Tests (started 2007-10-10; completed 2007-11-17)

A provisional regression set is primed with the pre-0.59 checks and then evolved to remove all reliance on deprecated elements, relying on their replacements instead.  The evolving tests are rerun any time that changes are brought back that change the 4.3 results or any of the confirmation tests.

4.6 Package odmjni100 0.59beta Material (started 2007-11-23; completed 2008-03-30)

4.6.1 The 0.54-odmjni100 (Clickr) regression set is package for independent usage in confirmation of all releases from 0.54 to 0.59/0.60 and beyond (section 3.5.1). 

4.6.2 The 0.57-odmjni100 (Check04) regression set is package for independent usage in confirmation of all releases from 0.57 to 0.59.  This set relies on deprecated methods, interfaces and classes and will not operate beyond 0.59.

4.6.3 The 0.59-odmjni100 (Check04) regression set is packaged for independent usage with releases 0.59/0.60 and beyond.  Only those features of 0.59 that are not deprecated and that are carried forth into 0.60 and beyond are exercised with this confirmation check.

4.6.4 The license, release notes, manifest, and d061001o-odmjni100-0.59beta.zip archive are created and announced as available for review and provisional testing.

4.7 Final Packaging (started 2008-03-30; in progress)

The final packaging consists of any updating to the odmjni100 0.59beta material.  This is a reviewed package that is acceptable for inclusion in the final 0.59beta Packaging.   See d070901c: 0.59 Public Beta Transition Packaging.

5. Developer Notes: Working toward 0.59beta

2008-03-27-17:08 Barriers to Common Format Checking
I wanted to provide the common library for format checking as early as the 0.60 public beta.  However, there really can't be clean common code implementations until OdmNative100 delivers and accepts UTF-16 Unicode strings and operates with BSTR-like structures. 
    The natural progression, from a development perspective, is to update format checking as part of 0.80 when that refactoring of OdmNative100 is conducted.
    If an intermediate solution is required, the OdmNative100 library could be extended to provide appropriate native implementations for use by odmjni100 but with no/little shared use by OdmNative100 interfaces before the 0.80 refactoring.
2008-03-26-18:36 DMS Connection Lifecycle Problems
I have just determined that the ODMA Connection Managers do not manage the life cycle of DMS integrations properly.  In particular, an OdmUnRegisterApp will free all DMS DLLs whether or not any interfaces into the integration are still held. 
    Because ODMJNI intervenes between the Java Application and the ODMA Connection Manager via the OdmNative100 library, this situation is not possible.  OdmNative100 will not perform an OdmUnRegisterApp until any interfaces that can involve access to a DMS integration are first released.
    There is no caveat required about this.  The design of ODMJNI does not permit performance of OdmUnregisterApp at a dangerous time.  I must be careful in the further development of OdmNative100 for other, independent usage, however.  This note is a reminder to account for that when the planned refactoring of OdmNative100 occurs.  There may be complications with the prospective use of additional DMS interfaces intended for COM-level discovery by future ODMA 2.5 clients.
2008-03-25-20:22 Format Checks Not Clear
The caveats about format checks don't reflect the principles I applied in coming up with what may be too-restrictive ones.  I need to describe the motivation as well as the idea of choosing to err on the side of being too restrictive rather than too permissive, since restrictions can be dropped, but permissions are hard to remove.  I am not sure where there is a good place to explain this yet.
2008-03-25-19:06 More Caveats
Every time I have documented some caveats, more occur to me.  I think I have all that I can think of for now, so I just need to complete the ones listed in my work items. I will request review to see if others recall ones that I have forgotten.
2008-03-19-17:51 ODMASAMP Uses C:\WINDOWS\ODMASAMP.INI File
The use of an .INI file in the Windows directory will fail on Vista, even with administrator privileges.  The file will be created in a redirected temporary that is not found by the running of ODMASAMP again in a later process.  The behavior is as if the ODMASAMP documents are being magically deleted.  This has to be repaired for an ODMASAMP to be useful in the future.
2007-11-17-17:16 Regression Organization Still Lacking
I have been cleaning up the regression sets.  It is a pain.  I need a better-organized approach and more automation.  Also, there needs to be automated analysis of the results so I can tell quickly whether the expected behavior occurred or not.  None of this is going to be solved overnight.  I need to just improve with each release from now on.  There may be no decent solution until we get to the 0.90 Hardening distribution.  To do this thoroughly, we will need to have test fixtures beneath the ODMA Connection Manager, so there are some interesting dependencies of this work on the early progression to ODMA 2.5. 
   See also: d071002: Envisioning ODMA64
2007-11-16-22:00 ODMASAMP Requires Admin for New Documents
Among the many idiosyncrasies of the sample DMS, one is that it loses any document that is not created while running as an administrator.  I'm not sure what the details are (use of registry or access to a system directory), but it just fails silently.  Of course, any time there is a temp-directory cleanup, the older documents vanish too, although they remain in the sample DMS directory of documents available for selection.  Just venting.  The ability to start a console session as administrator has been sufficient as a workaround, as demonstrated in the screen captures of the 0.59 regression checks.
2007-11-16-17:00 Oh, Missed OdmFormat Usage in CheckKnown
It happens that CheckKnown in regression set Check04 uses OdmFormat.  I never looked.  I saw it when looking for viewOnly usages.  I got that clue and did searches in all three of those to make sure that I found all use of deprecated elements.
2007-10-13-14:43 Regression Setup Complete
I am satisfied with the organization of the pre-0.59 regression sets and the 0.59-odmjni100 regression set.  Although more documentation and organization can be added to the provisional material at any time, everything is ready for the first zigzag of changes from practical100 to odmjni100.
2007-10-10-18:28 Extending Test Development into the ZigZag
The development of new regression tests needs to follow along with incremental introduction of 0.59 changes over the 0.58 base.  To accomplish that, copies of the pre-0.59 regression checks are used to form a provisional 0.59 set. 
   For each adjustment to odmjni100 code, the pre-0.59 regression-checks will be confirmed. 
   But then any changes that can be made to a set of prospective 0.59 regression-checks will also be made and used as a regression check for 0.59/0.60 features. 
   To accomplish this, the 0.59/0.60 development of regression tests is being started now and will proceed in parallel with the zigzag of changes between practical100 and odmjni100.
   One consequence of this approach is that I won't know what pre-0.59 checks can be preserved unchanged and how simple the change may be.  This exercise will doubtless prove that the current tests are inadequate and don't exercise enough cases.  That is something to be dealt with over time as other developments increase the ability to refine the testing procedures and, especially, allow for greater automation of regression testing.
   At the end of the zigzag process, I can then see which tests are the ones to support with better documentation and other additions for being useful into 0.60 and beyond.  I won't be fussy about the tests that do not survive 0.59.
   It is possible that an 0.60 constraint will be missed, but that will be factored back into this set if discovered during the upgraded for 0.60 release. 
2007-10-08-17:55 Need Better Regression-Folder Names
When I chose 0.30-regression as the name of the practical100 set, I wasn't thinking ahead to when the regression sets might be carried with the run-time and not be differentiated by being under the practical100 or odmjni100 code trees.  At the moment there is no collision, but I need to think this through and get it done properly now.  The simple step is to replace "regression" by the package name, whether practical100 or odmjni100.  There is still more to think about as some of the tests change and others do not.
2007-10-08-17:16 Examine Existing Tests to Make Into Regressions
Not having previously thought about making regression tests out of my confirmation tests, I had not made any effort to avoid recompiling classes when the source code hadn't changed.  I also am not clear what happened with the tests as they were progressed through the 0.5x series of deployments.
   The OdmClicker test application was last modified with 0.54beta.  It requires the changes in OdmJniBind.application from 0.52beta.  It should work with 0.52beta as well, although incorrect character conversions might show through from 0.52beta.
   The Check04 set of test console applications should operate properly all the way back to 0.50beta, even though CheckKnown was not introduced until 0.57beta.  The shared CheckUtil class was modified in 0.57beta but its native-method CheckUtil.dll was not touched.  It seems that all of these are backward compatible for operation with all 0.5x drops.
   I had forgotten that, in 0.58beta, I updated RunCheck.bat to accept the name of the class to run and to accept an optional addition to the class path so that testing with the run-time jar could be done using the same script.  The default the class paths are those of the source-code tree set in OdmJava.bat.  The run-time jar is assumed to be at that point or somewhere below it, and the additional path segment (at least "\") and the .jar filename are accepted as the optional parameter.  I will build on this method.
   [update 2007-10-10: I also forgot that I had made a Clicker.jar as part of the installation check included in the 0.58 run-time package.  I am much closer to having an end-to-end regression structure that I can use, and have already tried out parts that I'd forgotten about.  Some dots are already connected.]
2007-10-04-17:57 Use of Zigzag Development Progression
It was not until I started to introduce this material (0.02) that I saw that I needed finer-grained feature-by-feature zigzag changing and testing of practical100 and then odmjni100.  This has been rippled over to the other materials.  It will also impact packaging in how the regression tests are made avaiable as confirmation tests in the runtime distribution.

Hamilton, Dennis E.
ODMJNI 1.0 info.odma.odmjni100 0.59 Transition Candidate Implementation.  AIIM ODMA Interoperability Exchange, ODMdev Development Note page d061101o 0.13, March 27, 2008.  Available with any downloadable software at <http://ODMA.info/dev/devNotes/2006/11/d061101o.htm>.
Revision History:
0.14 2008-03-30-17:41 Complete Packaging
The packaging of the 0.59beta material is completed. 
0.13 2008-03-27-17:59 Complete Additional Caveats
A large number of caveats are being compiled as a way to warn developers prior to the availability of specific documentation.
0.12 2008-03-20-12:20 Add Caveat on Finalizing
The problem of ensuring release of interface implementations is added to the caveats.
0.11 2008-03-19-17:56 Complete This Note
This note is completed except for completion of the downloads.  When those are completed, stage 4.6 will be complete and stage 4.7 will be pending.
0.10 2007-12-01-13:23 Complete Packaging of the Regression Sets
The three regression sets are packaged and posted in the Confirmation Tests folio.
0.09 2007-11-17-18:37 Complete Metadata and Document Refactoring Adjustments
The classes are adjusted to honor the refactored interfaces of practical100.  Deprecated elements and their replacements are documented and the notChangeable method is implemented.
0.08 2007-11-11-15:06 Complete formatCheck Adjustments
The adjustments to deliver OdmFormatCheck interfaces via formatCheck methods are made, along with corrections to be able to extend from classes of the 0.59 practical100 classes and implement the adjusted interfaces. 
0.07 2007-10-31-17:20 Complete Format-Exception Adjustments
The Release Notes are updated to reflect the completion of the changes and the final testing of the changes.
0.06 2007-10-23-22:48 Intermediate Update
The results of the removal of exceptions for ill-formed string-valued parameters remain to be documented, but the steps and their regression are accounted for.
0.05 2007-10-13-14:47 Refine Regression Setup
The pre-0.59 set is organized better and then the 0.59/0.60 provisional set is created using those sets for starter regression checks.
0.04 2007-10-10-19:56 Complete Setup of Regression Development
The relevant existing tests are captured into regression sets and then also cloned as the starting point for new tests to be evolved as the 0.59 changes are introduced.
0.03 2007-10-07-18:03 Analyze Available Regressions to Freeze
I looked over the available confirmation tests and now understand which ones depend on what levels of runtime and what I need to do to preserve them as a pre-0.59 regression set.
0.02 2007-10-04-17:59 Complete Development Progression
0.01 2007-09-25-14:54 Provide Initial Structure for 0.59beta
I corrected the name one more time to transition candidate rather than candidate transition.
0.00 2007-09-24-22:45 Provide Placeholder for Material
Create placeholder that will be populated with information as the 0.59beta Transition Candidate is defined and then implemented.

Construction Structure (Hard Hat Area)
Creative Commons License You are navigating ODMdev.
This work is licensed under a
Creative Commons Attribution 2.5 License.

created 2007-09-24-17:57 -0800 (pst) by orcmid
$$Author: Orcmid $
$$Date: 08-03-30 17:45 $
$$Revision: 42 $