[jdom-interest] Status update and request for comments

[Olivier Jaquemet]

Thank you for the detailed rational behind validation deprecation, and 
alternatives.
I had seen the setValidation() javadoc, but I did not spotted the 
package summary, my bad

> 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? 
{{ Digging in vcs history.... vcs history incomplete... failure to find 
proper explanation... damn developpers... myself included... }}
If i recall correctly, we introduced this behavior 6 years ago to fix an 
incompatibility of our webapp in some app servers which were bundled 
with other non working parser (probabley WebSphere and its outaded 
libraries such as jdom beta7 and other oldies... not certain of 
that...). So we wanted to make sure we were using the certified xerces 
version we had bundled in our app and nothing else.
This might not have been the best way to do deal with this issue... and 
a proper configuration of the appserver classloader and other properties 
might have been much better... but I don't remember :/
But this is the general idea : ensuring that the code runs with the 
certified parser.

> I meant to ask... what Unit tests passed?
Ours, including many related to XML manipulation using JDom (though with 
quite basic usage, some tricky namespace and xpath, but not anything 
really challenging).

> Now, the real question is whether the 'old' methods should be marked 
> as 'deprecated', or left as 'active' and 'supported'.
> [...]
> Thoughts?
I am definitely for the all deprecated solution, it will make a cleaner 
and homogenous JDOM API, and we certainly be easier to maintain on the 
long term.
Until those API are removed in JDOM3, we can perfectly live with the 
deprecation warning, or migrate our code to the new XMLReaderJDOMFactory 
/ XMLReaderSAX2Factory. As long as the documentation explains the 
alternative (and it does), this is perflectly fine !

Just another though regarding naming of "XMLReaderSingletons", I think I 
would have better understood its behavior with another name. It is an 
enum, so it's quite obviously a singleton and its member too. I think 
"XMLReaders" would be a fine name :)
http://stackoverflow.com/questions/3069743/coding-conventions-naming-enums
My two cents ;)

Regards,
And thanks again for the great work !




On 15/12/2011 15:37, Rolf wrote:
> 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
>>
>>
>
>

-- 
Olivier Jaquemet<olivier.jaquemet at jalios.com>
Ingénieur R&D Jalios S.A. - http://www.jalios.com/
@OlivierJaquemet +33970461480