[jdom-interest] XMLOutputter naming questions

[Alex Chaffee]

In addition to my patch, I'd like to make a few cosmetic changes to
XMLOutputter.  I thought I'd ask the list if anyone objects to the
following:

- remove setIndenting() -- it's redundant with setIndent() and
confusing to boot.  Why should I have to call setIndenting(true) if I
just called setIndent(" ")?  Likewise, if I call setIndenting(true)
why should I then also have to call setIndent(" ") before any
indenting will happen?

  I'd like the semantics to be 
	setIndent(null) -> no indenting
	setIndent("") -> no indenting
	setIndent("  ") -> enable indenting 

 Is anyone really in love with setIndenting(true)?  (If so, we could
 make it wrap setIndent(" ") or someting sensible.)


- remove the method output(Document, OutputStream, String encoding).
Instead, if people want to output a different encoding, they should
just call
  outputter.setEncoding(foo);
  outputter.output(doc, out);

(of course, that depends on there being a setEncoding method, which I
just added :-)

  this will make the API clearer and the internal logic a little
neater for another improvement I'm adding, namely...


- allow the user to output to either a Writer or an
OutputStream. (Right now it's one or the other -- OutputStream to
print a document, Writer to print an element.)  This would have to be
documented as follows:

 Warning: using your own Writer may cause the outputter's preferred
 character encoding to be ignored.  If you use encodings other than
 UTF8, we recommend using the method that takes an OutputStream
 instead.


- add a method for outputting a string.  This would just wrap the
normal output() in a ByteArrayOutputStream.  Then we can use the same
formatter (and all its options) to output a (document or element) to a
(string or stream or writer).

I'd like opinions on the following naming conventions:

	void output(Document d, OutputStream out)
	void output(Element d, OutputStream out)
	String output(Document d)
	String output(Element e)

versus:

	void output(Document d, OutputStream out)
	void outputElement(Element d, OutputStream out)
	String outputString(Document d)
	String outputString(Element e)

versus:

	void output(Document d, OutputStream out)
	void output(Element d, OutputStream out)
	String outputString(Document d)
	String outputString(Element e)

Note that most of this is written already (on my machine); I just need
advice on the names.  I'm leaning towards the last one (output/output/outputString)

Thanks -

 - Alex

-- 
Alex Chaffee                       mailto:alex at jguru.com
jGuru - Java News and FAQs         http://www.jguru.com/alex/
Creator of Gamelan                 http://www.gamelan.com/
Founder of Purple Technology       http://www.purpletech.com/
Curator of Stinky Art Collective   http://www.stinky.com/