26 Dec
2012
26 Dec
'12
2:58 p.m.
I've been thinking a bit more on the mailSender component, and here's the
APIs I have in mind :
The component API would have the following methods :
- void prepareMail(String from, String to, String cc, String bcc, String
subject)
- void addToContent(String contentType, String content) //To add a part
to the mail, contentType being the Mime Type of this part
- void addAttachment(Attachment file)
- int sendMail() //Returns 1 on success and 0 otherwise
And the scripting API would have the following :
- void prepareMail(String from, String to, String cc, String bcc, String
subject)
- void addToContent(String contentType, String content)
- void addHtml(String content)
- void addCalendar(String vCalendar)
- int sendMail()
- int sendHtmlMail(String from, String to, String subject, String html,
String alternativeText) //Simple method for non-experienced users sending
a simple html mail
{
this.mailSender.prepareMail(from, to, null, null, subject) ;
this.mailSender.addToContent("text/html", html) ;
this.mailSender.addToContent("text/plain", alternativeText);
return this.mailSender.sendMail() ;
}
So, a simple use-case would look something like :
{{velocity}}
$services.mailSender.prepareMail("foo(a)bar.fr"r.fr", "foo2(a)bar.fr"r.fr",
"", "",
"Subject")
$services.mailSender.addHtml("<strong>This is an email with a
calendar</strong>")
$services.mailSender.addCalendar($calendar)
$services.mailSender.sendMail()
{{/velocity}}
What do you think ? Is there anything you think is missing ? In peticular,
I'm wondering whether it would be useful to recreate methods similar to the
parseRawMessage() and sendMailFromTemplate() methods that were implemented
in the former mailSender ?
Cheers,
Thomas
On Thu, Dec 20, 2012 at 7:00 PM, Sergiu Dumitriu <sergiu(a)xwiki.org> wrote:
On 12/20/2012 06:55 AM, Thomas Delafosse wrote:
Hi all,
I would be happy to work on the mailSender plugin.
I propose to make it a component and add it a few functionalities.
Namely,
I was thinking about adding an API like:
public int sendMultiContentMessage (String from, String to, String cc,
String bcc, String subject, String[] contents, List<Attachment>
attachments) (1)
Methods with too many arguments are not recommended. It even breaks our
checkstyle, which allows at most 7 parameters (which I think is too
much, anyway). Listing possible mail tokens is bad, since in most cases
not all of them are needed, and in some cases others will be needed with
no way of specifying them, other than writing the whole message
including headers by hand.
Either use a typed object, or a generic map.
where contents would be a string array containing
all the contents to be
embed in the mail (text, html but also a vCalendar for example) along
with
their MIME type.
So for example, if you want to send a mail containing some html part and
a
vCalendar, "contents" would look
something like :
contents = ['text/html', Your Html code, 'text/calendar', Your
vCalendar] .
This is an untyped convention. You're hoping that all users will read
the documentation and know that they're supposed to provide pairs of
values, MIME + content. That's not a nice thing to do. A list of typed
objects would be better, since it doesn't allow mistakes.
Another way to achieve this would be to use a
single String "body"
instead
of "contents", with a specific syntax
indicating each part MIME type,
thus
allowing us to parse it. For example we could
imagine having something
like
:
public int sendMultiContentMessage (String from, String to, String cc,
String bcc, String subject, String body, List<Attachment> attachments)
with
body = "{{html}}HTML code{{/html}}
{{calendar}}Calendar
code{{/calendar}}"
(2) or even
body = "{{mailPart type='text/html'}}HTML code{{/mailPart}} {{mailPart
type="text/calendar"}}Calendar code{{/mailPart}}" (3).
This would be easier to use ((2) most of all), but probably trickier,
slower and for (2), less flexible.
I don't like this either, it's even more error prone.
Java is an OOP language, use good OOP design as much as possible.
WDYT ? And of course, if there is anything else
you would like to change
in
the mailSender, let me know !
Thomas
--
Sergiu Dumitriu
http://purl.org/net/sergiu
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs