Robert Burrell Donkin ha scritto:
On 7/10/08, Stefano Bagnara <[EMAIL PROTECTED]> wrote:
Robert Burrell Donkin ha scritto:
thanks to the great work done by Oleg, Mime4J is much better and has
quite a lot more classes. a release should be really close now. so,
it's a good time to review packaging. i think the packages below need
some thought.
i think that the packaging strategy has become inconsistent. i think
that the choice is either to move lots of utility-ish classes out from
mime4j and into sub-packages, or to remove the decoder and util
subpackages and move their contents into mime4j.
i can see arguments either way. lots of classes in a single package is
less expressive. but libraries can benefit from flat packaging. flat
packaging can also be an advantage for OSGI.
opinions?
I only checked the sources for cyclic dependencies between packages and
somewhere 7 new cycles have been introduced.
The last time I fixed this the root package (org.apache.james.mime4j)
only depended on decoder and util packages, with decoder depending on
util too).
I think the first thing is to remove cycles.
Ok
What do you propose?
ATM I identified these "wrong" dependencies.
util.MimeUtil
- root.BodyDescriptor
- root.CharArrayBuffer (*)
decoder.DecoderUtil
- root.CharArrayBuffer (*)
root.MaximalBodyDescriptor
- field.language.ContentLanguageParser
- field.structured.StructuredFieldParser
- field.mimeversion.MimeVersionParser
- field.datetime.parser.ParseException
- field.datetime.parser.DateTimeParser
(*) moving CharArrayBuffer to the util package would fix two dependencies.
IMHO in packaging we should care about 2 things:
1) public api (at least the external layer) classes should be in a
limited number of packages
2) avoid cyclic dependencies and group by dependencies
I don't have a good view of the api, so I concentrate on the second
strictly technical and pragmatic issue.
I started with a class dependencies graph, grouping the whole "field"
and "message" trees as single nodes (they already have good packagings).
A] decoder are indeed utils, I don't see a real motivation for 2
different packages, so I think they could be merged (if needed we
can break them later, when we identify a classification).
I merged them to util.
B] our root package included classes from mixed layers/dependencies.
From the class dependencies graph it was almost obvious some
different classification:
- core:
BodyDescriptor/MutableBodyDescriptor/ContentDescriptor/MimeException
- util: ByteArrayBuffer/CharArrayBuffer
- everything else.
So I moved the 2 utils to util and the 4 core classes to a new
"core" package.
The 2 actions (and the "organize imports" for MimeUtil I already
committed) removed all of the cycles.
I also noticed a couple of things:
I noticed we have some unused class:
- util.StringArrayMap
- util.PartialInputStream
- util.PositionInputStream
- EOLConvertingInputStream
- CloseShieldInputStream
what should we do? (delete? deprecate?)
utils contains both "generic utils" and "mime related utils"
- generic: TempStorage, SimpleTempStorage, TempPath, TempFile
- mime: CharsetUtil, MessageUtil, CodecUtil, MimeUtil
After the merge with decoder and there are some more classes, but if the
package is too big I think we can split them in the 2 groups (generic
utils vs mime specific)
the core package still contains utility classes that could be moved to
utils:
- InputBuffer
- BufferingInputStream
- BasicBufferingInputStream
- BufferingInputStreamAdaptor
- MimeBoundaryInputStream
I think it is more appropriate the util package than the root package
for them (the less we have in the root package, the better).
Furthermore the updated diagram shows that the *Descriptor classes are
all in a lower level than the rest of the package classes. I'd probably
favor a package for them.
After all of this we have this packages
- root 13 classes
- util 25 classes
- descriptor 7 classes
- core 4 classes
- field* (big)
- message 12 classes
I'm pretty satisfied with the result, but I have concern with the root
package. I think the root package should only contain "public" stuff and
we should move internal processing classes somewhere else (existing
packages or new packages).
I would also be interested in understanding what packages/classes a
standard usage of the library exposes to better understand how to group
them.
Stefano
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
