ODMdev: ActiveODMA Development Framework

devNote d070701
 ODMJNI 1.0 Public Beta
0.60 Stable Candidate

ODMdev>devNotes>
2007>07>

d070701e>
0.01 2008-04-23 21:12 -0700


  • Latest version: The latest ODMJNI 1.0 Public Beta material can be found via   <http://ODMA.info/dev/devNotes/2007/07/d070701b.htm>.
  • Previous version: 0.59 Public Transition Candidate <http://ODMA.info/dev/devNotes/2007/07/d070701d.htm>.
       
  • This version: 0.60 Stable Candidate Public Beta 0.01 <http://ODMA.info/dev/devNotes/2007/07/d070701e.htm>.  This release is formed simply by deleting all deprecated elements from the 0.59 Transition Candidate, by satisfying the regression checks, and by declaring the public beta  of stable interfaces for candidate use.  Apart from bug fixes, useful additions, and hardening of the underlying implementation, this API will be preserved for the lifetime of ODMJNI 1.0.
       
  • Downloads: {to be defined}

The 0.60 Stable Candidate is a complete release in which there are no deprecated interface elements.  The elements in the 0.60-level API are those that will be preserved in all future ODMJNI 1.0 releases.   The only changes will be for repairing defects, adding additional features (if any), and hardening the underlying implementation.  Refactoring of the underlying implementation for improved maintainability and easier verification is to be accomplished by later releases that will have no impact on the interfaces exposed for application-software usage.

1. Purpose and Scope
2. Breaking Changes
    2.1 Removal of Deprecated Methods in Viewable, Editable, and Working Documents
    2.2 Removal of Deprecated OdmFormat Class Methods now in OdmFormatCheck Interface
    2.3
3. Development Approach
    3.1 Summarize Changes
   
3.2 practical100 Changes
   
3.3 odmjni100 Changes
   
3.4 Packaging of 0.60 Beta
    3.5 Additional Materials for Adopters
4. Bugs and Caveats
5. Developer Notes

1. Purpose and Scope

{tbd}

2. Breaking Changes

2.1 Removal of Deprecated Methods of Viewable, Editable, and Working Documents

{tbd}

2.2 Removal of Deprecated OdmFormat Class Methods Now In OdmFormatCheck Interface

{tbd}

3. Development Approach

3.1 Summarize Changes

3.2 practical100 Changes

3.3 odmjni100 Changes

3.4 Packaging of 0.60 Beta

3.5 Additional Materials for Adopters

4. Bugs and Caveats

5. Developer Notes

2007-12-02-10:04 The Problems of Building to a Quality Release
Apart from just being a slow worker, I also find it very tedious and taxing to be on the homeward leg of the ODMJNI 1.0 Development.  From a technical point of view, 0.60 is intended to be a stable, usable-in-production release.  The only code updates will be for the coordinated use of the same parameter-format checking in odmjni100 as in OdmNative100.  The only tricky spot, at the moment, has to do with the proper behavior of transferToNewDocument when the DMS returns success and no new docId.
    But 0.60 is not a polished release, and that is why it is called 0.60.  There is much work required to provide the improved packaging, documentation, and worked examples to make ODMJNI 1.0 a dependable open-source description.  This will all happen after 0.60 is available, in a series of supplements that accompany the movement of the code base to the ActiveODMA project on SourceForge.  That takes us to 0.70.
   The 0.70 release is all about deployment packaging.  This may be a slim activity based on how much is going into it now, or I may realize that I am attempting too much up front and can accelerate 0.60 release because is this provision for 0.70.
   Later on, when 0.70 is declared, there will also be a major refactoring of the internal implementation.  This is required to not disrupt applications that use ODMJNI 1.0 in any way whatsoever.  The reason it is out there at 0.80 is precisely because we want all of the tools and tests and definitions in place to provide good assurance and confirmation that no regression has occurred and nothing is broken. 
   That's why "hardening" is an 0.90 activity, because we want to do the most strenuous hardening activity against the refactored code base. 
    And finally, the 1.0 stage doesn't happen until all code is signed and certified in some way. 
    Now you know why this seems like such a long and tortuous progression, when the code starts out being stable enough to rely on in production (with good precautionary testing) at 0.60.
    I was reminded of this by Oren Eini's blog post today.
    see also: Oren Eini: Releasing Open Source. Ayende @ Rahien (web log), 2007-12-02.
  
2007-11-27-18:40 Bugs and Caveats Needed
There may still be known bugs or at least caveats for 0.60, in addition to the breaking changes.  Some of these will be about the shallow level of testing and the poor automation, missing and inadequate documentation, etc.  I am anxious to get a clean 0.60 laid down and downloadable.  It may well be that surrounding materials, especially improved confirmation tests and documentation comes after the code is available.  Other materials can come out of the build-up of a stable deployment process that includes presence under the SourceForge ActiveODMA project.  Completion of that, and any documentation-related build (maybe for JavaDoc) will culminate in 0.70, a release that can be reached more-or-less at leisure.  I do want to be at least defining the 0.80 refactor by the time of the AIIM 2008 meeting in early March, though.
   I am willing to get the code flat and then see what is revealed by more testing and any take-up for other Java-based applications.  If there are bugs to fix, 0.6x releases can be made.
   
2007-11-21-20:27 Narrowing in on 0.60 Definition
The easiest changes to make for 0.60 consist of deleting all deprecated methods from the Java code of practical100 and odmjni100 and verifying that the regression checks all pass.  This may actually catch defects in the 0.59/0.60 regression checks, but if everything compiles with the changes made, there should be great confidence in that result.
   There are two other changes that are required.  The first consists of the implementation of native string format-checking code in OdmNative100.lib and introducing an OdmJniFormat extension of OdmNullFormat that uses Java native methods to access those library functions.  This is done now to stabilize the behavior and to catch any discrepancies in production usage as early as possible.
   The second change has to do with stabilizing the implementation of transferToNewDocument and having applications informed that the original working document is to be used to save any new content.  This is a breaking change and it needs to be put in here. 
    I'm now confident that this is the extent of the modifications required for 0.60.  I am willing to do all further refinements, including addition of documentation, improvement of web pages, release notes, examples, more confirmation tests, and so on, in the interval to 0.70 and even up until 0.80 work starts.  That will again make major changes to odmjni100 and to OdmNative100, but these should not have any impact on the productive use of ODMJNI 1.0 starting with 0.60.
   If there are any requirements for bug fixes, we can consider 0.6x and 0.7x intermediate drops with fixes.
  
2007-11-18-19:17 Cleaning Up transferToNewDocument
I haven't checked the behavior with ODMASAMP yet, but I suspect that transferToNewDocument misfires if a DMS does not return a new docId as part of its successful response.  This means, according to ODMA 1.0 and all later specifications, that the existing DMS document should be used.  This means that there should be a save to the current docLocation, if there are any changes to be committed. 
   The only way I can distinguish that for an application is to give it a successful OdmPendingDocument interface that has a null docLocation, indicating that the existing working document should be used, and any new content should be saved to that document via commitChanges.
   I'm satisfied with that resolution but I need some reality checks.  First, what happens now, secondly does ODMASAMP provide a reliable behavior that I can check?  Finally, what do other applications do?  In particular, I can see what Microsoft Word does, that being an important and useful indicator.
  
2007-11-17-19:48 Worrying About Binding Mismatches
In C and C++, it is easy to use header files that do not match the .lib or the .dll that is actually bound to at another stage or at runtime.  There are practices that avoid this, and the use of interface identifiers (IIDs) is also very helpful in maintaining of the agreement between a header file used in compiling and the code used at run-time.
   One problem I have with the way OdmFormatCheck works is that OdmNative100 interfaces and class loaders must defend themselves with format checks and these checks might be inconsistent with the filters in OdmFormatCheck.
   For 0.60, I want to solve this problem by having the OdmNative100 code that is run by odmjni100 native methods and the odmjni100 implementation of OdmFormatCheck use the identical implementation.  That will be done.  It is the only new code in 0.60, but it is important to get that into the deployed software.
   I had it in my head that I needed some way to check, at runtime, that OdmNative100 was using the same format-checking code that the odmjni100 native methods in support of OdmFormatCheck were also using.  I figured I needed to use some sort of common key (such as an IID) by which odmjni100 told OdmNative100 what format checking code was being used.
   I finally got to the idea that I might as well make the OdmNative100 format checking code have a COM interface except then it wouldn't be useable from static methods, and it appeared that static native methods would be good enough on the Java side.
   If I'd drawn a diagram I might have seen more quickly what a waste of time this worry is.  The odmjni100 native methods are implemented via a single odmjni100.dll and odmjni100.cpp file.  The compilation of odmjni100.dll uses an OdmNative100.lib.  All I have to do is make sure the format-checking code that OdmNative100 is bound to be in that very library.  Then odmjni100 will be bound to that same code and so will the OdmNative100 implementation that is bound by the odmjni100 code.  It is easy.  No worries.  I might need to deal with binding checks and binding matches somewhere else in the future.  Not here.
  
2007-10-25-17:53 Regression Tests Targeted for 0.60
In the creation of 0.59/0.60 regression tests from the existing pre-0.59 checks, I am changing them only enough to avoid deprecated 0.59 elements.  That leaves serious gaps in test coverage, especially of failure cases and format-checking consistency between odmjni100 and OdmNative100.  Those checks important for an assurance that 0.60 is stable for use will be added for the 0.60 release with more-comprehensive checks added along the way to 1.00.
   I am not sure whether the gaps will be catalogued here or in a separate folio devoted to testing.  The second option may be more appropriate as a way to focus attention all the way through ODMJNI 1.0 and to the point where fully automated end-to-end tests can be provide as part of overall ODMA hardening.
    
2007-10-08-14:00 Concern About Test Coverage
I wonder how to get better coverage and better regressions.  One thing to do is to have notes pages up for future stages so that I have a place to record concerns that are intended to be resolved no later than that point.  I also need a practice of reviewing the developer notes.
  
2007-09-29-17:03 Careful Provision for Variants
To implement variants the way I describe, just below, I must be careful that the practical100 and odmjni100 classes can be derived from in useful ways, while also maintaining the separation of concerns and other features around least surface for confined usages.  I think the use of practical100 by odmjni100 is cause for confidence in the building of variant interfaces and implementations atop the practical100 interfaces and null implementations. 
   It may take additional care to allow for variant derivations atop odmjni100 classes as well.  I will have to watch that and make sure that some of the access conditions are not so strict that variants in supplemental packages cannot be added in this way.
  
2007-09-29-15:22 Safe Ways to Build Synchronized Variants
ODMJNI 1.0 is a kit, and people are encouraged to make their own variants (just so they are not called ODMJNI m.n).  Then, in order to be able to stay synchronized with any additions and especially any defect repairs and improved implementations, how does one do this in a safe way that does not create a maintenance headache for the variant.  My thinking is that the way odmjni100 classes derive from practical100 classes is an useful model.  Variants should derive from those and rely on their implementations as much as possible. 
   I think this is an useful model for those who want to extend ODMJNI for improved integration with their applications and use of ODMA. 
   This is not a fool-proof approach, but I think it retains the greatest flexibility for synchronizing with ODMJNI repairs and improvements that follow creation of a variant.
  
2007-09-29-12:21 No 0.6x Releases Intended [from notebook #59.38]
My idea is to save 0.6x releases for breaking changes.  If I have to do that, then I can't just issue a new build of 0.60.  If there are other defect repairs, including comments and documentation corrections, I am thinking that will involve a replacement 0.60 build.  This is a little odd, so I will start making builds part of the release version.  That is, the first archive would be identified 0.60.00, and so on. 
   [dh:2007-10-10 The introduction of documentation, examples, and more tests might be worth making an 0.6x drop, but I don't think it needs to be done as a bundle like that.]
   
2007-09-23-15:05 Get to 0.60 as Stable with No Further Breaking Changes (from 0.59 notes)
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-17-21:00 Use the Idea of Stable Open Beta for 0.60 (from 0.59 notes)
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.]
  

Attribution:
Hamilton, Dennis E.
ODMJNI 1.0 0.60 Stable Candidate Public Beta.   AIIM ODMA Interoperability Exchange, ODMdev Development Note page d070701e 0.01, October 25, 2007.  Available at <http://ODMA.info/dev/devNotes/2007/07/d070701e.htm>.
Revision History:
0.01 2007-10-25-18:31 Adjust Around Regression
Added placeholder for Bugs and Caveats and indicated that there will be additions for gaps in the regression checks.
0.00 2007-10-10-16:31 Provide Placeholder
This page is put up as a placeholder for holding a sketch and notes on the 0.60 public-beta release that is being envisioned to follow the now-in-development 0.59 release.

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-10-10-16:31 -0700 (pdt) by orcmid
$$Author: Orcmid $
$$Date: 08-04-23 21:12 $
$$Revision: 22 $