ODMdev: ActiveODMA Development Framework

devNote d061001
 info.odma.practical100 Component Development
0.56beta Evolutionary Development

ODMdev>devNotes>
2006>10>

d061001g>
 0.11 2008-04-23 21:11 -0700

  • Latest version: The latest  info.odma.practical100 components are at <http://ODMA.info/dev/devNotes/2006/10/d061001b.htm>.
  • Previous version: 0.30alpha  <http://ODMA.info/dev/devNotes/2006/10/d061001f.htm>.
  • Next version: 0.59beta <http://ODMA.info/dev/devNotes/2006/10/d061001h.htm> is the transition candidate that will provide a half-step toward 0.60beta with all breaking changes identified.
      
  • This version:  0.56beta Evolutionary Development 0.11 <http://ODMA.info/dev/devNotes/2006/10/d061001g.htm> consists of  material that is intended for the practical100 release candidate.  Future changes were to be limited to documentation formatting changes (e.g., for JavaDoc) and repair of defects.  There may also be some tightening of parameter-format filtering before 0.60beta.  [This objective is amended in the 0.59beta work.]
      
  • Downloads: The material of the 0.56beta Evolutionary Development is provided in four files:
    1. d061001g-license.txt 0.00 version, 3,215 byte file dated 2007-02-23-12:16
    2. d061001g-ReleaseNotes.txt 0.07, 14,562 byte file dated 2007-03-10-23:30
    3. d061001g.txt 0.04 Manifest of the 0.56beta package, 10,335 byte file dated 2007-03-10-23:43
    4. d061001g-practical100-0.56beta.zip 0.04 Archive of the 0.56beta Material, 37,623 byte file dated 2007-03-10-23:44.  The license, release notes, and manifest are included.  Review the manifest to determine whether it is desirable to download the complete archive.
        
      WARNING: Versions 0.00-0.03 of the 0.56beta archive are obsolete.  They must be replaced by an 0.04 or later archive to work properly with the 0.57beta release of the odmjni100 package.  Changes in 0.04 correct a serious defect in OdmFormat.wfDocIdPrefix.  In addition, there are minor adjustments to the manifest and ReleaseNotes.

Synopsis

1. Objectives

The ODMJNI 1.0 0.56beta distribution is provided to accomplish six important steps in the progression to full ODMJNI 1.0:

  1. Begin clean-up and improved documentation of the practical100 package in anticipation of interface freeze and initiation of the initial-public 0.60beta release.
       
  2. Repair any defects noticed during usage of the practical100 package as it has existed since the 0.30alpha iteration.
       
  3. Introduce the info.odma.practical100.OdmFormat class and static methods for verifying the format of text data elements.  This allows verification of parameters to practical100 interface and class implementations without submission to, and summary rejection by, an implementation.
        
  4. Enable active filtering of parameters in the null implementations within the practical100 package. The encounter of any ill-formed text element will result in an unchecked OdmError exception as specified in the definition of practical100 behaviors. 
       
  5. Increase the test coverage of null implementations by providing more coverage of all paths that are possible under null conditions. (The testing of all of the filter and exception cases isn't complete until 0.60beta.  In particular, the 0.56beta changes do not make any modifications to the odmjni100 package, which must only undergo a regression check.)
        
  6. Perform regression against the 0.54beta odmjni100 implementations to ensure that the introduction of validations does not interfere with the valid format usages with existing odmjni100 classes and tests.  Because the odmjni100 package classes use practical100 null implementations for base classes, some parameter filtering will occur via inheritance.

2. Bugs and Caveats

Versions of the OdmFormat Document ID methods had a serious defect in packages prior to 0.04.  The bug was such that OdmFormat.wfDocIdPrefix and all other methods that relied on it (prefixDmsId, wfDocId, and safeDocId) would fail for all Document ID strings, well-formed or not.  This bug is repaired in package version 0.04.

3. Change Summary

This version of the info.odma.practical100 package introduces the OdmFormat class and its use within the practical100 package. 

All changes are backward compatible with the final 0.30beta version of practical100.  This package should work in all previous settings where the 0.30beta components are usable.  0.56beta is a cumulative roll-up of all practical100 changes to date.  It may be used with any ODMJNI 1.0 release from 0.25alpha to 0.56beta and beyond. 

There are some implementation changes and new classes and methods.  The contracts for existing classes and methods are honored fully.

These are the change highlights:

4. Development Approach

The development consists of the addition of validation operations and confirmation that the validations are being used properly (exceptions are thrown) and that the validations do not disturb any of the code that is known to be using well-formed data.  More rigorous coverage tests will come later.

OdmFormat is first implemented with all-null behaviors: the filters always return false regardless of the operand. Verification using the filters is added at all of the appropriate places in the practical100 null classes.   This will automatically confirm that OdmError is being thrown and what that looks like.

After this case, and after each subsequent change, we run a version of the practical100\test\Null01 which we will be improving as we go.

After each confirmation with Null01 and its improvements, we also run a regression on odmjni100.  The test programs for odmjni100 may or may not reveal any sensitivity to these changes.  Whatever sensitivity there is should come from the use of class inheritance from practical100 null classes.  In general, there should not be any need to make odmjni100 repairs, but there may be a list of changes that are warranted when odmjni100 is updated for 0.58beta.

The filters are given non-null implementations in the following sequence:

That concludes the basic development and confirmation.  There is no internal practical100 usage of the wfDocIdPrefix, prefixDmsId, and safeDocId methods.

5. Developer Notes: Working toward 0.56beta

if (docId.length() > MAX_DOCID_LENGTH) return false;

return wfDocIdPrefix(docId);

Basically, there must be a valid prefix, but any Unicode UTF-16 codes are permitted after the prefix so long as the length restriction is satisfied.  This is a simple way to do it, but it is far too relaxed about what can come after the prefix.  To improve on this, I went to the following approach in the 0.00 release of the 0.56beta archive:

if (docId.length() > MAX_DOCID_LENGTH) return false;

if (!wfDocIdPrefix(docId)) return false;

for (int i = ODMPREFIX.length(); i < docId.length(); i++)

    {   char code = docId.charAt(i);
        if (code < ' ' || code > '~') return false;
        }

return true;

This is the version that was settled on for archive version 0.00.  The idea is to only allow the printable graphic codes of the Unicode Basic Latin character set.  These are essentially the printable ASCII or ISO 646 codes.|
  
In all cases, the constant ODMPREFIX is the string whose value is the seven characters “::ODMA\” that was already verified in wfDocIdPrefix, along with the following DMS ID and another “\”. 
  
Now, this version although very safe (but not so safe as safeDocId), it more restrictive than the ODMA 2.0 specification requires of DMS integrations.  The one risk of this particular filter, is that it will reject ODMA Document IDs that were legitimately produced by a DMS. 
  
I have placed restrictions in wfAppId and wfDocFormatName that are stricter than required by ODMA.  But these are restrictions imposed on new Java applications, not on any existing applications, and I can argue that the added safety and utility of the restrained forms is part of the practical100 contract.
  
In considering the newly-introduced 0.57beta release, I concluded that the most effective solution is to use the translatability of the docId string to the single-byte codes of the default Windows ANSI code page to be the ultimate requirement for characters following the prefix, including the DMS ID.   I can't implement that in Java alone, I need to use JNI code for that.  In the 0.56beta, I can't be that tight, but I can relax to a point where all such strings will pass through, even though strings that don't translate will also be passed, for now.  When 0.58beta substitutes JNI implementations of filters used by both practical100 and the rest of the ODMJNI 1.0 implementation, the thrown exceptions will reject exactly the strings that will lead to silent failures in odmjni100 JNI code.
  
This is the first form I entertained for the 0.01 archive update was the original version considered for 0.00, above.  The problem with that is that it still permits far more than is ever intended to be acceptable.  It is also so permissive that known control codes are passed and must be filtered out by supplemental code in 0.57beta.  So I finally settled on this version:

if (docId.length() > MAX_DOCID_LENGTH) return false;

if (!wfDocIdPrefix(docId)) return false;

for (int i = 0; i < docId.length(); i++)

    {   char code = docId.charAt(i);

        if (code < 0x20
                || (code > 0x7e && code < 0xa1)
                || code == 0xad
                )
             return false;
             /* XXX: Although the non-break space (0xa0) and
                     the soft hyphen (0xad) are technically not
                     control characters, their allowance in
                     Document IDs would be pernicious.
                     */
        }

return true;

This version rules out the C0 and C1 Control Codes (and two more) of the first 256 Unicode UTF-16 values.  We can't reject more without knowing the code page, but translatability to the proper code page, without exceeding the length limitation, is all that remains for a precise check.  The idiosyncratic ODMPREFIX usage is also avoided, since those already strictly-checked codes will simply be accepted a second time.

        if (  docId.substring(0, ODMPREFIX.length()-1)
                .compareToIgnoreCase(ODMPREFIX)
              != 0)
             return false;

When I planted some additional output statements into the CheckKnown test code, it became clear that

docId.substring(0, "::ODMA\\".length()-1) == "::ODMA"

and not "::ODMA\\" as expected.  A little digging in the Java API documentation explains what is wrong with my use of the java.lang.String.substring(start, end).  I made a classic beginner mistake in not noticing that end is the position after the end, not the end itself.  That is, docId.substring(0, 0) returns an empty string and docId.substring(0,1) is the string which has docId.charAt(0) as its only character.

The repaired OdmFormat will be included in the 0.04 package and all previous 0.56beta package versions will be declared obsolete.

Attribution:
Hamilton, Dennis E.
info.odma.practical100 Component Development -- 0.56beta Evolutionary Development.   AIIM ODMA Interoperability Exchange, ODMdev Development Note d061001 page d061001g 0.11, September 23, 2007.  Available at <http://ODMA.info/dev/devNotes/2006/10/d061001g.htm>.
Revision History:
0.11 2007-09-23-17:00 Reflect Start of 0.59beta work
The 0.59beta placeholder is linked as the next version.  That page does not have the latest materials at first, but it can be accessed to observe the progression of activity that leads to the availability of candidate materials.
0.10 2007-08-19-15:45 Repaving Complete
All editorial cleanups and repaving-required modifications are introduced.
0.09 2007-03-10-18:04 Create package 0.04 with OdmFormat bug fix
This opportunity is used to correct some minor defects in the transmittal and wrapper material. 
0.08 2007-03-07-16:52 Make Simple Corrections to the Package
It is desirable to use 0.03, which makes small corrections to the manifest and Release Notes.  The software is not changed from 0.02.
0.07 2007-03-07-11:43 Clean up the Revised 0.56beta Packaging
The 0.02 archive version, with related updates, is produced to correct the identification of the OdmFormat.java file and to include class files that are compiled with that version of the file.  The source code and the class files were out of synch in the package.  The descriptions of wfDocId and safeDocId on this page also had to be corrected.
0.06 2007-03-06-18:17 Revise 0.56beta to support 0.57beta
The OdmFormat.wfDocId method is altered to fit with the direction being taken for 0.57beta as an interim step toward 0.58beta where the final OdmFormat methods will be established using native implementations.
0.05 2007-03-04-18:52 Complete Step 10 and make 0.56beta available
0.04 2007-03-03-16:48 Start Steps 9 and 10.
0.03 2007-03-01-21:21 Document through Step 8.
0.02 2007-02-24-21:06 Add Development Approach
0.01 2007-02-23-11:14 Update with Draft Release Notes
The draft notes are linked to the page and additional structure and narrative is provided as accompaniment to the release notes.
0.00 2007-02-21-19:38 Provide Placeholder for Commencement of 0.56beta Development
This page is put up as a placeholder so that the 0.56beta version of practical100 development can be captured.
Construction Structure (Hard Hat Area)
Creative Commons License You are navigating ODMdev.
This work is licensed under a
Creative Commons Attribution 2.5 License.

created 2007-02-21-19:38 -0800 (pst) by orcmid
$$Author: Orcmid $
$$Date: 08-04-23 21:11 $
$$Revision: 50 $