[jdom-interest] Push toward a 1.0 API

[Jason Hunter]

I think we're at a good point now where we can, with just a little push,
define the JDOM 1.0 API.  There may be a little work after that point to
have it fully implemented, and we're going to have to run through the
JCP process, but I don't see any API issues outstanding that would keep
us from defining the 1.0 API.

I've setup in the TODO.txt file a new category at the top called, "API
CHANGES FOR 1.0".  Below is the list as of today.  We start with the
easier stuff.


* Should CDATA be a flag on Text or a subclass of Text?

Currently CDATA is a Text subclass.  Noam raised this issue he'd prefer
it be a flag on the Text class.  No one else has piped up yet.


* Deprecate all XMLOutputter setIndent methods except setIndent(String).

elharo just raised this one, and he's right we need to address it.


* Rework SAXBuilder exception strategy, throwing IOEx when an underlying
IOEx
  is raised instead of wrapping it in a JDOMEx.

Another from elharo today.  Also should be addressed.


* Finalize the XPath class interface.

I haven't seen any feedback since checking in the class.  Are people
generally happy with the API?  


* Add methods to recursively get content and get filtered content.

Brad's been working on this one.  The idea is to have something like
doc.getIterator() and doc.getIterator(filter) to walk the entire tree
using the Iterator or ListIterator model.


* Figure out how to deal with XMLOutputter writing of special characters
like
  &#160.  Should it char escape only chars unprintable in the current
  character set?  Should there be a fancy API for selecting what's
escaped?
  Should this be something where you can subclass?
 
http://lists.denveronline.net/lists/jdom-interest/2001-February/004521.html
 
http://lists.denveronline.net/lists/jdom-interest/2001-April/005644.html
 
http://lists.denveronline.net/lists/jdom-interest/2001-April/005649.html
 
http://lists.denveronline.net/lists/jdom-interest/2001-April/005669.html
  Brad Huffman has a good proposal.

Brad also had a proposal for this one.  He sent me a set of sample
classes that I need to check out and will share with the list.


* Look at where Namespace may need to be synchronized or made no longer
a
  flyweight.  See
 
http://lists.denveronline.net/lists/jdom-interest/2000-September/003009.html
  and follow-ups.

No one's ever reported a problem here, but there may be a risk of
threading issues that could affect our design.  I welcome the various
gurus out there to take a look and see what they think of the Namespace
threading risks.  Otherwise we can punt on the assumption that no
problem report in years means no problem.  (that's guru bait)


* Look into how the factory builder model could support giving the
factory
  extra knowledge about the context (line number, element stack, etc),
and
  allow it to report errors or to return a code indicating the element
should
  be ignored.

Laurent had some ideas on this that I need to look into and share with
the list.


* Make sure that JDOMException is compatible with JDK 1.4 nested
exceptions.
  E.g. should getNestedException find 1.4-type nested exceptions? Do
both
  1.4-type nested exceptions and JDOMException both try to print child
  stack traces, causing them to be printed twice?

Now that 1.4 is out, we need to identify if there are any issues here. 
Alex, you were working on this as I recall.  Where did you leave it?


* Figure out if there's a role for a Node interface.  It sounds easy but
all
  attempts so far have hit obstacles.  Amy Lewis talks about it here:
 
http://lists.denveronline.net/lists/jdom-interest/2000-December/004016.html
  There were many follow-on threads.

Brad seems optimistic he's found something good here, so we'll see what
he comes up with.  I don't think it'd cause large-scale changes.


* Consider moving JDOMFactory to org.jdom.

This may be where it rightfully belongs, plus it allows a special
factory to avoid the Verifier costs associated with builds.


* Make sure we have a story for serialization.  How much work is it to
support
  serialization across current and future JDOM versions?
  See "serialVersionUID" thread especially Peter V. Gadjokov's remarks
at
 
http://lists.denveronline.net/lists/jdom-interest/2000-September/subject.html
  It may be OK to worry about fast short-term serialization only.

Personally, I don't think we need to worry about long-term
serialization.  That's what XML is for.  When you send XML over the wire
and care about extensibility in the future, you should send it as XML
and not as a Java-based serialized copy of the document.


* Look into in-memory validation

This is something we don't need in 1.0, but which may sneak in.  Allen
Holub said he could help us here.


Are there any other API issues people want to make sure get addressed
before the 1.0 API is defined?  Now's the time to speak up.

-jh-