[jdom-interest] Status update and request for comments

Thu Dec 15 06:37:25 PST 2011

Hi Olivier

Thanks for the play-time and the feedback.

First, the deprecated setValidation(). I think I was perhaps 
over-zealous to mark it deprecated.... perhaps... but I am not sure. In 
the new JDOM2 world I don't particularly want people using that 
method.... nor the 'boolean' constructor (nor for that matter using the 
sax-parser class-name constructor.

In JDOM2 I introduced the XMLReader*Factory classs/enum. For more 
information on the SAX Parsing changes see the 'package' JavaDoc: 
http://hunterhacker.github.com/jdom/jdom2/apidocs/org/jdom2/input/sax/package-summary.html

The motivation is because it is 'naive' to only have a 'boolean' setting 
for XML validation.... in the 'new XML world' (since 200x) there are all 
sorts of ways to validate XML, and DTD is only one of them. So, JDOM2 
keeps setValidation(boolean) for backward compatibility.

The constructor:

SAXBuilder mybuilder =
      new SAXBuilder(true);

should be replaced with:

SAXBuilder mybuilder =
      new SAXBuilder(XMLReaderSingletons.DTDVALIDATING);

likewise, the following is 'old':

mybuilder.setValidation(true);

and in new JDOM2 should be:

mybuilder.setXMLReaderFactory(XMLReaderSingletons.DTDVALIDATING)

So, JDOM2 introduces a new 'more logical' way of setting up SAX 
parsing/validation.

Is there any reason why you are not using the JAXP-based mechanism for 
loading a SAX Parser... do you really need to specify the class-name?

If you do, then, in your particular case, a good 'transitional' 
mechanism to use would be the new SAX2-based XMLReaderSAXFactory 
class.... 
http://hunterhacker.github.com/jdom/jdom2/apidocs/org/jdom2/input/sax/XMLReaderSAX2Factory.html

XMLReaderJDOMFactory readerfac = new XMLReaderSAX2Factory(true,
     org.apache.xerces.parsers.SAXParser.class.getName());
SAXBuilder builder = new SAXBuilder(readerfac);

or, alternately:

XMLReaderJDOMFactory readerfac = new XMLReaderSAX2Factory(true,
     org.apache.xerces.parsers.SAXParser.class.getName());
SAXBuilder builder = new SAXBuilder();
builder.setXMLReaderFactory(readerfac);

Now, the real question is whether the 'old' methods should be marked as 
'deprecated', or left as 'active' and 'supported'.

The 'deprecation' message in the JavaDoc is relatively comprehensive... 
http://hunterhacker.github.com/jdom/jdom2/apidocs/org/jdom2/input/SAXBuilder.html#setValidation%28boolean%29

Certainly, if we mark them as deprecated then the constructors should be 
deprecated too.... there is no point in marking just the setValidation() 
method.

I think my preference would be to mark the methods/constructors as 
deprecated, but that could make for a messy 'transition' as you have found.

On the other hand, if I update the documentation, and people 'expect' to 
have to make the change (or live with the deprecation warning) then that 
may be OK too.

Thoughts?

For the moment I am going to leave the deprecation in, and also mark the 
constructors as deprecated. I think that making people aware of the new 
mechanisms is important, and it does not technically 'break' old-style 
code... just messy.

Thanks for the note on the javadoc typo... will fix that.

As for the note on github and 'pull' requests, etc. That's an 
interesting one... I also have to learn about git more before I am fully 
capable of managing multiple 'source' repositories.

For now it is just fine to mail the list with concerns, and I can apply 
and 'push' the changes from my local code drop.

I anyone has bigger changes to submit then we can learn that together, 
when it happens.

So, to-do:
deprecate 'boolean' SAXBuilder constructors - in favour of 
XMLReaderSingletons.DTDVALIDATION
deprecate SAX-Driver-class-name constructors - in favour of 
XMLReaderSAX2Factory
fix 'me' typo in Javadoc for setValidation()
update the 'migration' wiki page for suppress-warnings
update migration page for deprecated methods.
wait for additional input on over-zealous deprecation ... ;-)

Thanks!

Rolf

On 15/12/2011 7:17 AM, Olivier Jaquemet wrote:
> Hi Rolf
>
> Tested with our code based :
>
>   * all unit-tests passed.
>   * generics works great :
>     We had long anticipated the time were JDOM would support it and were
>     already using generics collections, with code such as :
>     @SuppressWarnings("unchecked"),
>     List<Element> elmList= elm.getChildren("foo");
>     I simply had to remove the suppresswarnings everywhere and it worked
>     like a charm. Great job !
>
> I am a little bit confused with the deprecation of method
> SAXBuilder.setValidation()
> Method is deprecated, but there is still a non deprecated constructor
> receiving boolean validate :
> This this code compile without warning:
> SAXBuilder builder = new
> SAXBuilder(org.apache.xerces.parsers.SAXParser.class.getName(), true);
> This code generated warning :
> SAXBuilder builder = new
> SAXBuilder(org.apache.xerces.parsers.SAXParser.class.getName());
> builder.setValidation(true);
>
> Also note there is a small typo in javadoc for SAXBuilder.setValidation() :
> method provides a means to *me* more specific about validation
> I tried to fork the project on github to submit a pull request, but I am
> not enough familiar with git yet, and unfortunately do not have time to
> dig further for the moment.
>
> On 14/12/2011 18:43, Rolf wrote:
>> Hi all.
>>
>> Having just come through a crazy few weeks at 'real' work, and sorting
>> out a few other 'christmasy', and 'life' issues, I now have some
>> significant time to throw at JDOM and to make some real progress. Now
>> is also a good time to summarize and consolidate where things are.
>>
>> I am also looking for feedback and criticism of the new code. I know
>> that there have been some people playing with the code:
>> https://github.com/hunterhacker/jdom/downloads ... how is it working
>> out for you?
>>
>> If you have not yet had a look, please check out the wiki pages:
>> https://github.com/hunterhacker/jdom/wiki/JDOM-2.0
>>
>> The original objectives of the JDOM2 project are close to complete. To
>> recap:
>>
>> Admin things:
>> - move to github,
>> - package rename to org.jdom2
>> - regression test harness
>> - documentation
>>
>> Required things:
>> - generics
>> - varargs
>> - co-variant return types
>> - enums
>>
>> Corrective things:
>> - XPath factory API
>> - many bug fixes
>>
>> Nice things:
>> - upgraded XPath
>> - upgraded SAX
>> - upgraded Filter concept
>> - namespaces-in-scope.
>>
>> New things:
>> - StAX
>> - JDOMConstants
>>
>>
>> I have tried to keep the wiki pages up to date, for details on all the
>> major functionality 'drives' in JDOM2 please check out the JDOM2
>> Features page: https://github.com/hunterhacker/jdom/wiki/JDOM2-Features
>>
>> Because the major objectives are essentially complete I want to bring
>> the code to an 'official' ALPHA type state. I want to 'finalize' the
>> new API's, to start down the road of getting a final release. I want
>> to put out the 'Alpha' release on Jan 1, 2012. Hopefully it will be a
>> new year resolution I can keep.....
>>
>> JDOM 1.x spent years in 'beta', and I don't want the same thing to
>> happen with JDOM2. Really, there's not that much that's different, so
>> it should not be needed, but I think we have a better idea now of
>> what's important in the JDOM API, so it is not as important to let the
>> API 'settle' as it is 'played' with in the JDOM2 cycle.
>>
>> In other words, I fully expect any 'alpha' and 'beta' releases to be
>> short, measured in weeks, not years.
>>
>> It will have to happen at some point, but I don't want to miss
>> anything out in JDOM2 because JDOM3 is decades away and changing the
>> JDOM2 API will not be an easy option after it goes in to a 'beta' cycle!
>>
>> This all requires participation and feedback... I need to know what's
>> working, what needs improvement, what's missing.
>>
>> If you can take the code for a spin... Apply it to your existing
>> projects. Swap out the jdom 1.x jar you are using, do a search/replace
>> for 'org.jdom' and replace with 'org.jdom2' and tell me what breaks....
>>
>> Read this page:
>> https://github.com/hunterhacker/jdom/wiki/JDOM2--Migration-Issues
>>
>> I am putting together a separate mail detailing the changes I expect
>> to be making in the next week.... and I will want some feedback on
>> that too.
>>
>> Thanks
>>
>> Rolf
>> _______________________________________________
>> To control your jdom-interest membership:
>> http://www.jdom.org/mailman/options/jdom-interest/youraddr@yourhost.com
>>
>
> --
> Olivier Jaquemet<olivier.jaquemet at jalios.com>
> Ingénieur R&D Jalios S.A. -http://www.jalios.com/
> @OlivierJaquemet +33970461480
>
>