[jdom-interest] JDOM2 Update

[Rolf]

Time for another update

The test-harness has been steadily growing. The numbers are interesting 
to track... (obviously, quality is what counts, but the numbers are 
interesting anyway).

More importantly, though, at least 13 bugs were identified in the code 
so far as a result of the newly implemented tests. Additional issues 
have been identified as well.

Some issues are not yet resolved.

Back to the numbers...

JUnit tests have gone from 179 to 630 (or so, I have some uncommitted 
tests in my copy).

Code coverage is an interesting metric. There are two measures, one is 
the % of lines of code which were run/tested. The second is the % of the 
number possible code-paths that were taken in the code (including the 
'obvious' if, while, for type conditions, as well as the more complex 
throws and try/catch/finally blocks).

On their own they are useful metrics, but they are also somewhat 
unreliable, because some lines of code can never run, or some exceptions 
are never thrown. For example, the Content.clone() method is:

      public Object clone() {
          try {
              Content c = (Content)super.clone();
              c.parent = null;
              return c;
          } catch (CloneNotSupportedException e) {
              //Can not happen ....
              //e.printStackTrace();
              return null;
          }
     }

In the above code, the catch block is impossible to test (super.clone() 
is Object.clone(), and as a result, the return null; line never runs.

Thus, 100% coverage of Content is not possible.


With that being said, the classes in the org.jdom2, org.jdom2.filter, 
org.jdom2.input and org.jdom2.output packages are now 'fully' covered by 
the jUnit test cases.

The org.jdom2.adapters package is hard to test, because it requires 
loading up all the various parsers (crimson, oracle v1, oracle v2, etc.) 
and that needs some discussion...

The org.jdom2.xpath package has some issues....

I have not started the org.jdom2.transform package yet...

At this point then, counting the core, filter, input, and output 
packages, we are at 94.5% line coverage, and 94.1% of the code path 
coverage.

I don't believe there is much more that can be done in the code to 
increase those numbers.

The start-point numbers for the same packages were 48% line and 43%

Additionally, the adapters, xpath, and transformer packages account for 
'only' 11% of the code.



What this all boils down to is that by the end of this week I expect 
that we can start working on the actual JDOM2 features we all want. 
Hopefully there are some good ideas out there for what features people 
want added to the list.... which, for the moment is reflected in the 
'issues' related to the JDOM project at: 
https://github.com/hunterhacker/jdom/issues?sort=created&direction=desc&state=open&page=1

Additionally, progress has been made in back-porting a number of fixes 
to the jdom-1.x branch. This is getting ready for a release at some point.

I am still looking for some Maven experts to step up and help in that 
process.

Rolf

On 08/08/2011 9:47 AM, Rolf wrote:
>
> Hi Everyone.
>
> Just to bring everyone up to date with JDOM2.
>
> The current plan is described on the wiki page:
> https://github.com/hunterhacker/jdom/wiki/JDOM-2.0
>
> The initial steps are described as:
>
>     1. Migrate the code from CVS to GitHub (keeping all the history).
>     2. Create a branch for 2.0
>     3. Do the basic package renames.
>     4. Fix the test case that's currently failing
> (test_TCM__void_setExpandEntities_boolean)
>     5. Upgrade the JUnit libraries and tests
>     6. Use Cobertura to build up the JUnit test cases to get much better
> coverage of the junit tests on JDOM (currently have only got 40% coverage
> of the org.junit code from the JUnit test cases....). Fix any issues that
> arise in untested code.
>     7. Modify the core code and the test harness together to implement the
> changes - document what changes are made so that we can get a list of rules
> for migration from JDOM 1 to JDOM 2.
>     8. Confirm any deviations from 'compatibility' with the jdom-interest
> list to ensure that all changes are reasonable.
>     9. Complete the migration, ensure all JavaDoc is complete. All Tests
> are run, and code test coverage is 'complete'.
>
>
>
> The initial preparation steps (set up github, branches, basic package
> rename, etc.) are done. See JDOM's new home at
> https://github.com/hunterhacker/jdom
>
> What that means is that the current JDOM2 state is:
>
> JDOM2 looks exactly like JDOM, except it has a new package name, and all
> the JUnit tests now are based on JUnit 4.8.2.
>
> In order to have a clear and documented migration path from JDOM to JDOM2
> we need to know and document all significant changes in the API.
>
> The most comprehensive way to do that is to ensure that the current JDOM
> is well covered with unit tests, and that as we perform the JDOM2
> migration, we ensure that all unit tests pass, and if there are any reasons
> to change the API, the unit tests get modified to adapt, and the deviation
> is documented.
>
> In other words, in order to have the best possible JDOM2 it's important to
> ensure that JDOM itself is very well covered for regression tests.
>
>
> This is where JDOM2 is at the moment: building JUnit tests basically for
> JDOM 1.1.1
>
> No work will be done on any 'generics' or other API modifications until
> the JUnit tests have adequate coverage for regression purposes.
>
> In order to track the progress of the regression testing, the tool
> 'Cobertura' is being used to track the JUnit code coverage, and there is an
> ant target 'coverage' that will do that for us.
>
> Currently the core JDOM code has about 40% coverage. This number should be
> better than 95% before any real 'fun' work can begin.
>
>
> My expectation is that the JUnit coverage will probably amount to about
> half of the real work of the JDOM2 process.
>
>
> In light of the above, this is also an invitation for assistance in doing
> the hard work of building the best and most comprehensive testing we can.
>
> Once that is done we can get on with the fun part of doing the actual
> migration (with the security of the unit tests to keep us on track).
>
>
>
> In order to set the expectations for JDOM2, I anticipate that any code
> submission should be accompanied with as comprehensive JUnit testing as
> possible. No changes will be accepted on existing code unless there are
> first JUnit tests for that code. No patches/pulls/commits will be allowed
> if they result in failing tests.
>
>
> In order to facilitate the patching/submission process I am happy to
> accept contributions in any reasonable format.... but, changes should be in
> as small a 'chunk' as reasonably possible though, in order to make merging
> and tracking as simple as possible. All changes will be attributed
> appropriately.
>
> If you intend to get busy writing JUnit test cases, please drop me a note
> so that I can co-ordinate with others writing tests so that there is no
> duplication of effort.
>
> If you have any comments, questions, suggestions, please speak up!
>
> Thanks all, happy coding.
>
> Rolf
> _______________________________________________
> To control your jdom-interest membership:
> http://www.jdom.org/mailman/options/jdom-interest/youraddr@yourhost.com
>