Hi Kohsuke,
Good suggestions.
Kohsuke Kawaguchi wrote:
>
> I think some ofthe XMLStreamBuffer method names can be named better, and
> this is the proposal to change it.
>
> For example,
>
> StreamReaderBufferProcessor processUsingStreamReaderBufferProcessor();
> XMLStreamReader processUsingXMLStreamReader();
>
> should be:
>
> StreamReaderBufferProcessor newXMLStreamReader();
>
> (we don't need two methods that does the same -- it just clutters the
> signature. "processUsing" isn't very obvious what it does. "new" or
> "create" is terse and suffice.)
>
To keep things consistent with "writing to" and "reading from" or
"pushing" and "pulling" perhaps the following would be better:
StreamReaderBufferProcessor readFromXMLStreamReader()
>
>
> void processUsingSAXContentHandler(ContentHandler handler);
>
> should be:
>
> void writeTo(ContentHandler handler);
>
> (once again "processUsing" doesn't make a lot of sense to me)
>
OK.
>
> There are a few others like this. If it's OK with Paul, I'd like to make
> these changes.
>
I have no problem with you making changes, but if you are time
constrained will all the other the lots of other stuff you are doing i
really do not mind doing this.
>
> The other usability issue is how to create a mark. This isn't very
> intuitive today, as you are expected to call the constructor by
> yourself. I think it's better if I can do it bit more nicely, like:
>
> StreamWriterBufferCreator swbf = xsb.createFromXMLStreamWriter();
> // write something into swbf
> XMLStreamBuffer mark = swbf.mark();
>
Yes, i like that.
> It's also strange that XMLStreamBufferMark derives from XMLStreamBuffer,
> when XMLStreamBufferMark offers less functionality than XMLStreamBuffer
> (for example XMLStreamBufferMark is read-only.)
>
> This should be the other way around. XMLStreamBufferMark should be an
> interface that only defines methods like "newXMLStreamReader", and
> XMLStreamBuffer should implement it (and add methods for filling data
> in.) The user appliations shouldn't need to call the constructor of
> XMLStreamBufferMark (instead related objects should define a method like
> "mark" that returns a mark), so it should be suffice for it to be an
> interface. This makes it harder to misuse XMLStreamBuffer, and it also
> makes the developer surface smaller without reducing functionality.
>
The reason why XMLStreamBufferMark derives from XMLStreamBuffer is that
i did not want any differentiation in terms of processing so that the
user or the processors need not know when using a mark or not. But i
agree it would be better to clear this up.
The problem with making a mark an interface is that the processor needs
to get access to the storage representation of the buffer but this
should not be exposed to the user (because them the buffer can be
modified in all sorts of nasty ways).
I think the solution might be to turn things around but keeping this as
classes. So by default XMLStreamBuffer is read only immutable class (so
it is essentially a mark but we do not need to call it so), processors
will use this, then we extend this to have MutableXMLStreamBuffer, and
creators will use this.
Would that work for you?
Paul.
--
| ? + ? = To question
----------------\
Paul Sandoz
x38109
+33-4-76188109