ODMdev: ActiveODMA Development Framework

devNote d061001
 info.odma.practical100 Component Development
0.59beta Transition Candidate

ODMdev>devNotes>
2006>10>

d061001h>
0.17 2008-04-23 21:11 -0700


Synopsis

The 0.59 Public Transition Candidate is a complete release in which deprecated interface elements and replacement interface elements are present together, along with breaking changes around parameter-validation and exception-generation behavior.  Transition to the 0.60 Stable Candidate is completed 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 practical100, the changes consist of marking elements as deprecated and introducing re-arranged and new elements that will persist from 0.60 onward.  The revision of interfaces is straightforward.  There is more impact on the null implementations: OdmNullBind, OdmNullCache, OdmNullConnection, OdmNullDocument, OdmNullFormat, OdmNullPendingDocument, and OdmNullWorkingDocument.  Of these, only OdmNullBind is ever used directly by an ODMA-aware Java-based application.  All of them are usable by odmjni100 classes, however.

Because practical100 0.59 involves both deprecated, new, and re-organized elements, it is only compatible with odmjni100 0.59.   It cannot be operated properly with earlier or later versions of odmjni100 (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 New OdmConnection.acceptNewDocument(docFormatId) Behavior
    2.2 Unstable OdmNullFormat implementation for OdmFormatCheck
    2.3 Weak Regression Checks
    2.4 Null appWindow Parameter Causes OdmError Exception
    2.5 Possible transferToNewDocument Difficulties
    2.6 Change to viewOnly null Behavior
    2.7 Incomplete Usage Documentation
   
3. Changes to practical100 in 0.59beta
    3.1 Organization of Pre-0.59 Regression Tests
    3.2 Remove Parameter-Format Exceptions
    3.3 Replace static OdmFormat with OdmFormatCheck Interface and Methods
    3.4 Refactor Document and Metadata Interfaces
   
4. Development
    4.1 Outline the Development
    4.2 Freeze practical100 0.58 Regression Tests
    4.3 Change practical100 Interfaces and Null Implementations for 0.59
    4.4 Confirm Regression Checks
    4.5 Develop practical100 0.59/0.60 Regression Tests
    4.6 Package practical100 0.59beta Material
    4.7 Final Packaging
  
5. Developer Notes: Working toward 0.59beta

1. Description

see also:
d070701d: ODMJNI 1.0 Public Beta 0.59 Transition Candidate

1.1 This 0.59beta stage introduces all practical100 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. 

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

Because practical100 0.59 involves both deprecated, new, and re-organized elements, it is only compatible with odmjni100 0.59.   It cannot be operated properly with earlier or later versions of odmjni100 (and vice versa with regard to practical100 versions).  Additional concerns apply to practical100, sometimes in conjunction with odmjni100:

2.1 New OdmConnection.acceptNewDocument(docFormatId) Behavior

Whether or not docFormatId is well-formed, null behavior of acceptNewDocument is to return a null OdmPendingDocument interface with localOperationRequested set.

2.2 Unstable OdmNullFormat implementation for OdmFormatCheck

2.2.1 There remains some indecision around the proper null-interface implementation of OdmFormatCheck interfaces as supplied by null-connection and null-document formatCheck methods.

2.2.2 Although the current null behavior, implemented internally in practical100 by the OdmNullFormat class, is an improvement over earlier approaches, there may be additional adjustment to provide proper default cases for odmjni100 extension and also to find a correct balance with what DMS integrations tolerate.

2.2.3 The expectation is that any changes will be toward relaxation of the existing checks, so that no applications will break as the result of future changes.

2.3 Weak Regression Checks

2.3.1 The only regression set for practical100 0.59 is the 0.30-practical100 set consisting of the Null04 Java application.  This check catches no differences between pre-0.59 and post 0.59 interfaces and their null implementations.  There is no verification of exception and edge cases, and the null implementation of OdmFormatCheck interfaces is not exercised at all.

2.3.2 The introduction of stronger test coverage, verification of edge cases and failure modes, and automation of regression checks are deferred to supplemental activity following the 0.60 release.

2.4 Null appWindow Parameter Causes OdmError Exception

2.4.1 Although the practical100.OdmNullBind.application(appId, appWindow) method is declared to possibly throw an OdmError when the appWindow parameter is null, this behavior was not implemented.  The exception is implemented in 0.59 and will be preserved in future releases.

2.4.2 If the application has no GUI window that is to be associated with the ODMJNI connection, the correct behavior is to use the practical100.OdmNullBind.application(appId) method.  This will cause modal dialogs to be associated with the console window, if there is one.  If there is no console window either, there is no assurance that modal dialogs will appear atop already-open application windows.

2.5 Possible transferToNewDocument Difficulties

2.5.1 There may be inconsistent behavior in validation of the docFormat parameter in transferToNewDocument operations.  ODMJNI 1.0 specifies strict limitations on this parameter as a filename extension.  formatcheck().wfDocFormatName may reject a format string, including one from OdmBasicDocumentMetadata.dmsDocFormatName(), that is actually acceptable to the connected DMS.  This difficulty will be resolved one way or the other in the 0.60 public beta release.

2.5.2 The transferToNewDocument implementation may not account for all possible responses from the ODMSaveAs ODMA operation used in its implementation.  If a DMS implementation does not not provide a new docId, the the operation should fail in some way that leads to the user being offered the opportunity to commit changes to the current document or to save them locally.  (See the odmjni100 0.59 caveat.)

2.6 Change to viewOnly null Behavior

The null behavior of OdmViewingDocument.viewOnly has been reversed (3.4.6).  This is a pointless breaking change to a deprecated method, but it is easier to leave the change than back it out.  It is expected that there will be no impact on any existing implementations.

2.7 Incomplete Usage Documentation

The documentation on setting up ODMA for tests and logging, using the ODMASAMP sample DMS integration, and other information needed for confirming regression sets and working with the source code is extremely incomplete.  This documentation will be built up gradually and might only appear as supplements to the 0.60 public beta release.

3. Changes to practical100 in 0.59beta

3.1 Organization of pre-0.59 Regression Set

see also:
d061001f: info.odma.practical100 0.30alpha Evolutionary Prototype.  The Release Notes (.txt file) establish the interfaces, null implementation, and tests that have been used up through 0.58beta.

3.1.1 0.30-practical100/ is created alongside the test/ branch of the practical100/ portion of the development tree.  This test has been used unchanged since 0.30alpha and it will likely remain usable for the life of ODMJNI 1.0.

3.1.2 0.30-practical100/Null01/ is a branch of practical100/test/Null01/ for independent preservation in the regression set.   The redundancy in the name is for later movement/replication of the folder under the run-time packaging tree. 

3.1.3 0.59-practical100 with sub-folder Null01 is created as an initial seed for development of the 0.59/0.60 regression checks as changes are made to practical100.  This is evolved along with the changes.  At the end, the changes needed here will determine whether to discard the 0.30 set or to retain it for 0.60 and beyond.  This also determines whether sharper tests are needed along with 0.60 or later.

3.1.4 From this point on, no further changes are made at any stage until the corresponding adjustments to preceding changes are reflected in the odmjni100 0.59beta development and its evolving unit tests.  Zigzagging between the two packages in this manner is valuable.  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."

3.2 Remove Parameter-Format Exceptions

3.2.1 The throwing of exceptions for ill-formed parameter strings is eliminated.  This impacts the documentary comments in many of the practical100 files.  There are code changes (at least the elimination of some throw clauses) in the following files and methods:

        OdmConnection.java
        OdmConnection.acceptNewDocument(docFormatName)
        OdmConnection.openKnownDocument(docId)

        OdmNullBind.java
        OdmNullBind.application(appId)
        OdmNullBind.application(appId, appWindow)

        OdmNullConnection.java
        OdmNullConnection()
            [with removal of unnecessary appId parameter]
        OdmNullConnection(appWindow)
            [with removal of unnecessary appId parameter]
        OdmNullConnection.acceptNewDocument(docFormatName)
        OdmNullConnection.openKnownDocument(docId)

        OdmViewingDocument.java
        OdmViewingDocument.transferToNewDocument(docFormatName)

3.2.2 While this work was carried out, all files were reviewed for consistent documentation commentary.  A number of additional improvements were made, including refactoring of some misplaced null-implementation behavior to where it belongs in odmjni100.

3.2.3 While the comparable adjustments were being made to odmjni100, it was noticed that there is actually no need to ever retain the appId beyond providing it to the native method that delivers a COM instance to be held by OdmJniApp.  With removal of that unnecessary class member, it is also unnecessary to pass appId to the OdmNullConnection constructor from OdmNullBind or OdmJniBind.  There is no validation at the OdmNullBind level (since the result is an OdmNullConnection instance regardless).

3.2.4 It is still necessary to pass appWindow to an OdmNullConnection constructor because OdmError is thrown if the parameter is null.   We need to do that in OdmNullConnection so the OdmError message includes the value of  OdmNullConnection.interfaceImplementation().

3.3 Replace static OdmFormat with OdmFormatCheck Interface and Methods

3.3.1 The entire OdmFormat class is deprecated for removal from the 0.60 release.  The dependency on OdmNullFormat is removed, since there is nothing useful to inherit and we want OdmNullFormat for other private purposes within the package.

3.3.2 The MAX_APPID_SIZE constant and the wfAppId method are added to OdmNullBind.

3.3.3 The OdmFormatCheck interface is defined as essentially those constants and methods of the deprecated OdmFormat that are not implemented by OdmNullBind.  At the same time, the constants are adjusted to end in -SIZE rather than -LENGTH, emphasizing that this is about storage in octets, not the number of successfully-encoded characters.

3.3.4 The repaved OdmNullFormat implements OdmFormatCheck and uses non-static versions of the corresponding methods from OdmFormat as a basis.

3.3.5 The implementation-internal OdmNull interface and OdmNullCache are updated to implement two methods for cached OdmFormatCheck interfaces:  OdmNull.nullCheck() and OdmNull.formatCheck().   For practical100, these are both implemented by an OdmNullFormat instance.

3.3.6 The OdmInterface interface is expanded with the formatCheck() method.

3.3.7 The OdmNullConnection class is expanded to implement formatCheck() by returning the nullCheck() from its internally-retained OdmNull implementation using OdmNullCache.

3.3.8 The OdmNullDocument class is expanded to accept an OdmFormatCheck interface at the constructor and to implement a formatCheck() that returns that interface.

3.3.9 The OdmNullPendingDocument and OdmNullWorkingDocument constructors are modified to accept an OdmFormatCheck parameter and deliver it to the constructor of the OdmNullDocument instance that is being extended.

3.4 Refactor Document and Metadata Interfaces

3.4.1 The OdmBasicDocumentMetadata interface is defined using the definitions originally defined directly in  OdmViewingDocument.

3.4.2 The OdmViewingDocument interface is modified to extend OdmViewingDocument as well as OdmViewingDocument.  The viewOnly method is identified as deprecated and the transferToNewDocument method is marked as deprecated from this interface, only being available with OdmWorkingDocument in release 0.60 and beyond.

3.4.3 The OdmEditingDocument interface is introduce as an extension of OdmViewingDocument.   This interface provides the new notChangeable method and takes the commitChanges method from OdmWorkingDocument.

3.4.4 The OdmWorkingDocument interface extends OdmEditingDocument, but it has no methods.  In 0.60, the method for transferToNewDocument will be moved here from OdmViewingDocument.

3.4.5 The OdmNullWorkingDocument class is given an implementation of notChangeable.  It uses the result of viewOnly, for now.

3.4.6 The OdmViewingDocument.viewOnly null behavior is changed to return true rather than false.  Although this property is not meaningful for a null document, this value is more consistent with commitChanges not being permitted.  There is no justification for this, since the method is deprecated anyhow.  Even though there is little likelihood that production code is broken by this change, it need not have been made.  Rather than do the work to restore the old behavior and repair the release notes, the change is retained.

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

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

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-01; completed 2007-10-07; revised 2007-10-13)

[2007-10-09: The regression set is 0.30-practical100/ with folder Null01/ holding the preserved test.]

4.2.1 The available confirmation tests are reviewed and used to create a practical100-0.56beta-regression set.   The name of the set may change.  Whatever its name, this set applies at least as far back as the 0.58beta compiled classes.  In reality, there is much that will operate from 0.56beta to 0.59 beta and some from earlier releases such as 0.50beta and even as far back as0.30alpha.  The freeze process will reconcile these cases and find 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.2.2 The regression set is performed against the current practical100 interfaces and null implementations.  It will be performed regularly as changes are made and new regression tests customized for the 0.59/0.60 set.

4.2.3 At this point, it is important to freeze odmjni100 pre-0.59 regression tests before any 0.59beta changes are made to either practical100 or odmjni100.  See d061101o: odmjni100 0.59beta Transition Candidate Implementation.

4.2.4 2007-10-13: To line up for adaptation as the provisional 0.59 regression set, the structure is streamlined as follows:

0.30-practical100/ [the regression folder]
  |
  |-- Null01/      [the elementary null-behavior check]
        |
        |-- results/                       [folder of results from pre-0.59 tests]
        |     |
        |     Null01-0.58-confirmation.txt [console log of check in 0.58]
        |
        ConWriter.class [helper classes for console output]
        IConOut.class
        Null01.class      [the check program]
        Null01-source.zip [all source code for building this regression check]
        RunNull01.bat     [script for running the regression check]

4.2.5 Additional documentation and instructions are developed as part of the 0.59-practical100 regression set.  They will only be factored back onto this regression set if there are no material changes and 0.30-practical100 is applicable for 0.59/0.60 also.
 

4.3 Change practical100 Interfaces and Null Implementations for 0.59
      (started 2007-10-14; completed 2007-11-13)

Change the practical100 package interfaces and null implementations to remove eliminated "throw" cases, identify deprecated elements,  and implement the interface refactoring and null-behavior changes.  It is possible to cycle back into this stage when implementation changes are found necessary in later tests and in use with odmjni100.

4.4 Confirm Regression Checks (started 2007-10-16; completed 2007-11-13)

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 additional changes to the 4.3 results).

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

[2007-10-11: The regression set is 0.59-practical100/ with folder Null01/ holding the provisional test.]

The pre-0.59 regression set is evolved to rely only on the 0.60-intended elements of the 0.59 practical100 implementation.  We'll determine the appropriate identification of this set following review and determination of the necessary changes.  Some of the confirmations may be unchanged.  These tests are also rerun any time that changes are brought back that change the results or any of the confirmation tests.

4.6 Package practical100 0.59beta Material (started 2007-11-18; completed 2007-11-21)

The license, release notes, manifest, and d061001h-practical100-0.59beta.zip archive are created and announced as available for review and provisional testing.  This package and this part of the development will not be final until any changes from odmjni100 confirmation have all been reflected in practical100.

The packaging wasn't attempted until after odmjni100 was confirmed.  There were improvements in the 0.30-practical100 regression set and then the final package was produced.

See also:
d071001d: 0.30-practical100 Regression Set

4.7 Final Packaging (pending)

The final packaging consists of any updating to the practical100 0.59beta material.  This is a reviewed package that is acceptable for inclusion in the final 0.59beta Packaging for deployment, and there may be adjustments for that purpose.   See d070901c: 0.59 Public Beta Transition Packaging.

{tbd: No changes are expected, but this activity can't be closed out until the final 0.59 deployment is put together.}

5. Developer Notes: Working toward 0.59beta

2007-11-28-20:08 Testing practical100 0.60 with odmjni100 0.59
Although the combination will never be put in the wild, the modifications for practical100 0.60 should be usable with the odmjni100 0.59 classes.  Although odmjni100 will, in that case, define methods that are not used by any of the practical100 interfaces, the combination should confirm  properly with the 0.59-odmjni100 regression set.  We will use that as an internal test but there will be no such combination in any defined release.
   
2007-11-27-19:38 Separation of Regression Sets
I have concluded that I don't need to keep regression sets as part of the basic package.  The test subdirectory, where Null01 is developed, is still part of the practical100 development tree.  That is an appropriate place for that.  The regression set is a snapshot of that preserved for use over time, with captured results.  It is useful to package that completely separately. 
    When I am ready to include the d061001h-practical100-0.59beta.zip as part of the general deployment, I will update the current one, and its manifest, to remove the regression set from the practical100 folder.  I think this will simply work better.  I will do that now for the odmjni100 regression sets to be issued along with 0.59beta.
   
2007-11-19-18:10 Regression Set On Separate Progression
I had been imagining how regression sets could go on their own version progressions over the past few days.  When I sat down to make a manifest for 0.30-regression, I realized that it makes no sense to lock it into the archive for this release.
   The current 0.30-regression Zip archive can and should be part of the practical100 package.  However, that should not be its official home.  It is included here for convenience and as part of the account for how the 0.59 package was confirmed.
   The 0.30-regression Zip archive has its own progression (and is independently downloadable) from a page of d071001d: ODMJNI 1.0 Confirmation Testing.  That is the page that the manifest in the regression set should refer to.  That page that has the usual download information as part of its version-progression block.
   
2007-11-18-20:19 Waffling on Packaging
I am waffling back and forth about the packaging of the regressions and the test folder.  The test folder is where I actually develop various checks, so the currently-viable tests need to remain in the package.  It is an appropriate place for any other developer to make modifications.  The 0.30-practical100 regressions set (with solo Null01 regression check) is more of a snapshot, and needs its own place in the scheme of things.  It may also show up in multiple packages.
   I don't want to have 0.30-practical100 and the other regression sets to have to be set up like archives on their own.  What I want is to have it incorporated in the d061001h-practical100-0.59beta.zip as an 0.30-practical100-check.zip archive.  It deserves a manifest.  If it has its own license it can simply be internal to the package. 
   That's where my thinking is on this right now.  I won't be done waffling until I get it done.
  
2007-11-17-18:48 Concerns About transferToNewDocument
The transferToNewDocument operation is defined as returning an OdmPendingDocument interface.  I am not sure there is any guarantee that there is not content for the new document already (in which case an OdmWorkingDocument is probably a better result).   Now, it is also clear that ODMASAMP does not provide any content for the new document.  I'm concerned that ODMASAMP is an unreliable guide to the behavior of other DMS integrations. 
    The ODMA 2.0 Specification suggests that a new docLocation is returned for ODMOpenDoc on the new docId and the application is expected to save its content to that location.  It is also allowable for the DMS to succeed and indicate that the docId has not been changed, so the change is to the same docId.  An ODMOpenDoc on this docId will fail if it is already open, so odmjni100 must somehow handle this properly. 
    For now, we need to indicate that an OdmPendingDocument may already have content that should be used if provided.  In the case of a transferToNewDocument, the content should be ignored but the docLocation might already be opened as a file and that must be allowed for by the application.
   I am definitely uneasy about this. 
   
2007-11-13-16:56 Boneheaded Change to viewOnly
After refactoring the metadata and document interfaces, I decided to be cute and have notChangeable return the result of viewOnly in the OdmNullWorkingDocument implementation.  But I wanted a different null behavior for notChangeable, so I changed it for viewOnly too.  This is a breaking change that was completely unnecessary: viewOnly is deprecated in 0.59, and will be removed in 0.60.  The technique actually makes sense in OdmJniWork, but it was not necessary to change the null behaviors.  Now that I have updated all of the comments and documentation, I'm not going to change it back, either.  There should be no one relying on the result of viewOnly for a null document.  (Fingers crossed.)
    
2007-11-12-16:00 transferToNewDocument Still in OdmViewingDocument
When I was ready to move transferToNewDocument, I realized that it would create a breaking change in any 0.58-compatible application that expected to find it there.  Since it arrives under OdmWorkingDocument (and OdmEditingDocument) by inheritance, that is good enough for now.  For 0.60 transferToNewDocument will move to OdmWorkingDocumentOdmWorkingDocument, the only actual implementation in practical100 can remain unchanged, it being indifferent to which interfaces deliver it.
  
2007-11-01-21:47 Blowing wfAppId Away
While setting up the OdmFormatCheck discussion in the Release Notes, it dawns on me we don't need the OdmFormat class at all.  The entire class should be deprecated. 
   I thought I needed to retain this class because of a chicken-and-egg problem.  A valid Application ID string is required to be provided to OdmNullBind.application and OdmJniBind.application methods.  So, to be consistent, there should be a format-check method available before the application performs one of those operations. 
   But the appropriate place for a format filter that applies to these static operations is on those same classes, OdmNullBind and OdmJniBind.  
   It would seem strange to require a way for an application to tell if its own Application ID is well-formed or not.  But there are cases where a program might receive the Application ID to use from external information: a configuration file or a command-line parameter, for example.  This would be useful in a test framework and the situation should be allowed for.
  
2007-10-31-20:08 Purity of the OdmFormatCheck Contract
As I edited a copy of OdmFormat.java to form the OdmFormatCheck.java interface definition, I noticed that there is not much abstraction in the description of OdmFormat.  It is also the case that most of the rules are dictated by the ODMJNI 1.0 implementation and do not depend much on the cooperation of the ODMA Connection Manager and any DMS integration that is being interacted with. 
   There is a tension.  I want OdmFormatCheck to be part of a clean but abstracted contract for the well-formedness conditions.   I also want flexibility for certain details to be determined by versions of ODMJNI and even, conceivably, with the cooperation of a Connection Manager or DMS integration.
   I may also be attempting to anticipate capabilities at some future ODMA 2.5 and 3.0 level without having any idea how it will really play out.  I will probably guess wrong.  What I can do is put my guessing in a place where it is easy to obsolete it or refactor it later on, as appropriate.
   I do know that the OdmFormatCheck description needs to be abstracted appropriately and there needs to be references to whatever "official" format requirements there are that can be expressed cleanly here.  I will do that much for 0.59/0.60.
  
2007-10-16-20:20 Null01 Can Check Exceptions and Views
I've not extended Null01 to check for expected null values of OdmViewingDocument property values and the expected exceptions for inappropriate use of commitChanges, transferToNewDocument, etc.  These can be added to the Null01 code while still being useable for pre-0.59 regression.  I should do that.  [2007-10-23: I am not going to make any changes in coverage for 0.59.   The only changes to the regression sets for 0.59 are those required to remove dependence on deprecated elements.  Additional coverage will be dealt with in 0.60 or later.  The critical path of this work involves on the essential work for reaching 0.60 with as much confidence in it as we had in 0.58.]
  
2007-10-16-21:40 How about Eliminating the appId Parameter Too?
Although the appId parameter passed to OdmNullBind.application is not used, the constructors for OdmNullConnection still require an appId parameter.  There is no reason to have those parameters on OdmNullConnection.  Duhh.  [The appWindow parameter is still needed so that OdmNullConnection can formulate the exception message for the null appWindow case.] [2007-10-17 These changes are implemented.]
  
2007-10-16-16:48 Elimination of odmAppId from OdmNullConnection
The removal of the format checks from OdmNullConnection makes it clear that there is no reason for that class to hold the protected odmAppId value, since it has no use in a null connection.  In addition, there is no point in validating the appId to a null connection (since that is all you can get in response) and there is no reason to ever allow an ill-formed appId string to be stored in a class member.  The odmAppId field will be implemented by OdmJniApp and that class will only be constructed if the appId string value is well-formed. 
   This is just one of those subtle things that is properly refactored when noticed as a consequence of adjusting something else.
    
2007-10-16-16:17 Continuing to Spiral
In the midst of (3.2), I am noticing how repetitious it is to spiral on each identified change, rather than making all changes needed when visiting a particular practical100 Java file for revision.  Although it is repetitious, I am maintaining my resolve to confirm the regression checks and make modified regression checks as needed along with these changes.  So I will continue spiraling for now.  When the time comes for 0.60, it will be much easier.
   
2007-10-13-13:43 Satisfied with Regression Sets
The organization of 0.30-practical100/Null01 is the pattern for the rest.  I am satisfied with this scheme and with the idea of cloning a branch of it that is used in testing changes and providing any changes for avoiding deprecated features, using the new 0.59 features, etc.  The set will be duplicated for the packaging and I will need to repair the Run scripts to work properly either way.
   
2007-10-09-17:29 Waffling Over Regression Structure
I am not taking action on this for now.  It is useful to have the regression set fall below the corresponding source development location (and hence the OdmPackage100 location too if replicated there).  I would like it if the tree were shallower (with, say, the runtimes for the tests at the regression folder level and the source code and build scripts in a zip file at that level too.  But I can also put the source in a zip within the existing folder.  This is something that will be thought about and not resolved until we get to the packaging of the runtime.  This will also depend on whether there is a package of regression tests with the practical100 code tree.  It seems likely.
   
2007-10-09-17:09 0.30-regression Renamed to 0.30-practical100
I am anticipating the regressions being moved to the some place in the run-time packaging tree where they may also be bundled with the run-time distribution.  There may be other changes to the packaging as I work this out.  For now, I am changing the names in the source tree and in VSS as a first step.  I am learning how little I have worked through the idea of having preserved regression sets that work for confirmation of the final build/distributions and also used in regressions in the development tree as changes are being made to the source-code units.
  
2007-10-07-15:32 Null01 Is a Weak Test
The Null01.java test has not been updated to check out all of the null cases in the full API.  This should be done.  Since this test is likely to be preserved through 0.59beta to 0.60beta I have some choice about when I can do this.  It would be weird to improve it at this point and then regress it all the way back to 0.30alpha, but why not?
  
2007-10-07-15:09 Recovering the Null01.class file
I had not realized that the Null01.class file is not kept in the practical100\test\Null01 tree.  I was able to retrieve an original compile of it from the 0.30alpha archive.  This ran just fine in practical100\0.30-regression\Null01 using RunNull01.bat without any modifications.  I do need to warn against recompiling and I suppose I could rename the source and the build script in a way where it takes a conscious effort to make a new one.  I need to think about that.  Maybe I should zip up all of the source and build parts inside the 0.30-regression\Null01 folder.
 
2007-10-04-18:30 Need to Centralize Regression Sets
At some point, I want to see how to use the same regressions during testing of modifications and in testing of the deployment package.  The regressions should probably be made available as part of the run-time distribution in any case.  I will worry about this when we get to the packaging stage of 0.59beta.  Meanwhile, I will keep regressions adjacent to the test folders until I come up with a general solution for sharing the same regression.  [2007-10-08-15:40 I notice that, because of packaging considerations, I need to have the regression tests with the build tree too, since they can be used independently.  This is an odd interdependency that I need to reconcile.]
  
2007-10-04-16:55 Adopting Zigzag Walk through 0.59beta Changes
Looking at the odmjni100 progression, I realized that each change there should immediately follow the corresponding change here.  That way, there is immediate feedback that the changes are compatible.  The unit tests of both packages should also be updated progressively in the same way.  This is not unlike an example of how an application could be evolved from 0.58 to 0.59/0.60 readiness.
  
2007-10-03-15:52 Determining Appropriate Tests for the pre-0.59 Regression
I am a little nervous about choosing the tests. It is not that hard.  I must look in the development tree on my machine, examine all of the tests/checks that are there already, basically latest first, and see how to identify them and set them up in a folder of regressions.
   On looking, I see that there is only Null01 that works with all of practical100 since 0.30alpha.  Null00 was obsoleted by breaking changes in 0.30alpha (it won't compile).   The only subsequent difference in the tree to Null01  is the change of OdmJava.bat to version 0.05 in ODMJNI 1.0 0.58beta.   That change is inconsequential for Null01 compilation and execution.  So we have an 0.30 regression set coming into 0.58beta.
   There is no use of OdmFormat and no exception-yielding behavior in Null01.  That's how this simple test has managed to survive all this time.  A free-standing check of OdmFormat is envisioned but has never been written (which may explain why the most-howling bug in ODMJNI so far was in that code).  And with or without that, there is only the null implementation, OdmNullFormat, actually used in the practical100 null implementations even going into 0.59.
   It looks like Null01 is going to persist for pre-0.59 regression and into 0.60 and beyond.  We may need improvements and automation, but essentially the same test should work all the way back.

Attribution:
Hamilton, Dennis E.
info.odma.practical100 Component Development -- 0.59beta Transition Candidate.   AIIM ODMA Interoperability Exchange, ODMdev Development Note D061001 page d061001h 0.17, March 19, 2008.  Available at <http://ODMA.info/dev/devNotes/2006/10/d061001h.htm>.
Revision History:
0.17 2008-03-19-17:38 Connect to odmjni100 0.59 Caveats
The current status is identified as pending (4.7).  The caveat about transferToNewDocument is connected to the corresponding passage in odmjni100 0.59 page d061101o.
0.16 2007-11-21-23:08 Completion of 0.59 Package
The packaging is completed, with manifest d061001h.txt 0.00 .
0.15 2007-11-18-21:50 Prepare for packaging of inf.odma.practical100 0.59
Everything is current except for the wrap-up of the regression set, packaging of the overall archive, along with a manifest and finalized release notes.
0.14 2007-11-13-17:32 Complete Testing and Documentation of the Final Changes
Although we must allow for potential changes pushed back from odmjni100 use of the current practical100 package, we have every reason to believe that the basic changes are now in their final form, ready for packaging.
0.13 2007-11-12-18:42 Document Changes for Refactored Document Interfaces
The refactoring of the document interfaces is defined.
0.12 2007-11-09-18:55 Complete Documentation of OdmFormatCheck implementation
The changes are reviewed, annotated, and documented enough so we also know what needs to be remedied for 0.60 or beyond.
0.11 2007-11-06-22:21 Completion of OdmFormatCheck implementation
The changes to implement OdmFormatCheck and the formatCheck methods are made and the initial regression check passes.
0.10 2007-11-05-17:35 Reflect Change in OdmFormat Deprecation
The deprecation of the complete class with movement of wfAppId is reflected in the definition here.
0.09 2007-10-23-22:13 Review on Tests and on Changes
The Release Notes draft is connected.  There is also review with regard to test coverage and coordination into the d070701d master page on the 0.59 Transition Candidate development.   This is an interim change.  There are additional notes to be completed before commencing the next change.
0.08 2007-10-16-22:04 Complete the First Set of Changes
The removal of exceptions for ill-formed string-valued parameters has been completed.
0.07 2007-10-13-13:34 Stabilize the Regression Setup
The setup first created here and replicated with odmjni100 is confirmed as the approach to be used.  The notes and description are updated.
0.06 2007-10-10-20:10 Synchronize the Regression Setup
The initial creation of the 0.59/0.60 regression set is accounted for under section 3.1, with refinement of how we then proceed with an extended zigzag between practical100 and odmjni100 development of the 0.59 changes.
0.05 2007-10-09-17:21 Change the Regression Set Name and Structure
I made this one adjustment to get the tree working the way I want.  This matches the approach used for odmjni100, for now.
0.04 2007-10-07-15:37 Mark Regression Freeze as Complete
We are not doing anything else on the frozen regression set until we get to stage 4.5.
0.03 2007-10-04-17:08 Introduce Zigzag Approach
Hmm, I need an image of that sailor.  The material here is adjusted to reconcile with the zigzag methodology noticed when I started working on the definition of odmjni100 0.59beta.
0.02 2007-10-03-17:21 Select 0.30-regression/ Set
The 0.30 regression set is set up for appropriate use.  It needs to be run from there, its Run and Build scripts adjusted as necessary, and then its usage documented.
0.01 2007-10-01-22:46 Outline the Development
The section 4 Development outline is completed as the first step of the practical100 stage.  The freezing of regression tests is in-progress.
0.00 2007-09-23-16:38 Provide Placeholder for Commencement of 0.59beta Development
This page is put up as a placeholder so that the 0.59beta version of practical100 development can be captured.

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-23-16:18 -0700 (pdt) by orcmid
$$Author: Orcmid $
$$Date: 08-04-23 21:11 $
$$Revision: 38 $