You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by __matthewHawthorne <ma...@phreaker.net> on 2003/12/21 01:55:49 UTC
[io] docs and refactorings
I made some updates to [io]'s documentation today. I copied some of the
package description for the main package and put it on the main index of
the site. I think it's useful to have a nice overview of the projects
with links to Javadoc on the front page.
Since Maven is so good at generating docs, I'm starting to favor useful
xdocs over long package descriptions. It just seems easier to navigate.
Now onto the code: I have some ideas that I'd like to mention.
----------------------------------------------------------------
Packages o.a.c.io.input and o.a.c.io.output
----------------------------------------------------------------
I'd like to merge these into one package which contains all
InputStreams, OutputStreams, Readers and Writers. Currently, we have 1
Writer, 0 Readers, and the rest are streams. I just think it makes more
sense to have these classes side by side. For example --
ProxyInputStream and ProxyOutputStream, DemuxInputStream and
DemuxOutputStream. These classes will most like be used together, and
change together, so lets put them together.
Here are some ideas for a name:
o.a.c.io.throughput
- kind of vague
o.a.c.io.streams
- good, but there may be readers, writers also
o.a.c.io
- what about putting them in the root package similar to java.io
----------------------------------------------------------------
class o.a.c.io.HexDump
----------------------------------------------------------------
This class only has one method, dump(byte[], long, OutputStream, int).
I would like to move this method to IOUtils as dumpHex, then deprecate
and remove the original class.
Please chime in with any comments or suggestions.
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [io] docs and refactorings
Posted by Jeremias Maerki <de...@greenmail.ch>.
On 28.12.2003 20:34:05 Stephen Colebourne wrote:
> From: "__matthewHawthorne" <ma...@phreaker.net>
> > >>Packages o.a.c.io.input and o.a.c.io.output
> > >>----------------------------------------------------------------
> > OK, then perhaps io.streams is the best place. However, I believe that
> > Henri preferred leaving the classes split between io.input and
> > io.output. Henri, can you chime in and give us the reason for your
> > opinion on this again?
> I also support input and output (as is), as they just seem like an obvious
> classification. Is there any real need for them to be together?
> [collections] has suffered by putting things in one place when they should
> have been split.
I'm also totally ok with leaving everything as is.
> > Also, what are the opinions on renaming IOUtils to IoUtils? I think
> > there's a guideline in "Elements of Java Style" that suggests
> > capitalizing acronyms in this way.
> I wouldn't change from IOUtils, it just looks right.
I agree.
> Actually, you might want to consider InputUtils and OutputUtils instead.
> Again, this seems like the obvious classification.
Going through IOUtils I don't quite see how the methods would be
separated in these two classes. Any ideas?
Jeremias Maerki
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: ProxyXxx Was: [io] docs and refactorings
Posted by Stephen Colebourne <sc...@btopenworld.com>.
All deprecated.
Stephen
From: "Henri Yandell" <ba...@generationjava.com>
> ProxyMap, ProxyIterator, ProxyListIterator and others appear to exist
> still.
>
> Hen
>
> On Mon, 29 Dec 2003, Stephen Colebourne wrote:
>
> > BTW, [collections] uses the term "AbstractXxxDecorator" instead of Proxy
> > now. One to consider?
> > Stephen
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
ProxyXxx Was: [io] docs and refactorings
Posted by Henri Yandell <ba...@generationjava.com>.
ProxyMap, ProxyIterator, ProxyListIterator and others appear to exist
still.
Hen
On Mon, 29 Dec 2003, Stephen Colebourne wrote:
> BTW, [collections] uses the term "AbstractXxxDecorator" instead of Proxy
> now. One to consider?
> Stephen
>
> ----- Original Message -----
> From: "Henri Yandell" <ba...@generationjava.com>
> > Proxy is a bit of a special case I think, as I'd like to see a nice jar
> > full of handy proxy classes :) This is because I would walk up to said
> > javadoc and ask for a proxy, then choose the class I want to be proxied.
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [io] docs and refactorings
Posted by Stephen Colebourne <sc...@btopenworld.com>.
BTW, [collections] uses the term "AbstractXxxDecorator" instead of Proxy
now. One to consider?
Stephen
----- Original Message -----
From: "Henri Yandell" <ba...@generationjava.com>
> Proxy is a bit of a special case I think, as I'd like to see a nice jar
> full of handy proxy classes :) This is because I would walk up to said
> javadoc and ask for a proxy, then choose the class I want to be proxied.
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [io] docs and refactorings
Posted by Henri Yandell <ba...@generationjava.com>.
In the end, the prime aspect is 'what will be used together'. That's what
makes a package. I view this as what will one piece of code use, not one
huge application.
I think it's more likely that we'll see 3 InputStream's chained, or using
Proxy or something, than for an OutputStream to be used.
That's my entire justification for keeping in/out separate :)
Should InputStream and Reader be separate? I think it's not that common to
use Reader and InputStream together, but it's a lot more common than using
with OutputStream. As Reader may be written in terms of InputStream, I can
see that it makes sense to keep these guys together.
I guess another way to view it is in terms of search parameters,
hierarchical search not google. I feel I'm far more likely to walk up to
the javadoc and say: "I need a Writer, make it a Counting", than "I need
a Counting, make it a Writer".
Proxy is a bit of a special case I think, as I'd like to see a nice jar
full of handy proxy classes :) This is because I would walk up to said
javadoc and ask for a proxy, then choose the class I want to be proxied.
[end of babble]
Hen
On Sun, 28 Dec 2003, Stephen Colebourne wrote:
> The situation is no different to [collections], where we have PredicatedXxx,
> TransformedXxx, TypedXxx etc. In the end, the prime aspect is the type of
> collection, not the type of decoration.
>
> This can be argued both ways, but it would be nice for [io] to follow
> [collections] ;-)
>
> Stephen
>
> ----- Original Message -----
> From: "__matthewHawthorne" <ma...@phreaker.net>
> > There are 3 examples in the current [io] codebase:
> >
> > Counting [InputStream, OutputStream]
> > Demux [InputStream, OutputStream]
> > Proxy [InputStream, OutputStream]
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [io] docs and refactorings
Posted by Stephen Colebourne <sc...@btopenworld.com>.
The situation is no different to [collections], where we have PredicatedXxx,
TransformedXxx, TypedXxx etc. In the end, the prime aspect is the type of
collection, not the type of decoration.
This can be argued both ways, but it would be nice for [io] to follow
[collections] ;-)
Stephen
----- Original Message -----
From: "__matthewHawthorne" <ma...@phreaker.net>
> There are 3 examples in the current [io] codebase:
>
> Counting [InputStream, OutputStream]
> Demux [InputStream, OutputStream]
> Proxy [InputStream, OutputStream]
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [io] docs and refactorings
Posted by __matthewHawthorne <ma...@phreaker.net>.
Stephen Colebourne wrote:
>>OK, then perhaps io.streams is the best place. However, I believe that
>>Henri preferred leaving the classes split between io.input and
>>io.output. Henri, can you chime in and give us the reason for your
>>opinion on this again?
>
> I also support input and output (as is), as they just seem like an obvious
> classification. Is there any real need for them to be together?
> [collections] has suffered by putting things in one place when they should
> have been split.
There are 3 examples in the current [io] codebase:
Counting [InputStream, OutputStream]
Demux [InputStream, OutputStream]
Proxy [InputStream, OutputStream]
I think that these classes belong in the same package. With regard to
streams and readers/writers, I disagree that input and output is an
obvious classification. There are many situations, although we only
have three in [io] where the concept (or "type" of stream) is the
controlling factor. These classes make use of the same concept, and
therefore may make use of similar code and tests.
Take a look at java.io:
Buffered [InputStream, OutputStream, Reader, Writer]
ByteArray [InputStream, OutputStream]
CharArray [Reader, Writer]
Data [InputStream, OutputStream]
File [InputStream, OutputStream]
Filter [InputStream, OutputStream, Reader, Writer]
LineNumber [InputStream, Reader]
Object [InputStream, OutputStream]
Piped [InputStream, OutputStream, Reader, Writer]
Pushback [InputStream, Reader]
Should these classes all be separated by input and output? I don't
think so.
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
RE: [io] docs and refactorings
Posted by "Noel J. Bergman" <no...@devtech.com>.
> what are the opinions on renaming IOUtils to IoUtils? I think
> there's a guideline in "Elements of Java Style" that suggests
> capitalizing acronyms in this way.
Sun deprecated isRequestedSessionIdFromUrl, encodeUrl, encodeRedirectUrl,
etc., in favor of isRequestedSessionIdFromURL, encodeURL, encodeRedirectURL,
etc.
This appears consistent with the Java style guide I found from Sun:
"All [type, non-constant field and method] names should use
the InfixCaps style. Start with an upper-case letter, and
capitalize the first letter of any subsequent word in the
name, as well as any letters that are part of an acronym.
All other characters in the name are lower-case."
ref: http://wwws.sun.com/software/sundev/whitepapers/java-style.pdf,
sections 3.2 - 3.4. An HTML version of an older edition can be found at
http://www.isr.umd.edu/~austin/ence489c.d/java-style.html.
--- Noel
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [io] docs and refactorings
Posted by Stephen Colebourne <sc...@btopenworld.com>.
From: "__matthewHawthorne" <ma...@phreaker.net>
> >>Packages o.a.c.io.input and o.a.c.io.output
> >>----------------------------------------------------------------
> OK, then perhaps io.streams is the best place. However, I believe that
> Henri preferred leaving the classes split between io.input and
> io.output. Henri, can you chime in and give us the reason for your
> opinion on this again?
I also support input and output (as is), as they just seem like an obvious
classification. Is there any real need for them to be together?
[collections] has suffered by putting things in one place when they should
have been split.
> Also, what are the opinions on renaming IOUtils to IoUtils? I think
> there's a guideline in "Elements of Java Style" that suggests
> capitalizing acronyms in this way.
I wouldn't change from IOUtils, it just looks right.
Actually, you might want to consider InputUtils and OutputUtils instead.
Again, this seems like the obvious classification.
Stephen
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [io] docs and refactorings
Posted by __matthewHawthorne <ma...@phreaker.net>.
Jeremias Maerki wrote:
>>----------------------------------------------------------------
>>Packages o.a.c.io.input and o.a.c.io.output
>>----------------------------------------------------------------
>>I'd like to merge these into one package which contains all
>>InputStreams, OutputStreams, Readers and Writers. Currently, we have 1
>>Writer, 0 Readers, and the rest are streams. I just think it makes more
>>sense to have these classes side by side. For example --
>>ProxyInputStream and ProxyOutputStream, DemuxInputStream and
>>DemuxOutputStream. These classes will most like be used together, and
>>change together, so lets put them together.
>>
>>Here are some ideas for a name:
>>
>>o.a.c.io.streams
>>- good, but there may be readers, writers also
>
>
> I like this most. I don't think there is a problem if we put Readers and
> Writers in there.
OK, then perhaps io.streams is the best place. However, I believe that
Henri preferred leaving the classes split between io.input and
io.output. Henri, can you chime in and give us the reason for your
opinion on this again?
>>----------------------------------------------------------------
>>class o.a.c.io.HexDump
>>----------------------------------------------------------------
>>
>>This class only has one method, dump(byte[], long, OutputStream, int).
>>I would like to move this method to IOUtils as dumpHex, then deprecate
>>and remove the original class.
>
>
> -0. I'm thinking about visibility. I don't like filling up IOUtils with
> too much. People need to find out quickly what capabilities IO has. For
> HexDump (a class I haven't looked at, yet) I can imagine several layout
> modes. The code for that may inflate IOUtils too much for my taste.
I didn't quite understand HexDump. If you feel that it has room to grow
and would clutter IOUtils, then let's leave it.
Also, what are the opinions on renaming IOUtils to IoUtils? I think
there's a guideline in "Elements of Java Style" that suggests
capitalizing acronyms in this way.
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [io] docs and refactorings
Posted by Jeremias Maerki <de...@greenmail.ch>.
On 21.12.2003 01:55:49 __matthewHawthorne wrote:
<snip/>
> ----------------------------------------------------------------
> Packages o.a.c.io.input and o.a.c.io.output
> ----------------------------------------------------------------
> I'd like to merge these into one package which contains all
> InputStreams, OutputStreams, Readers and Writers. Currently, we have 1
> Writer, 0 Readers, and the rest are streams. I just think it makes more
> sense to have these classes side by side. For example --
> ProxyInputStream and ProxyOutputStream, DemuxInputStream and
> DemuxOutputStream. These classes will most like be used together, and
> change together, so lets put them together.
>
> Here are some ideas for a name:
>
> o.a.c.io.throughput
> - kind of vague
Hmm, I agree
> o.a.c.io.streams
> - good, but there may be readers, writers also
I like this most. I don't think there is a problem if we put Readers and
Writers in there.
> o.a.c.io
> - what about putting them in the root package similar to java.io
I agree with Henri's comments.
> ----------------------------------------------------------------
> class o.a.c.io.HexDump
> ----------------------------------------------------------------
>
> This class only has one method, dump(byte[], long, OutputStream, int).
> I would like to move this method to IOUtils as dumpHex, then deprecate
> and remove the original class.
-0. I'm thinking about visibility. I don't like filling up IOUtils with
too much. People need to find out quickly what capabilities IO has. For
HexDump (a class I haven't looked at, yet) I can imagine several layout
modes. The code for that may inflate IOUtils too much for my taste.
Jeremias Maerki
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [io] docs and refactorings
Posted by Gareth Andrew <ga...@ntlworld.com>.
How about calling the package o.a.c.io.io?
>
> This depends how you define the term "lots of classes", although I see
> your point. [io] has so few classes right now (and so few people
> interested in it) that it's hard to predict the future. I personally
> would prefer to see the streams,writers,readers in a subpackage rather
> than the root, but am having trouble thinking of a good name.
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [io] docs and refactorings
Posted by __matthewHawthorne <ma...@phreaker.net>.
>>----------------------------------------------------------------
>>Packages o.a.c.io.input and o.a.c.io.output
>>----------------------------------------------------------------
>>I'd like to merge these into one package which contains all
>>InputStreams, OutputStreams, Readers and Writers. Currently, we have 1
>>Writer, 0 Readers, and the rest are streams. I just think it makes more
>>sense to have these classes side by side. For example --
>>ProxyInputStream and ProxyOutputStream, DemuxInputStream and
>>DemuxOutputStream. These classes will most like be used together, and
>>change together, so lets put them together.
>
>
> Dunno. I'm hesitant on this move as I don't think the Proxy's will be used
> side by side, though Demux might.
Maybe the Proxy classes were a bad example. My point is: I don't think
input/output are the best way to group these classes. It would be nice
to have streams, readers, writers that use the same concept (such as
Demux, Proxy, Counting) in the same package. I count 12 classes in
these two packages -- which is not really that many.
>>o.a.c.io
>>- what about putting them in the root package similar to java.io
>
>
> Tidiness. At this stage of IO's life, a package with lots of classes in
> looks like one that won't scope. A package with a few things in will scope
> however.
This depends how you define the term "lots of classes", although I see
your point. [io] has so few classes right now (and so few people
interested in it) that it's hard to predict the future. I personally
would prefer to see the streams,writers,readers in a subpackage rather
than the root, but am having trouble thinking of a good name.
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [io] docs and refactorings
Posted by Henri Yandell <ba...@generationjava.com>.
On Sat, 20 Dec 2003, __matthewHawthorne wrote:
> Since Maven is so good at generating docs, I'm starting to favor useful
> xdocs over long package descriptions. It just seems easier to navigate.
Ditto, though I've started to favour turning off the default Maven
navigation and setting my own up by hand.
> ----------------------------------------------------------------
> Packages o.a.c.io.input and o.a.c.io.output
> ----------------------------------------------------------------
> I'd like to merge these into one package which contains all
> InputStreams, OutputStreams, Readers and Writers. Currently, we have 1
> Writer, 0 Readers, and the rest are streams. I just think it makes more
> sense to have these classes side by side. For example --
> ProxyInputStream and ProxyOutputStream, DemuxInputStream and
> DemuxOutputStream. These classes will most like be used together, and
> change together, so lets put them together.
Dunno. I'm hesitant on this move as I don't think the Proxy's will be used
side by side, though Demux might.
> o.a.c.io
> - what about putting them in the root package similar to java.io
Tidiness. At this stage of IO's life, a package with lots of classes in
looks like one that won't scope. A package with a few things in will scope
however.
> ----------------------------------------------------------------
> class o.a.c.io.HexDump
> ----------------------------------------------------------------
>
> This class only has one method, dump(byte[], long, OutputStream, int).
> I would like to move this method to IOUtils as dumpHex, then deprecate
> and remove the original class.
+1
Hen
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org