d061201c-ReleaseNotes.txt 0.03       UTF-8                    dh:2006-12-07

                                 RELEASE NOTES

               ODMJNI 1.0 0.20alpha End-to-End Confirmation
               --------------------------------------------

        For the latest version of this material, consult web page
        <http://ODMA.info/dev/devNotes/2006/12/d061201c.htm>.
        This material is maintained on the ODMA Interoperability
        Exchange site at <http://ODMA.info>.

   The ODMA 1.0 0.20alpha distribution is provided to accomplish three
   important steps in the progression to full ODMA 1.0:

     1. Confirmation of the end-to-end operation of the ODMJNI "stack"
        from a Java console (command-line) application's connection to
        ODMJNI back to the ODMA Connection Manager and an available ODMA
        DMS integration.  Confirmation is accomplished by performing the
        basic exercises provided with the distribution (section 1).

     2. Description of how the 0.20alpha software is usable in other
        Java applications (section 2) and the basic connection lifecycle
        that must be managed by the Java application (section 3).

     3. Description of the critical elements that are required to be
        confirmed when integrating the 0.20alpha level of operation into
        Java GUI applications (section 2.3).  FEEDBACK FROM DEVELOPERS is
        required for any difficulties encountered with this step and the
        provisional arrangements that are included in 0.20alpha.


   CONTENT

     1. Basic Exercises
        1.1 Customization of OdmJava.bat
        1.2 Confirming End-to-End Function
            1.2.1 Using Setup04-reference
            1.2.2 Using RunSetup02
            1.2.3 Using RunNull00
     2. Confirmation in an Application
        2.1 Setting the environment for using 0.20alpha components
        2.2 Using ODMJNI in the application
            2.2.1 Starting out
            2.2.2 Using the OdmConnection interface
        2.3 Critical Confirmation for Java GUI Applications
     3. Integration in Application GUI Behavior
     Copyright Notice
     Revision History


1. BASIC EXERCISES

   There are three sample programs that can be used to demonstrate operation
   of end-to-end connection:

     Java app <-> practical100 - odmjni100 - odmjni100.dll - ODMA <-> DMS

   There are also two OdmJava.bat scripts that must be customized in order
   two operate the samples, which run as console (command-line) applica-
   tions.  They are all found in these parts of the 0.20alpha folder tree:

            <folder>
                /info
                    /odma
                        /odmjni100
                                OdmJava.bat << CUSTOMIZE
                            /test
                                /Setup02
                                    RunSetup02.bat << FULL END-TO-END
                        /OdmNative100
                            /test
                                /Setup04
                                    Setup04-reference.exe
                                        << NATIVE WINDOWS CONFIRMATION
                        /practical100
                                OdmJava.bat << CUSTOMIZE
                            /test
                                /Null00
                                        RunNull00.bat << NULL FRONT END

1.1 Customization of OdmJava.bat

   The OdmJava.bat scripts have two lines that need to be customized.
   These lines are here:

        rem LOCATION OF THE JAVA JDK ON THIS COMPUTER:
        SET OdmJava=C:\Program Files\Java\jdk1.5.0_09
        rem         ---------------------------------

        rem LOCATION OF THE FOLDER WHERE ODMJNI CLASSPATHS START
        SET OdmClasses=C:\MyProjects\java\ODMdev
        rem            -------------------------

   The first is where you have installed a version of the J2SE SDK.  The
   first setting is for the 1.5.0_09 release that was used in building
   and testing the 0.20alpha distribution.  Change this to locate the
   JDK on your system.

   The second one is the location (called <folder> in these notes) where
   you have extracted the 0.20alpha folder tree onto your computer.

   This is important because the scripts RunSetup02.bat and RunNull00.bat
   each depend on OdmJava.bat to find the java program and use the
   java packages that are part of the 0.20alpha folder tree.


1.2 Confirming End-to-End Function

1.2.1 Using setup04-reference

   The program setup04-reference.exe, under OdmNative100/test/Setup04,
   uses the native Windows COM part of the ODMJNI bridge directly.  If you
   suspect some difficulty with the Java portions, run setup04-reference
   to see what results it produces.

   This is a quick way to determine five things:

        1. Whether the ODMA Connection Manager, Odma32.dll is installed
           where ODMJNI can find and use it.

        2. Whether there is a default DMS for the application.  There must
           be either an explicit default registered against the application
           name ("OdmNativeTest" in setup04-reference) or there must be
           a global default that applies for all other applications.  If
           neither case holds, the application will not find a default DMS.

        3. Whether the specified default DMS (individual or global) is
           reachable and responding to a request for a document selection.

        4. Whether the DMS dialog for choosing a document is modal.  While
           the DMS dialog is being displayed,
             a. It should remain on top of the application window (in this
                case, a console window)
             b. The application window can't be used and no mouse action
                on it is effective until the dialog window is dismissed in
                some way.
           *** THIS IS VERY IMPORTANT ***

        5. The actions taken by the user with the dialog window are properly
           reported back to the application and that is confirmed in the
           output of Setup04-reference.

   The OdmNative100/test/Setup04 directory contains examples of ODMA logs,
   console transcripts, and screen shots that you can compare with.

   There are also two registry scripts (OdmNativeTestDefault.reg and
   OdmNativeTestNoDefault.reg) that can be used to specify a default
   DMS and then remove the default DMS setting.  You can also modify
   OdmNativeTestDefault.reg to change the name of the Default DMS to work
   with.

   In working with your own application, you can create similar scripts to
   make sure that the different cases are being handled correctly.

1.2.2 Using RunSetup02

   In folder odmjni100\test\Setup02, the RunSetup02.bat script can be
   executed within a console (command-line) session.  This script depends on
   odmjni100\OdmJava.bat having been customized properly (section 1.1).

   RunSetup02 performs essentially the same functions as Setup04-reference
   except it uses a Java application and the full ODMJNI package.  There
   should be equivalent results.

   RunSetup02 provides fewer details than Setup04-reference because it does
   not have access to the same kind of information.

   This is the end-to-end confirmation in the 0.20alpha distribution.

   Notice that RunSetup02 does not report the results of the user's actions
   with the Default DMS document-selection dialog.  The dialog is produced,
   and the user's action is recognized, but it is not reported back to the
   Java application at this point.  (Basically, a new object is created to
   communicate the result and 0.20alpha returns a null object where the
   new object should be delivered.  0.30alpha will overcome that.)


1.2.3 Using RunNull00

   With RunSetup02 and Setup04-reference, the idea is to get as far into
   connection with a default DMS as the 0.20alpha implementation allows.

   When ODMJNI cannot access the ODMA Connection Manager, it provides
   standard null responses for all operations.  Behind the scenes, it makes
   use of the practical100 OdmNullConnection and related classes to
   accomplish that.

   The RunNull00.bat script in practical100/test/Null00 is a basic exercise
   of the OdmNullConnection functionality as it has existed since 0.05alpha.

   RunNull00 is useful as a demonstration of the ways that ODMJNI does not
   fail but simply reduces function and availability of results.  Most of
   the time, this is done in a way that advises the Java application to rely
   on its normal file-access dialogs in place of defering to ODMA.


2. CONFIRMATION IN AN APPLICATION

2.1 Setting the Environment for Using 0.20alpha Components

   Two access components of ODMJNI 1.0 0.20alpha in your own Java
   application, you will need to specify the classpath (directory <folder>)
   to java.

   You will also need to tell java how to find odmjni100.dll.

   There is an example of what is needed (for the command-line java engine)
   in RunSetup02.bat.  This is the important instruction in that script:

        java -cp ".;%OdmClasses%" -Djava.library.path=..\..\ Setup02

   where %OdmClasses% was set in OdmJava.bat and the java.library.path is
   locating the directory containing the odmjni100.dll that is needed for
   ODMJNI operations.  An alternative value would be

        "-Djava.library.path=%OdmClasses%\info\odma\odmjni100\"

   The quotes are required if there are any spaces in the %OdmClasses%
   path.  There are other ways to set the library path.  The alternatives
   are specified in the JDK and JNI documentation.

2.2 Using ODMJNI in the application

2.2.1 Starting out

   The way to obtain an OdmConnection interface for use of ODMJNI in your
   Java application is with a definition such as the following:

        import info.odma.practical100.*;

            /* ... */

        OdmConnection myOdma
            = info.odma.odmjni100.OdmJniBind.application("MyApplication");

   where "MyApplication" is a string that names your particular ODMA-aware
   application.  (It must not exceed 15 alphanumeric characters, it must
   not contain spaces, and be unique enough to your product that a default
   DMS can be set for it in the Microsoft Windows registry.)

   Everything that happens after that is accomplished with the myOdma
   interface reference.

2.2.2 Using the OdmConnection interface

   All of the OdmConnection functions are implemented and represent
   actual condition of the ODMA Connection Manager and any default DMS.

   However, the functions for accessing actual documents are limited:

        * acceptNewDocument provides a null-document response

        * openKnownDocument provides a null-document response

        * chooseDocument *will* engage any default DMS and elicit the
          DMS document-selection dialog.  Then, whether there is a DMS or
          not, it provides a null response.

   These are all legitimate responses.  In the case of chooseDocument, the
   user's response is simply being over-ridden and the Java program is
   advised that the user requested that the application's own dialog be
   used.  The 0.30alpha distribution will replace that behavior, reporting
   the actual response and allowing a selected document to be delivered to
   the application for its use.

2.3 Critical Confirmation for Java GUI Applications

   The end-to-end confirmation demonstrated in the 0.20alpha distribution
   is accomplished using Java console applications.   No attempt is made
   to provide a Java GUI demonstration.  This distributions is to seek
   confirmation of successful Java GUI integration by Java application
   developers.  There are two critical measures:

        * Confirmation of the successful maintenance of an OdmConnection
          interface to the end-to-end ODMJNI solution achieved in 0.20alpha.
          This involves confirming the 5 features described for Setup04-
          reference (section 1.2.1).

        * Confirmation that the DMS dialog that appears in response to
          OdmConnection.chooseDocument() operations is properly modal.

          THIS IS A CRITICAL CHECK.  The dialogs must appear atop the Java
          application's GUI window. Operations with the GUI window must not
          be possible until the DMS Dialog is responded to by the user.

          0.20alpha demonstrates that this is accomplished for console
          (command-line) applications.  0.20alpha contains untested code
          to accomplish the same result with a Java GUI application.  Java
          GUI Application Developers: If a modal dialog is not presented,
          or it is tied to the wrong Java GUI Windows, please report this
          at once.  (See the end of this document for contact information.)

   The following section sketches the recommended approach to integration
   of ODMJNI operations and ODMA-aware behavior using the 0.20alpha
   distribution.


3. Integration in Application GUI Behavior

   The following hierarchical progression recommends ways that application
   GUI dialogs incorporate ODMA-aware behavior via ODMJNI:

   The application should be organized to keep track of the documents it is
   operating on, their origin, and their change status:

       * whether the document has a known location or is not associated
         with a known location (file system path)

       * whether the local document is the content of a managed document
         that is accessed via ODMA

       * whether there are any changes to the local document that have not
         been reflected at a file-system and location and in ODMA.

    > OdmConnection is established in the startup of the application.  A
      reference to the interface is kept available wherever users or the
      application may request access to a document: Open ... selections,
      Recent documents ..., etc.

      > If OdmConnection.availableConnection() is false, all document
        operations are to be accomplished with local file operations only.

      > If OdmConnection.availableConnection() is true, ODMA should be
        checked before performing a local file-system operation (other than
        Save on a document that was obtained from the local file-system).

        > If OdmConnection.dmsDefaultAvailable() is false, all document
          operations that would require a default DMS should be performed
          using the local file file-system.  dmsDefaultAvailable() is always
          false when availableConnection() is false.

        > If OdmConnection.dmsDefaultAvailable() is true, then operations
          directed against a default DMS should be attempted before trying
          the counterpart operation with the local file system:

          > OdmConnection.acceptNewDocument is used when there is content
            in the application that has no known location and it needs
            to be saved.  If there is no default DMS, this operation will
            simply return a null-document indicating that the local file-
            system should be used.  That is also the response in 0.20alpha.

          > OdmConnection.chooseDocument is used when the user indicates
            a desire to access a document.  If there is no default DMS,
            this operation will simply return a null-document indicating
            that the local file-system should be used.  If there is a
            default DMS, the DMS will interact with the user and return an
            indication of the user's response via a document object.  For
            0.20alpha, the null-document response is always provided.

        > OdmConnection.openKnownDocument is used when an ODMA Document ID
          has been provided to the application and that specific document
          is being requested.  A known Document ID might have been provided
          on the command line, as a link in another document, or from the
          application's recent-documents list or equivalent.  When
          OdmConnection.availableConnection() is false, this operation
          returns a null-document indicating that the request failed.  The
          operation will also fail if there is no DMS (default or otherwise)
          of the kind required for the particular Document ID.  0.20alpha
          always fails with this request.

    > At some point where it is known that the OdmConnection interface will
      not be needed, the OdmConnection.release() operation should be
      performed.  This allows resources that are not in use to be released
      by ODMJNI, rather than holding onto them in the prospect of further
      operations.  OdmConnection.release() will not release anything used
      by other ODMJNI objects (such as an in-use OdmWorkingDocument).  After
      an OdmConnection.release(), OdmConnection.availableConnection() and
      OdmConnection.dmsDefaultAvailable() return false and other operations
      of the OdmConnection behave accordingly.

 - - - - - - - - - - - - - - - - - - | - - - - - - - - - - - - - - - - - -

Questions, comments, discussion and feedback about ODMA concepts, status,
and materials are welcome.  Please send comments to the discussion list at
<mailto:activeodma-discuss@lists.sourceforge.net>.  For further details
visit <http://ODMA.info/contact.htm>.

             Copyright © 2006 NuovoDoc <http://NuovoDoc.com>
  Portions Copyright © 1994-1998 AIIM International <http://www.aiim.org>
                   and the respective contributors to ODMA.

           This work is licensed under the Creative Commons Attribution
           License.  To view a copy of this license, visit web site
           http://creativecommons.org/licenses/by/2.5/ or send a letter
           to Creative Commons, 559 Nathan Abbott Way, Stanford,
           California 94305, USA.

Attributions can be made in any suitable scholarly-citation format.  It is
requested that citations identify the material sufficiently for others
to be able to locate the material on their own.   This citation example
can be adapted to your purpose and format:

    Hamilton, Dennis E.
        Release Notes: ODMJNI 1.0 0.20alpha End-to-End Confirmation.
        ODMA Interoperability Exchange, ODMdev Development Note page
        d061201c-ReleaseNotes.txt 0.03, December 7, 2006.  Current version available as part of the archive downloadable at
        <http://ODMA.info/dev/devNotes/2006/12/d061201c.htm>.

 - - - - - - - - - - - - - - - - - - | - - - - - - - - - - - - - - - - - -

0.03 2006-12-07-17:11 Update the attribution information as a result of
     namechange and versioning of this text.
0.02 2006-12-07-15:25 Rename to ReleaseNotes and emphasize the two key
     confirmation requirements that apply to Java GUI applications.
0.01 2006-12-06-16:52 Complete the caveat information and repair some
     lines that were too long.
0.00 2006-12-06-13:27 Initial note on caveats to make clear what is
     important to confirm with the 0.20alpha distribution.

$Header: /ODMdev/d061201c-ReleaseNotes.txt 5     06-12-07 17:14 Orcmid $

                    *** END OF d061201c-ReleaseNotes.txt ***

