james-server-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Bagnara <apa...@bago.org>
Subject Re: [mime4j] Review Packaging
Date Thu, 10 Jul 2008 16:54:55 GMT
Robert Burrell Donkin ha scritto:
> On 7/10/08, Stefano Bagnara <apache@bago.org> 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: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org


Mime
View raw message