james-mime4j-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Stefano Bagnara (JIRA)" <mime4j-...@james.apache.org>
Subject [jira] [Created] (MIME4J-195) Entity and AbstractEntity consistency and correcteness checks
Date Tue, 19 Apr 2011 08:33:05 GMT
Entity and AbstractEntity consistency and correcteness checks

                 Key: MIME4J-195
                 URL: https://issues.apache.org/jira/browse/MIME4J-195
             Project: JAMES Mime4j
          Issue Type: Task
          Components: dom
    Affects Versions: 0.7
            Reporter: Stefano Bagnara
             Fix For: 0.8

Entity exposes
- setBody: sets the body of the entity
- setHeader: sets the header

Inconsistency: setBody throws an exception if the body already exists, setHeader does not
show this behaviour
Correctness: setBody does not provide consistency at the dom level: e.g: if you previously
added a Content-Type field saying it is a multipart it happily accept a plain text body and
will fail when the body is written out.

AbstractEntity adds:
- setMessage(Message message)
- setMultipart(Multipart multipart)
- setMultipart(Multipart multipart, Map<String, String> parameters)
- setText(TextBody textBody)
- setText(TextBody textBody, String subtype)
- setBody(Body body, String mimeType)
They all prepare parameters and call the internal method
- setBody(Body body, String mimeType, Map<String, String> parameters)

All of these methods document they behaviour saying "A Header is created if this entity does
not already have one but they don't say that the Content-Type field is replaced by a new content-type
created using the parameters. These methods are only used by example code and not by the parser.
The parser will only use the Entity.setBody method when parsing.

Inconsistency: Multipart interface expose "subtype" but not "boundary". I think that technically
the boundary is a part of a multipart body instead subtype is only something used when the
full entity is used (it is only in the header). So it seems inconsistent that a Multipart
knows its subtype, its raw epilogue but doesn't know the boundary: should we add it?
Inconsistency: Multipart knows its own subtype, instead TextBody doesn't know it.
Weirdness: If you call the public method "setBody()" and you pass a Multipart object Entity
doesn't do anything to ensure the dom object is valid. Instead if you call setMultipart()
and you pass the very same Multipart it will take care of adding the content-type using the
subtype from the Multipart object and a new generated Boundary. If you call the third method
"setMultipart(multipart,parameters)" then you also ensure a new contenttype is generated starting
using the subtype and parameters as input. the setMultipart methods always rewrite the original
contenttype added previously to the header.

It doesn't sound good that the public interface exposes the only method (setBody) that doesn't
provide "content-type-header vs body content consistency".

I'm not sure what is the best way to make the whole thing consistent, so I hope we can discuss
the logic here. At the very least I hope we can define if "subtype" is something belonging
to the body or not (and maybe other properties like boundary, charset, ....).

Should mime4j dom api care about consistency between content-type/content-transfer-encoding
and the entity body? What object should care? How should it react when we change one or the
other to become incompatible? e.g: if I add a Multipart then I change the Content-Type header
to say text/plain what should it do? (change Multipart body with a TextBody on the fly? Keep
the inconsistency and simply dump the text/plain header and the multipart stream?). 

I think answers to this issue will also help understand how we should expose message building
public API. Currently we only expose MessageBuilder.newMessage. The Message exposes a setBody
but we don't publish a way to create new bodies. Now an API user have to go in the internals
and create e.g: a new MultipartImpl then call the setBody and then make sure to add a content-type
header (how does it do?) matching the multipart just added.

This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira

View raw message