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.1.1 Provides complete, self-contained roll-ups of run-time, library, builds, and source code as a rehearsal of the 0.60 complete deployment.  Download and install of earlier versions is not required.
    
• 1.1.2 Introduces all breaking changes required to have complete and stable interfaces that will be preserved in 0.60.  This is the last opportunity for non-additive changes as part of refactoring the public interfaces.
     
• 1.1.3 Preserves deprecated elements from 0.58 beta so that 0.59 can be used by application code in making incremental transitions to the stable interfaces that will survive into 0.60 and beyond.  Although there are breaking changes, current Java code that relies on ODMJNI 1.0 0.58 should operate properly without recompilation.  Any changes to remove deprecated elements and confirm reliance on only the final elements should be straightforward and can be carried out and confirmed prior to 0.60 availability.
    
• 1.1.4 Establishes regression-confirmation tests and preserves them in compiled form for testing against future releases of ODMJNI 1.0.  This structure is piloted here for finalization with 0.60.  These provide confirmation that future releases of the practical100 interfaces and implementations do not represent breaking changes to code compiled with the 0.60 versions.  This is the start of a set of cross-regressions that can be used to confirm with different platform versions (e.g., Vista), other JDK releases.
      
• 1.1.5 Achieves a stable level for which documentation, examples, confirmation code, and test exercises can be produced for use with 0.60 and later developments.
    
• 1.1.6 This level is intended to allow declaration of an 0.60 version as stable for production use, based on the successful use since 0.58 along with successful transition via 0.59. 

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

• 1.2.1 Documentation is inadequate and the release notes may be insufficient for use by developers who have not relied on the 0.58 beta preview already.
    
• 1.2.2 Attention is on the least changes needed to work with existing programs while providing improved interfaces.  There is no effort to tune the implementation and to eliminate unnecessary or inefficient code.
    
• 1.2.3 There is little automation in the provision of a complete build.  Confirmation tests are not automated.
     
• 1.2.4  Verification and authentication of the runtime and libraries is weak.

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

• 1.3.1 Documentation will be developed and reviewed.
    
• 1.3.2 Any defects in the 0.59beta can be repaired before the 0.60 public beta is publicized.
    
• 1.3.3 A repeatable build and confirmation process can begin.
     
• 1.3.4 There is an evolutionary regression set for confirming cross-platform and up- down-level versions: e.g., different computers, operating-system versions, JVMs, JDKs, and other tools, including changed DMS integrations.
    
• 1.3.5 Implementation changes beneath the interfaces can proceed without disrupting the productive use of ODMJNI 1.0.
    
• 1.3.6 All deprecated elements retained in 0.59beta strictly to mitigate transition will not be documented and will be removed in 0.60.
     
• 1.3.7 Further changes to the interfaces will be limited to additions that do not interfere with applications based on the 0.60 versions of the interfaces.

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:

• View-only access.  Accessing an existing document only for viewing.  There is nothing to prevent the document being copied and modified by an application, there is just no way to convey any alterations back to the DMS.
    
• Delegated viewing.  Delivery of a viewing interface that only offers viewing operations to some subordinate procedure.  The subordinate essentially has only read-only access capability regardless of the available access case.  Protection against alteration of the accessible document requires via penetration through the interfaces to implementing classes requires additional protective measures.
    
• Editable-Document access.  Accessing an existing document where it is permissible to commit changes made to the accessible file back to the DMS.  
     
• Delegated editing.  Delivery of an editable-document interface for usage by a subordinate function.
     
• Save-As Operation.  Ability to request that the DMS create a new managed document of an (edited) accessed document in the DMS itself.  This is presently accomplished with the transferToNewDocument method.  (It is always possible to perform an external Save-As in the application.  The transferToNewDocument is a request that a DMS-managed document be derived automatically by transfer from the currently-accessed document.)
    
• Working-Document Access.  An access that offers all of the available cases, with possible restrictions against particular sets of operation - editing and Save-As in particular.
   
• Independent Metadata Access [added 2007-11-12].  The metadata that is provided through ODMA Document interfaces is also available independently without accessing the individual document content.  To allow for that availability in other ODMA-supported operations that may be provided in the future, it is useful to have the common metadata defined by a separate interface that may be useful in other situations.  One might desire to provide just this metadata and nothing about access of the content, to support functions.

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:

• [Added 2007-11-12] A new interface, OdmBasicDocumentMetadata, is defined for delivery of the metadata that is separately available and usable by an application.   There is no separate implementation as part of ODMJNI 1.0 as presently defined, however.  It is possible that purely-additive changes will arise that include implementation of the interface by standalone instances.  This interface provides the docId, dmsDocName, dmsAuthor, dmsDocType, and dmsFormatName metadata values.
    
• [Added 2007-11-12] The OdmViewingDocument interface is defined to extend OdmDocument and  OdmBasicDocumentMetadata.
     
• An additional interface, OdmEditingDocument, is added between OdmViewingDocument and OdmWorkingDocument.  The commitChanges method is moved to OdmEditingDocument.
    
• The OdmViewingDocument.viewOnly() check is deprecated.  It will be removed in 0.60beta.  There is no need for a viewOnly() indicator on an interface that only supports access.   One should not presume that material found at  OdmViewingDocument.docLocation() can be altered in place. 
    
• The OdmEditingDocument.notChangeable() method is added to indicate that any OdmEditingDocument.commitChanges() operation will fail, whether or not it is possible to open the OdmEditingDocument.docLocation() file for writing.  This is a more-accurate replacement for the deprecated viewOnly method.
    
• The OdmViewingDocument.transferToNewDocument operation is moved to OdmWorkingDocument.  There is currently no reliable mechanism to determine whether or not such a request will be accepted by the DMS.  Nothing is done in 0.59beta to work around that limitation.  [In ODMA 2.0, there is a function for determining whether or not a DMS implements this function at all, but not on an individual document.  Any discovery of ODMA 2.0-provided information is not expected before 0.90beta.]
    
• Guidance on control of access beyond the limited information available through ODMJNI will be included as part of the 0.60 release.
    
• Additional methods that do not contradict the non-deprecated ones of 0.59 beta may be added at 0.60 and beyond.

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:

• Using an interface allows for runtime variation among different ODMA-DMS combinations.  It is conceivable that the rules may vary depending on configuration conditions, especially ones around character-set encodings, that the practical100 code should not have to be discovering.
    
• An interface provides greater flexibility for test cases and substitution of implementations when subjecting applications to stress tests and failure-mode verification.
     
• The use of an interface allows a common implementation to be used beneath the odmjni100 code and the OdmNative100 code so there are no peculiar edge cases where (1) OdmFormat produces a more-restrictive filtering than OdmNative100 imposes or, (2) worse, OdmNative100 is more-restrictive than the OdmFormat filtering, or (3) worst-of-all, a string, such as an ODMA Document ID received from an ODMJNI 1.0 interface is not accepted by an interface where it should be automatically recognized as well-formed.
    
• The use of an interface technique not relying on info.odma.practical100.OdmFormat code preserves an important separation of concerns between the practical100 interfaces and the odmjni100 (or other) implementations.  There is some creativity required to reconcile null implementations under practical100 in this case.

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. 

• The interface will be implemented by a version of OdmFormat OdmNullFormat class (with no public constructor).  There will be derived classes in odmjni100 that reflect the conditions of the current OdmNative100 implementation.  This will be at least the same as the OdmNullFormat filtering, but it might be more stringent.  [updated 2007-11-10]
    
• The OdmFormatCheck interface is supplied by a formatCheck() method on every info.odma.practical100.OdmInterface implementation.   This approach has an OdmFormatCheck interface available anywhere that a practical100 interface is available for use, and the filtering applies to the string parameters of methods of that interface in its current state.
    
• info.odma.practical100.OdmConnection.FormatCheck() will deliver a null OdmFormatCheck implementation whenever OdmInterface.available() is false.  The requirement that an ODMA Connection Manager be available allows for possibly-different implementations of parameter-format filters depending on the way an OdmConnection is implemented.  All null implementations are the same (and are supplied by practical100).
     
• A formatCheck() implementation will cache a single implementation that will also be used with all subordinate interfaces (e.g., OdmWorkingDocument) delivered by connection methods and by subordinate-interface methods.  So there is at most one implementation each of a null and a non-null OdmFormatCheck interface under a single OdmConnection implementation instance.  [updated 2007-11-10 The practical100.OdmNull interface now delivers cached implementations so that it will be rare for more than one of each being instantiated under a single connection.]
    
• The 0.59 version of the info.odma.practical100 package introduces info.odma.practical100.OdmFormatCheck and provides a cached null implementation in all practical100 implementations of OdmInterface.
     
• The 0.59 version of the info.odma.odmjni100 package introduces a non-null implementation of OdmFormatCheck that is cached in any interface implementation so long as OdmInterface.available() is true.  Once OdmInterface.available() is false, the standard practical100 null implementation is delivered.
     
• Warning: It is permissible for each OdmConnection and OdmDocument implementation to have a different OdmFormatCheck implementation so long as the interface contract is preserved.   It is wise to always use the OdmFormatCheck interface of the same interface that a parameter is to be submitted to.  [updated 2007-11-10]

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.

• All "throws OdmError" clauses are removed from the declarations of all constructors and methods where this result is solely a consequence of string-parameter format checks.
    
• All implementations will verify the format of string parameters.  If a parameter is not well-formed, the requested operation will produce an appropriate null result, as specified in the documentation of each interface and of each class for binding connections.

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. 

• The 0.59 version of info.odma.practical100 will eliminate throw operations and provide the necessary null results in its null implementations.  (See section 2.2 for related null behavior.)
    
• The 0.59 version of info.odma.odmjni100 will eliminate throw operations.  Individual operations will also rely on the internally-held OdmFormatCheck interface to verify string-parameter formats and provide null failure results in place of thrown exceptions.

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

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 Consequences.  Norman.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 Interfaces.  Ayende 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.
  

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.

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 $