ODMdev: ActiveODMA Development Framework

devNote d070701
 ODMJNI 1.0 Public Beta
0.59 Public Transition Candidate

ODMdev>devNotes>
2007>07>

d070701d>
0.17 2008-04-23 21:12 -0700


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.  The resulting clean interfaces are to be preserved hereafter in all ODMJNI 1.0 releases.

1. Purpose and Scope
2. Breaking Changes
    2.1 Refactoring of Viewable, Editable, and Working Documents Plus Metadata
    2.2 Movement of OdmFormat Class Methods to OdmFormatCheck Interface
    2.3 Elimination of OdmError Exceptions for Format Violations
    2.4 Redefinition of Null viewOnly Response
3. Development Approach
    3.1 Summarize Changes
   
3.2 practical100 Changes
   
3.3 odmjni100 Changes
   
3.4 Packaging of 0.59 Beta
4. Developer Notes

1. Purpose and Scope

1.1 ODMJNI 1.0 0.59 transition candidate is the technical rehearsal for the creation of the 0.60 Public Beta distribution.  This is also where the last application-visible breaking changes are to be made.  Only corrections and additions will be made after 0.60.  The ability to safely make additions is also confirmed in the development of 0.59beta.

1.2 The 0.59 beta candidate is limited in the following respects:

1.3 The 0.59 release allows transition to an 0.60 stable public release that can be evolved thereafter:

2. Breaking Changes

Because release 0.59 involves both deprecated, new, and re-organized elements, practical100 0.59 and odmjni100 0.59 may only be operated with each other.  

2.1 Refactoring of Viewable, Editable, and Working Documents plus Metadata

2.1.1 Concerns.  The info.odma.practical100 OdmViewingDocument and OdmWorkingDocument interfaces, between them, are inadequate for embracing the range of desirable cases:

2.1.2 Assessment. There are too many cases to manage entirely by flavors of interfaces.  It is desirable to deliver restricted interfaces that match requests for restricted capability (e.g., opening a document only for viewing, only for changing) and to be able to cast to more-restricted cases as part of delivery of interfaces to subordinate functions.  Because the practical100 interfaces deliver document artifacts via file-system locations, we must tolerate the poor abstraction level that affords.  Higher-level abstractions are more appropriate when the overall ODMA Connection Manager model can be enriched.  Such changes are inappropriate for the practical100 level of supported operations.

2.1.3 Approach.  To provide enough fine-grained dependencies control to an application, the following modifications are made:

2.1.4 Mitigation.  All current operations involving existing documents deliver OdmWorkingDocument interfaces.  The 0.59 changes will appear to be additive.  It seems safe to assume that programs that cast to OdmViewingDocument or receives that interface will perform only-read operations on the document: There is nothing to learn from a viewOnly flag at that point.  There is no assurance that a viewOnly has a docLocation that cannot be written to: Modifications to the file are simply not deliverable to the DMS.

2.1.5 Implementation.  Most of these changes are implemented by modification of the info.odma.practical100 interfaces and the related null implementations.  The only change in info.odma.odmjni100 is in addition of notChangeable in implementation of OdmEditingDocument interfaces (including the OdmWorkingDocument subclass)..

2.2 Movement of OdmFormat Class Methods to OdmFormatCheck Interface

2.2.1 Considerations.  The only format filter that has to be available separate from any ODMA Connection is the wfAppId method.  That is also the only format that is defined entirely by ODMJNI 1.0 as a fundamental requirement for practical100 operation.  It is desirable for the other filters to be provided through an interface:

2.2.2 Approach.  For 0.59beta, the OdmFormat class will remain available and the OdmFormatCheck interface will also be provided.  In 0.60, the OdmFormat class will be reduced to a single static method, wfAppId, and all other checks will require use of the interface. eliminated completely.  The wfAppId method and any supporting constants will be moved to the practical100.OdmNullBind class (and replicated in odmjni100.OdmJniBind).  [updated 2007-11-05]

2.2.3 Mitigation.  Applications that operate correctly with 0.58beta should see no difference when operated with the 0.59beta release.  However, for 0.60 compliance, all places where OdmFormat methods are now used must be altered to use a dynamically-obtained interface instead (with the exception of wfAppId, which is supplied by an al constant).  This can be done using 0.59 since it supports the 0.60 approach.  New application programs and tests should be confined to the interface approach of 0.59.

2.2.4 Implementation

2.3 Elimination of OdmError Exceptions for Format Violations

2.3.1 Concerns.  In 0.58beta, an unchecked exception, info.odma.practical100.OdmError, is thrown whenever an ODMJNI operation is supplied with a java.lang.String parameter whose value does not pass the applicable OdmFormat filter.  The use of unchecked exceptions was to reject passing of unscreened data to ODMJNI as a fatal application error that should be prevented by first filtering the parameter values.  This does not actually prevent a developer from catching OdmError exceptions as a form of format checking.  The requirement that good date be submitted is not satisfied.  The throwing of OdmError is also problematic in situations where ODMJNI requests are performed on worker threads, the usual case in ODMA-aware GUI applications.

2.3.2 Assessment.  All places where ODMJNI now throws OdmError exceptions for format violations shall be changed to have the requested operation fail, with its normal failure response, without any additional explanation.  If and when logs are provided around these cases, the data-format violation will be identified.  There will be no programmatic indication, however.  There is more than one way a normal failure response can arise.  It is now necessary to filter parameter strings in order to eliminate that source of failures and be able to provide reliable failure responses in the application.

2.3.3 Approach.

2.3.4 Mitigation.  This is a change where it must be done now or never.  There is a tiny number of implementations relying on ODMJNI 0.58beta.  It is unlikely that catching OdmError exceptions has become an established practice.  Places where there are try clauses that catch OdmError exceptions should be easy to find and adjust to operate differently.

2.3.5 Implementation. 

2.4 Redefinition of Null viewOnly Response

The null behavior of OdmViewingDocument.viewOnly() is changed to return true.  This is consistent with the fact that commitChanges is not permitted for a null document.  The new OdmEditingDocument.notChangeable() is defined with the same null behavior.

3. Development Approach

Table 3-1.  Progression of Development Spirals
Stage practical100 Regression odmjni100 Regression Over-All
pre-0.59 0.59-0.60 pre-0.59 0.59-0.60
1. Complete Summary of Changes

-

-

-

-

-

-

2007-09-29
x.1 Outline individual Developments

2007-10-01

- -

2007-10-04

- - -
x.2.1 Freeze pre-0.59 regression sets 2007-10-07 ok - 2007-10-10 OK - -
x.2.2 Base 0.59-0.60 regressions on pre-0.59 2007-10-11 - ok 2007-10-13 - ok  
x.2.3-1 Remove OdmError on Format Check 2007-10-16 ok same 2007-10-17 ok same 2007-10-31
x.2.3-2 Implement OdmFormatCheck 2007-11-09 ok same 2007-11-10 ok same 2007-11-11
x.2.3-3 Refactor OdmDocument Interface Set 2007-11-13 ok same 2007-11-15 ok NEW 2007-11-17
3. Archive the Individual Packages 2007-11-21 0.01 same \2008-03-30 ok NEW 2008-03-30
4. Package 0.59 beta Deployment              
5. Announce 0.59 Availability              

3.1 Summarize Changes (started 2007-09-20; completed 2007-09-29)

The summary of changes on this page is expanded and filled in.  This is a top-level view.  Further details are provided in the folios that account for the individual portions of ODMJNI 1.0.

3.2 practical100 Changes (started 2007-10-01; in progress)

3.2.1 This stage consists of all interface changes and null behaviors that are visible to Java-based applications. 

3.2.2 Two sets of regression tests are created:

  1. Tests that use the interfaces supported in 0.58beta (without reliance on any OdmError exceptions) and can be used in regression of the 0.59beta interfaces.  These tests are expected to succeed without any changes or recompilation with the 0.59beta changes, but not thereafter when deprecated elements of 0.59 are removed.
       
  2. Tests that use the non-deprecated and new elements in 0.59beta interfaces.  These will be the regressions that go forward to 0.60 and later releases. These are created initially as provisional clones of the pre-0.59beta regression sets that are captured in (1).

3.2.3 The changes to make the 0.59beta practical100 are made and confirmed after the first regression set, 3.2.2(1), is captured for both practical100 and for odmjni100.  This continues through the entire sequence of changes, first in practical100 and its revised regression tests, then in odmjni100 and its revised regression tests.  The two sets of changes and regressions are evolved and verified together, providing immediate feedback on any incompatibility requiring adjustment to practical100.

3.2.4 Details are provided under d061001h: info.odma.practical100 Component Development 0.59beta Transition Candidate.

3.3 odmjni100 Changes (started 2007-10-03; in progress)

3.3.1 This stage introduces the non-null implementations of all behaviors visible to the Java-based applications.  If follows the same staging principles that apply for practical100 (3.2).

3.3.2 Two sets of regression tests are also created:

  1. Tests that work against the interface elements and behavior of the 0.58beta-level interfaces and elements.  These must be confirmed prior to any changes to the practical100 interfaces and the odmjni100 implementations.  These test are expected to continue to succeed without any change or recompilation using the 0.59beta interfaces and implementations.  Any use of deprecated elements will fail beyond 0.59, however.
      
  2. Tests that use the non-deprecated and new elements in 0.59beta interfaces and the odmjni100 implementations.  These are created initially as provisional clones of the pre-0.59beta regression sets that are captured in (1).

3.3.3 Changes are not made until after the first regression set (1) is captured for both practical100 and for odmjni100.  Changes are confined to the odmjni100 Java package. 

3.3.4 Details are provided under d061101o: info.odma.odmjni100 Java-OdmNative Bridge 0.59beta Transition Candidate.

3.3.5 There is not expected to be any change to the odmjni100.dll implementation of native methods.

3.4 Packaging of 0.59 Beta (started 2008-03-30; in progress)

3.4.1 Following the completion of changes to practical100, odmjni100, and their regressions/confirmations, a new complete packaging is created.  In this package, odmjni100.jar will contain the new Clicker confirmation program.

3.4.2 [added 2007-10-04] There will be regression tests against the packaging.  These can include additional tests related to execution with JAR-based applications, although that might not begin to arise until 0.60 and beyond.   The regression sets devised as part of 0.59beta may well be moved under the package development activity and be supplied in conjunction with the runtime.

3.4.3 Details are provided under d070901c: ODMJNI 1.0 Public Beta 0.59 Transition Packaging.

3.4.4 As part of the packaging, there will also be updating of d061201h: ODMJNI 1.0 Deployment of 0.5x beta Function-Stabilization Updates.

4. Developer Notes

2007-11-28-20:16 practical100 0.59 and odmjni100 0.59 Interoperability
odmjni100 0.59 should operate successfully with every practical100 release from 0.30 to 0.60.   There is no value in doing so and no such combinations are tested nor made available for distribution.  Although practical100 0.60 will be tested with odmjni100 0.59 as an internal check during development, that regression will not be published and we will immediately increment odmjni100 to 0.60 in all further testing. 
 
2007-11-27-18:47 How to Accelerate?
I have packaged practical100 already.  I am next going to remove the 0.30-practical100 regression set from that archive, since it now works completely fine as a separate distribution that can be included in the overall deployment package.  I have also completed the 0.54-odmjni100 regression set with its Clicker application.  0.57-odmjni100 and 0.59-odmjni100, both having versions of the Check04 applications, remain.  I want very much to complete 0.59 packaging by the end of November, and I am not sure, at this point, what I can triage to do it.  I will look for something as soon as I have the two remaining regression sets handled.
   
2007-11-17-19:19 Angst Over Development Staging
I am complete with all changes and they are tested with the current weak-coverage regression checks, updated only as necessary to avoid deprecated elements for confirmation of 0.60.  There is still archiving and completion of the individual packages to be done.  I am also concerned about moving to deployment with a package and also appropriate bundling of the regression sets.   I'm anxious to get on to 0.60, but I don't want to defer too much to that stage.  I want this to be a dress rehearsal for all of the 0.60 stages, with the only development, if any, being the building of a comment set of format checks in OdmNative100 that are used by an odmjni100 replacement for practical100.OdmNullFormat.  That's more than enough change to get through 0.60 along with removal of all deprecated elements.
  
2007-11-12-15:14 Committing to the Metadata Interface
I need to name the metadata interface and commit to what is included.  I had thought of OdmDocumentProperties, but this seems too non-specific and also too all-encompassing.  I have settled on OdmBasicDocumentMetadata to emphasize that this is metadata that the DMS provides independent of the document content (however it manages to obtain the metadata) and that it is the basic metadata available via ODMA.  It includes docId, dmsDocName, dmsAuthor, dmsDocType, and dmsFormatName.  It excludes docLocation and dmsWindowTitle, both of which apply to access and presentation of the document content.  It also excludes anything to do with the read-write authorization and other state information about the document.  (The viewOnly method and its replacement do not describe a condition of the document but of the individual access situation.)
    I was reluctant to include docId, because it will usually already be known and it is not intended to be dealt with directly by users of managed-document applications.  I decided to include it anyhow, because it helps to have the bundle of information conveyed by the metadata interface be self-contained and coherent.
   I also considered having this interface delivered by a metadata method, similar to the introduction of formatCheck methods.  This added level of introduction does not seem worthwhile, since caching is already handled in the implementations and it is important to tie the way the metadata can change to the document interface where that change can be provoked.  The provision of additional metadata beyond the basic ODMA 1.0 set may lead to rethinking of this situation, but the basic set will always be implemented directly in OdmViewingDocument.
  
2007-11-10-16:00 Need Separate Properties/Metadata Interface
The OdmViewingDocument interface has a number of methods that deliver metadata about the DMS document being accessed.  Some of this metadata is available without opening the document (the file with the content), so long as the Document ID is known and the particular DMS is available to the application. 
   To provide harmony with the future availability of interfaces to the DMS collection and the metadata provided by the DMS external to the document content, the metadata not associated with a document instance is defined in a separate interface.  This interface will be extended by OdmViewingDocument and, indirectly, by all interfaces that extend OdmViewingDocument.  The interface will be available for use and extension by other interfaces as additional facilities are added that rely on practical100 as a base.
     
2007-11-09-17:00 Change All _LENGTH to _SIZE
The OdmFormat class defines some constants for various sizes, such as MAX_APPID_LENGTH, MAX_DOCID_LENGTH, etc.  The use of length as a measure is inappropriate.  These terms are being deprecated along with OdmFormat itself.  The new terms, defined by the OdmFormatCheck interface (and the ...Bind classes) use _SIZE as a suffix, affirming that these apply to the storage structure and not the number of characters actually represented.  Even though these string parameters are always converted to code-page octet strings, those strings could include double-byte encodings.  Either way, the size (number of octets) is what is limited by the ODMA API and ODMJNI 1.0.
  
2007-11-01-22:17 wfAppId Moving to Bind Classes
Analysis for practical100 0.59 has convinced me that the wfAppId check should be part of the Bind classes where appId parameters are used.  The entire OdmFormat class will be deprecated and the OdmNullBind and OdmJniBind classes will provide the necessary static values and methods.
   
2007-11-01-19:20 Where Should Format Checks Be Provided?
As I reworked the practical100 materials and introduced an OdmFormatCheck definition, I wondered whether having OdmInterface.FormatCheck() was the proper place to expect OdmFormatCheck  interfaces to be provided.  There are two kinds of tension: (1) some of the formats are prescribed for ODMJNI 1.0 and it has little to do with code page problems; (2) there may be future interfaces (e.g., for administration and for non-document operations, such as search and metadata retrieval) for which these functions are not particularly relevant.  Its also the case that an OdmConnection interface and an OdmDocument interface do not have a direct need for the same formats to be checked. 
   So this is one of those analysis paralysis moments and I will simply find a solution that can be worked out of some day in the future without breaking changes.
   
2007-10-31-19:06 Improvements without Format-Check Exceptions
One of the awkward aspects of having OdmError thrown for parameter format checks is having that check be redundant because the OdmNative100 interface implementations (and odmjni100 native methods) must provide format defenses already.  Since these naturally return error or null status, the test at the Java level is redundant and was present only because any exception needs to be thrown at the Java level.  Considering that application software should be performing a format check for all externally-originating data anyhow, that meant three layers of checking when there is nothing amiss.
   It is best to have there be one-true-test and have it be at the OdmNative100 implementation, as close as possible to the ODMA connection.  This also means that we need to have the OdmFormatCheck implementation seen by the application software to use precisely the same checks.  This is finessed for now and it will be a large caveat for 0.59, to be removed in 0.60.
  
2007-10-28-15:55 Factoring Out Metadata
In thinking about expansion of support for other ODMA-based functions, it dawned on me that metadata access does not require an opened document, and that the supplying of metadata values should employ an independently-defined interface that can be used with other functions.  I am not sure what the interface should be called, but it should be defined as part of the refactoring that will happen in the last set of changes.  This will involve additions to section 2.1 here.  It is important to do this now, although there should be no impact between pre-0.59 and 0.59/0.60 at all.
   I am also thinking that some metadata elements should also be firmly affixed to document-access interfaces.  I'm thinking of the OdmViewingDocument.windowTitle() property.
  
2007-10-23-21:32 Simplifying 0.59/0.60 Regressions
I am noticing places where there is poor coverage in the pre-0.59 regressions that I am setting aside.  These lead to holes in the coverage of the 0.59/0.60 regressions when there is no need to make a change for 0.60 and beyond.  I have concluded to allow that.  The changes to make the 0.59/0.60 regressions should be the changes necessary to avoid use of deprecated elements.  Anything else should be dealt with in the creation of the 0.60 release or even later.  I do need a structure for capturing all of these areas to be tested and I will do that.
  
2007-10-17-13:08 Spiraling into Confusion
In defining the work for 0.59beta, I described the work on each package, and then the final packaging, as a separate progression.  Then, as the work was undertaken, I finally arrived at zigzagging and tiny spirals of change that cut through from practical100 to odmjni100 and back again for the next round of changes.  This overlay is difficulty to visualize and track in the account that I am providing.  On the other hand, I don't want to refactor all of that.  So I suppose what I will do is create a table, here where all of the changes are summarized at the top level, of the spiraling, with links into the by-package accounts.  That way, it will all make sense here and the package views will be local to those concerns while connected over-all.  [This is not unlike the need for a table of the dependencies among packages and previous releases for the 0.5x deployment progression.]
  
2007-10-17-13:01 Refactoring Some Gaps
Although I thought the tiny spirals were simply becoming tedious, it is not going that way.  In working through the first set of changes for practical100, I discovered some need to improve the definition of interface behavior, the contracts behind the interfaces, and I found some incorrect placement of data members that risks having un-verified string values leak into connection instance data.  So the added scrutiny that rereading for particular changes has brought my attention to other blemishes which I am repairing along with the changes.  I suppose that is how it works when I am the only known active reviewer of this code.  We'll see what happens when there are more eyeballs.
  
2007-10-17-10:19 Fear of Breakage
One of the reasons for the tiny spiral steps and regression-set development in 0.59beta is to provide a disciplined set of regression tests (unfortunately, mostly manual into the indefinite future) by 0.60beta and increasing into the planned deployment progression of 0.70, 0.80, and 0.90.  This is a dress rehearsal and I am taking baby steps to fill in where the testing, so far has been pretty shallow. 
   I believe that I have been careful and my desk checking and tests have provided stable fixtures.  But I am noticing how many untested corners there are.  I am living on borrowed time.  This was brought home to me this morning by an article by Norman Walsh.  Norman slacked off on the tests and got caught by it.  I want ODMJNI to be absolutely rock solid and confirmable in the field.  I am beginning to pay for that now, so none of us will have to pay later.
   Norman Walsh: Unintended ConsequencesNorman.Walsh.name (web log), 2007-10-17.
  
2007-10-13-12:10 Provisional Regression Sets Complete
Along with the pre-0.59 regression sets for practical100 and odmjni100, I also created provisional 0.59 regression sets for each package.  The provisional set starts out being a direct shared copy of the pre-0.59 ones, in a single set.  All sets work with the 0.58 implementations.  To have them start out the same, I did some rearranging and reorganization of the material.  I also deleted the test trees from my working development folders (although I have them in VSS for whenever needed).  I have the source code in little *-source.zip files.  This is to discourage the accidental replacement of the compiled regression tests with newly-compiled versions.  When I need to review or update any of the sources, I will do it using branched versions from VSS.  Strictly-documentation changes will be used to update both the pre-0.59 and the 0.59 provisional versions.  Material changes will have the *-source.zip packages branched and we'll end up with new 0.59 versions for that particular regression check.
  
2007-10-10-16:20 Angst Over Regression-Set Cleanup
I have completed squirreling away the existing confirmation checks that apply to verification of pre-0.59behaviors that 0.59 will preserve, but that 0.60 might not (first step of stages 3.2.2 and 3.3.2) .  I've confirmed that the regression sets work on the 0.58 code base, but I would like to perfect their organization and documentation a little.   But the regressions that matter are the ones that apply for 0.59/0.60 and I should put most of my effort in their usability.  Of course, some of the pre-0.59 regressions may well persist into the 0.59/0.60 sets.  It would seem, then, that the sooner I know that the better. So I will mainly tidy up my pre-0.59 sets to make sure I've preserved everything that I might otherwise miss later and get on with the interesting task of making the changes to the interfaces and the new tests.  That's what I will do.
   
2007-10-07-14:36 Preference for OdmFormatCheck Interface over Static OdmFormat Methods
I generally prefer interfaces over direct use of classes in any exposed API.  This is my automatic inclination.  With practical100.OdmFormat, I was attached to using static methods for the string-format filters and didn't notice,  that I was also creating unfortunate dependency of practical100 on odmjni100/OdmNative100.  I had this desire to substitute interfaces but it wasn't until I read some blog posts of Oren Eini that desire turned into resolve, even though I hadn't figured it all out:
   Oren Eini: More Reasons for InterfacesAyende Rahien (web log), 2007-09-29.  This is not the post that tipped me over (since it seems too recent), but it will do until I find the one that led to my resolve on this matter.
    
2007-10-04-17:16 Recognition of ZigZag Approach for the practical100-odmjni100 Change Progression
In defining the progression, I did not recognize the importance of alternating between practical100 and odmjni100 changes all the way through.  This confirms the compatibility of practical100 changes for implementation by odmjni100.  It also has the revised regression tests be evolved along with the feature changes.  This is in many ways a demonstration of the same technique that can be applied when updating an application from dependence on the 0.58 runtime to the 0.59/0.60 runtimes.
   
2007-10-04-15:06 Fretting About Build/Package Regression: Thinking Ahead to the End Game
Technically, any regression checks against practical100, odmjni100, etc., down in the source code tree are essentially unit tests, whatever their quality.  The runtime packaging of ODMJNI 1.0 should pass exactly the same checks (and some additional ones depending on JAR files).  It is a matter of using that package in the class path.
   I have not thought ahead to the use of the regression tests I am setting aside now with the runtime package as well as with the development tree.  I failed to think ahead to the end game.  So now I need to consider the tests being available for checking the final package and also being available for others to use as confidence tests, as a basis for tests against modified packages, and so on.  This is at a different level than where I have been putting them. 
   I am wondering about parameterizing an OdmJava.bat to use either class path, putting the regression sets I'm creating under the OdmDeploy100 part of the development tree rather than alongside the test tree where these programs are developed. 
   I could delay a decision about this until 0.60, but it would be nice to put it through the 0.59 rehearsal.  When I get to the 0.59 packaging step, I shall take another look.  I have added that topic to section 3.4.
   I also need to account for this under the practical100 and odmjni100 subprojects.  I won't be doing that with OdmNative100 because it is to become an independent product with its own deployment.  I will carry out these ideas there when the time comes in the 0.70beta time frame of ODMJNI 1.0 development.
 
2007-10-03-14:03 Wondering about FormatCheck() versus FormatCheck
It would be great if I could use FormatCheck and have a simpler expression of chained methods.  I think there might be something like this in C# properties, but I can't use it here.  The FormatCheck() method involves a cache of a possible non-null implementation and eventually a null implementation depending on OdmInterface.available().  So it must be a method because there is first-time cache-priming behavior and the cached-yet? check has to be made every time.  Just so you know why and I am reminded every time I wish I could change it.
    
2007-10-02-17:45 Refactoring the Refactoring
Sometimes it is not until I am reviewing something and struggling to improve/simplify wordings that I see how I have missed something.  I spent a lot of time in section 2.1.3 cleaning up the refactoring approach today.  First, knownNotChangeable() is simplified to notChangeable().  [By the way, this has to be a method too, because it is forced to false by release().]  Secondly, notChangeable() belongs on the OdmEditingDocument interface (for inheritance onto OdmWorkingDocument).
   
2007-10-02-17:30 Refactoring is not Normalization
The use of "Normalization" in the title of 2.1 caught me on rereading as I was putting in the proof-reading changes.  I am refactoring, but I have not achieved "normalization." 
   
2007-10-02-17:00 Is It Purpose or Scope?
The first section was called "Summary" but that isn't what it was.  I then though about Objectives, and then Scope, and settled on Purpose and Scope.  If I was rewriting it I might attempt to get rid of the conjunction and settle on a single purpose for the section (whether Purpose or Scope).  Or maybe not.  I don't feel too disturbed about this, and it is more aligned with what is in there.  I can stop fussing about it for now and I'll see what works on later versions.  (The Summary is the paragraph that precedes the table of contents.)
   
2007-09-29-17:39 Caching and Variation of OdmFormatCheck implementations
I have been avoiding the details of section 2.2-2.3 for a week.  Today, I recognized the desirability of caching and the need to tie the delivery of format-checking interfaces to OdmInterface.available().   Tying any non-null FormatCheck() result to the individual connection implementation seems very clean.  This strikes me as a great principle whether or not any application ever uses more than one OdmConnection implementation at any time.  Concurrent connections are not recommended at the moment because of potential race conditions in the Connection Manager and especially in ODMA DMS integrations.  We're also not all that clear what happens when two ODMA-aware desktop applications are running at once.  Any connection-manager log should be rather interesting.
 
2007-09-29-14:26 No Format-Checking OdmError Exceptions
To be clear, I am not going to provide OdmError exceptions for format checking on any method, constructor, or factory operation.  While it was considered for the Application ID parameters, I prefer to use null implementations and failure responses in all cases.  These will happen silently and it is up to the application to never submit unfiltered parameter data from sources not under the application's control.  [dh:2007-09-29 The 0.02 version of this page, completed today, affirms this approach.]
  
2007-09-23-17:57 Considering Model-View-Controller and Initial Creation of Interfaces
In looking at the prospect of still throwing OdmError for Ill-Formed Applications IDs (noted on 2007-09-20), I need to think about the different ways that initial connection interfaces might be used.  This might happen on the worker thread and it might happen on a main thread and the worker thread only be created when there is known to be an ODMA connection.  Any operation that requires a DMS action may lead to a modal dialog.  This needs to be balanced by the desire to have it known that at least the basic establishment of a working ODMJNI connection (not a DMS connection) has succeeded before a worker thread is even created, avoiding useless activity if the application developer so desires.  If the application does the ODMJNI connection setup on the worker thread, it is then wise to have the null behavior set up on the worker thread.  It looks to me like one would not want to create such a worker thread, so the application code that requests ODMJNI operations should perhaps be shielded by an interface that does to-worker thread requests only when that's needed, and offers a null behavior of its own otherwise.  [dh:2007-09-29-14:26 I am going to eliminate OdmError in all of these cases.]
   
2007-09-23-15:36 Introduce a Folio for OdmDeploy100 OdmPackage100 Development
As part of progressive disclosure, I also need a folio for describing the packaging process, its materials (i.e., under OdmDeploy100 OdmPackage100 in the development tree)  and its automation.  This is too detailed for the deployment page (d061201) which is just about the overall roll-up these days.  I will be making a separate folio for this.  I need it quickly so I can collect and track work items there.  This is a hangover from 0.58 beta.  I'd forgotten that this was left unaddressed.  [dh:2007-09-24 The new folio is d070901: ODMJNI 1.0 Packaging.][dh:2007-10-10 The folder is now named OdmPackage100.]
   
2007-09-23-15:05 Get to 0.60 as Stable with No Further Breaking Changes
I am emphatic that there will only making critical fixes and non-breaking additions to application-visible interfaces starting with 0.60 beta.  The 0.59 beta will be the same except for deprecated elements.  Deprecated elements will be retained in 0.59 to simplify confirmation and transition of existing code to the 0.60 interfaces.  Deprecated elements will be removed from the 0.60 interfaces and implementations. 
   
2007-09-21-20:30 Subdivide the Development Progressions and Details among Subordinate Materials
The progression defined on 2007-09-20 needs to be done with a kind of progressive disclosure.  The top level goes here, and greater detail goes on the pages where the practical100 and odmjni100 details are given for 0.59beta.  I expect that there will be a deliverable archive for each of these components, and the complete-deployment package will carry those as parts.
  
2007-09-20-17:00 Used OdmError for Ill-Formed Application IDs
There is no reason not to throw OdmError when an ill-formed Application ID is supplied to one of the factory classes.  It's really the uses of format names, DMS IDs, and other string inputs that we want to be well-formed on submission and that must be filtered by the application.  What's unacceptable is using OdmError as a substitute for application-provided filtering of other string-valued parameters.  I could leave the Application ID exception case in but remove the others.  [update 2007-09-23: This is a genuine breaking change in 0.59 beta.  The exceptions will no longer be thrown and the method descriptions will remove the advisory throws-clauses.  I need to consider whether my concern about worker threads applies even for the initial creation of interfaces, and even ill-formed Application IDs should result in null behavior, not an exception.  This may involve preserving the integrity of model-view-controller separation in applications, so I should proceed carefully here.]
  
2007-09-17-21:00 Use the Idea of Stable Open Beta for 0.60
The Facebook Developers Wiki has an interesting "open beta" statement that is along the lines I mean for what can be counted on in 0.59 and especially 0.60: " ... API is in open BETA now. ... Any application can access it now.  Everything ... should be fully working now, and we will ... minimize interface change as much as possible, but since this is still in beta, please make sure you have some backup of your data.  Thanks!"  [dh:2007-10-03-14:48 In my case I want this to be a no-kidding promise around stability, although I might have to make .6x additions if there are application-threatening (and user-data) problems uncovered in the public beta.]
   
2007-09-16-18:25 Consider Cross-Regression
I notice that having specific builds of regression checks is also going to be valuable in cross-regression cases.  That is, verifying that practical100 runtime works with odmjni100 built with a later or different JDK, there is preservation of behavior on different operating-system versions (e.g., going from XP SP2 to Vista), and so on.  I don't have a clear picture of how to matrix this, but the thinking in terms of regression sets and narrating which cases they have been confirmed with will matter.
  
2007-09-16-14:30 Breaking Changes, Migrations, and Regression Tests
I have been procrastinating 0.59beta definition, using the time to do some site cleanups, research, and pondering.  Last night I lay awake thinking about breaking changes, migration across breaking changes, and the tests that have to work without recompilation. 
   I must inventory the tests that I have that work with 0.58beta, build them and then keep the binaries (the *.class files) in 0.59 without rebuilding them.  I needed this already, and I don't know how I have managed not to think about it until now.  I also need to document the approach and keep regression versions somehow so they can be tried against future releases of Java, cross-wise, etc. 
   Somehow, this seems like what I have been waiting to show up, although I didn't know that was it until it surfaced.  I feel freed to get on with it now.
  

Attribution:
Hamilton, Dennis E.
ODMJNI 1.0 0.59 Public Transition Candidate.   AIIM ODMA Interoperability Exchange, ODMdev Development Note page d070701d 0.17, March 30, 2008.  Available at <http://ODMA.info/dev/devNotes/2007/07/d070701d.htm>.
Revision History:
0.17 2008-03-30-18:18 Reflect Completion of odmjni100 Archive
The packaging of the archive for odmjni100 0.59 beta is completed.
0.16 2007-11-17-19:25 Reflect Completion of odmjni100 Changes
Those changes and the identification of next steps are added.  In addition, the change of viewOnly null behavior is added as a breaking change.
0.15 2007-11-13-18:33 Reflect Completion of practical100 Changes
All known changes for practical100 are completed.  Any further changes are from pushback of odmjni100 changes that require practical100 adjustment.
0.14 2007-11-12-16:03 Introduce OdmBasicDocumentMetadata Interface
A new interface for document metadata is introduced as part of the refactoring of the OdmDocument interfaces.  It is not part of that progression, but OdmViewingDocument also extends it.
0.13 2007-11-11-16:07 Reflect completion of the OdmFormatCheck integration
All of the available regressions have passed, although these are weak tests in the case of anything to do with format checking.
0.12 2007-11-10-15:00 Adjust for Changes in Approach to OdmFormatCheck
The implementation description is updated to reflect the approach settled on as of the completion of changes to practical100.
0.11 2007-11-09-19:03 Reflect Completion of Step x.2.3-2 for practical100
The practical100 changes and regressions are complete and now odmjni100 must be completed.  This might cause the practical100 changes to be revisited.
0.10 2007-11-05-17:23 Reflect Change in wfAppId Checking
The wfAppId checks are moved to the OdmNullBind and OdmJniBind.  This puts the check in the context where it is actually needed.
0.09 2007-10-31-18:55 Close on Spiral -1
The recognition that there needs to be a separate metadata interface is diaried and there are some other touch-ups to reflect the completion of spiral -1, with all other activity to be performed in spiral -2, introduction of the OdmFormatCheck interface and OdmInterface.FormatCheck() method.
0.08 2007-10-23-22:58 Bring Tracking of Progression Current
The tabulation of progress through the development spiral is added and all but overall completion are documented here or in the folios for the individual packages.
0.07 2007-10-17-13:16 Notes on Experience So Far
Just partway into the first round of changes, there are some useful experiences to be acted upon.
0.06 2007-10-13-12:25 Update Information on Regression Sets
The creation of 0.59 regression sets by provisionally cloning the pre-0.59 sets is described.
0.05 2007-10-10-16:49 Link in 0.60 Stable Candidate Public Beta Material
A placeholder is needed for early notes and a sketch of how 0.60 will be carried out.  That page is linked into the version progression and additional developer notes added for bringing the situation current.
0.04 2007-10-04-15:42 Anticipating ZigZag Development and Regression of the Runtime Package
It just dawned on me that the same regression checks apply to the runtime packaging as to the under-development practical100 and odmjni100 releases in the development tree.  I have created a marker for that.  I'm also thankful that the structure I'm using is malleable enough to support this change without much fuss.  It provides an interesting simplification and expands the usability of the regression set.  The use of a zigzag alternation for the remainder of the development did not occur to me until I started defining odmjni100 0.59beta in greater detail today.
0.03 2007-10-03-14:00 Streamline Presentation, Interface Refactoring
Changes noticed when proof-reading the hard copy are introduced.  In addition, I saw important changes in the rational for interface refactoring and where the new methods should be place and what they should be named.
0.02 2007-09-29-17:46 Complete All Changes and Nomenclature Experiments
This is the official top-level description of the 0.59 deliverable and its changes.  Taking a Public Transition Candidate step preceding the first full-up Public Beta is now the established approach.
0.01 2007-09-23-14:56 Complete Summary of Changes and Add Progression
The summary of changes is updated and the development progression is summarized for linking to the other places where the work will be done.
0.00 2007-08-23-13:51 Provide Placeholder
This page is put up as a placeholder for description of 0.59 beta candidate material as the next stage toward the 0.60 Public Beta Release.  Provisional draft material is provided for initial review.

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-08-23-13:51 -0700 (pdt) by orcmid
$$Author: Orcmid $
$$Date: 08-04-23 21:12 $
$$Revision: 43 $