Wiki source code of ERJavaMail Framework

Last modified by Pascal Robert on 2012/07/19 21:12

version	line-number	content
6.1	1	== Overview ==
2.1	2
22.1	3	ERJavaMail provides a simple and powerful API for sending component-based emails from a WebObjects application. ERJavaMail does not depend on any other pieces of Project Wonder, and is a good way to get your feet wet using Wonder.
2.1	4
22.1	5	(% style="color: rgb(0,0,0);" %)Configuration
2.1	6
	7	* er.javamail.centralize = true
22.1	8	Centralize sends all emails to the er.javamail.adminEmail user.
2.1	9	* er.javamail.debugEnabled = true
22.1	10	Determines whether or not email debugging is displayed. This contains protocol-level debug information.
2.1	11	* er.javamail.adminEmail = user@domain.com
22.1	12	The email address of the admin user to send centralized emails to. This is a required property.
2.1	13	* er.javamail.smtpHost = smtp.domain.com
22.1	14	The SMTP host name to use. If this isn't set, mail.smtp.host will be checked and ultimately WOHost will be used.
2.1	15	* er.javamail.senderQueue.size = 50
22.1	16	The number of messages that the sender queue can hold. Defaults to 50.
2.1	17	* er.javamail.milliSecondsWaitIfSenderOverflowed = 6000
22.1	18	The number of milliseconds to wait if the sender queue is full. Default is 6000.
2.1	19	* er.javamail.smtpAuth = true
22.1	20	Sets whether or not Authenticated SMTP is used to send outgoing mail. If set, er.javamail.smtpUser MUST
	21	also be set (and preferably er.javamail.smtpPassword).
2.1	22	* er.javamail.smtpUser = smtpusername
22.1	23	The username to use to login to the authenticated SMTP server.
2.1	24	* er.javamail.smtpPassword = smtppassword
22.1	25	The password to use to login to the authenticated SMTP server.
10.1	26	* er.javamail.smtpProtocol = smtp
22.1	27	The protocol to use to connect to the mail server. Defaults to smtp.
6.1	28	* er.javamail.XMailerHeader =
22.1	29	The X-Mailer header to put into all outgoing mail messages. Defaults to nothing.
2.1	30	* er.javamail.defaultEncoding = UTF-8
22.1	31	The default character encoding to use for message content. Defaults to ???.
6.1	32	* er.javamail.WhiteListEmailAddressPatterns =
22.1	33	A comma-separated list of whitelisted email address patterns. If set, then only addresses that match one of the whitelisted
	34	patterns will delivered to. Pattern syntax is the same as EOQualifier's caseInsensitiveLike.
2.1	35	* er.javamail.BlackListEmailAddressPatterns =
22.1	36	A comma-separated list of blacklisted email address patterns. If set, then any email addresses that match a blacklist pattern
	37	will not be delivered to. Pattern syntax is the same as EOQualifier's caseInsensitiveLike. The blacklist filter is processed
	38	last, so a blacklist pattern beats a whitelist pattern.
20.1	39	* er.javamail.smtpPort =
22.1	40	To specify the TCP port number of your SMTP server. Default is 25, you can also try 587, who is the "submission" port.
2.1	41
18.1	42	You need to at least specify the value for er.javamail.centralize, and if the value is "true", you also have to specify a value for er.javamail.adminEmail.
	43
6.1	44	== Example Usage ==
2.1	45
6.1	46	{{code}}
2.1	47
10.1	48	// Create an instance of an ERMailDelivery subclass
6.1	49	ERMailDeliveryHTML mail = new ERMailDeliveryHTML ();
2.1	50
6.1	51	// Here ERMailDeliveryHTML needs a WOComponent to
	52	// render the HTML text content.
	53	mail.setComponent(mailPage);
2.1	54
6.1	55	// Here you create a new instance of the message
	56	// You can loop over this fragment of code, not
	57	// forgetting to use newMail ()
	58	// before you set the attributes of the message.
	59	try {
	60	mail.newMail();
	61	mail.setFromAddress(emailFrom);
	62	mail.setReplyToAddress(emailReplyTo);
	63	mail.setSubject(emailSubject);
	64	mail.setToAddresses(new NSArray (toEmailAddresses));
	65	// Send the mail. There is an optional sendMail(boolean) that
	66	// optionally blocks during the send.
	67	mail.sendMail();
	68	} catch (Exception e) {
	69	// handle the exception ...
	70	}
2.1	71
6.1	72	{{/code}}
	73
	74	== Example of sending Mail with Attachments ==
	75
2.1	76	The subclasses of ERMailDelivery will not only deliver the mail for you, but also will create the message. So ERMailDelivery is
22.1	77	in some way more like a message than a delivery mechanism. For each message you want to sent instantiate a concrete subclass of
	78	ERMailDelivery (e.g. ERMailDeliveryPlainText). You can then add attachments to it. Below a simple code snippet sending of a
	79	mail with an attachment. The MimeType of the attachment is parsed out of the extension of the filename.
2.1	80
22.1	81	Sending mail is per default asynchronous, you can specify a flag (true h1. shouldBlock, false should not block) to influence
	82	the behaviour.
2.1	83
6.1	84	{{code}}
2.1	85
10.1	86	byte[] content; // assume this exist, same interface exists for NSData, too
6.1	87	// Create an instance of an ERMailDelivery subclass
	88	ERMailDeliveryPlainText message = new ERMailDeliveryPlainText();
	89	// set the text and subject
	90	message.setTextContent("Some Mail text");
	91	message.setSubject("The mail subject");
	92	// add the attachment
	93	message.addAttachment(new ERMailDataAttachment("myattachment.zip", null, content));
	94	message.setToAddress("receiver@bitbucket.com");
	95	message.setFromAddress("sender@bitbucket.com");
	96	// send the mail assynchronously
	97	message.sendMail();
2.1	98
10.1	99	{{/code}}
7.1	100
19.1	101	== Inline Attachments ==
	102
20.1	103	If you have a WebObjects Component and you want to send inline images with the component, you have to make use of a trick, that was mentioned in Fabian Peters mail on the Wonder Discussion mailinglist on 6 june 2009. I could not find an online reference.
19.1	104
	105	First of all, in the Component HTML one includes something like this:
	106
	107	{{code}}
	108
	109	<img src="cid:image0" alt="Logo" />
	110
	111	{{/code}}
	112
	113	The code that accompanies this cid:image0 is:
	114
	115	{{code}}
	116
	117	URL logoURL = myApp().resourceManager().pathURLForResourceNamed("logo.png", null, null);
	118	File logo = new File(logoURL.toURI());
	119	ERMailAttachment imageLogo = new ERMailFileAttachment("logo.png","<image0>",logo);
	120
	121	{{/code}}
	122
20.1	123	Note that the file "logo.png" has to be included in the Resources folder of you WebObjects project.
22.1	124	The "cid:image0" is linked to the <image0> in the ImageAttachment.
19.1	125
6.1	126	== Gotchas ==
2.1	127
22.1	128	Be careful of the WOContext that contains the component you are sending. If you use ERMailDeliveryHTML inside of the normal request-response loop with the default WOContext, it is very likely that the next page that is sent to the user will be the emailed component rather than the page you WANTED to send. There are several possible workarounds for this. One is to return a specific component rather than null from your action method. I have had better and more consistent success with the following code:
2.1	129
6.1	130	{{code}}
2.1	131
10.1	132	WOContext context = (WOContext) context().clone();
6.1	133	MyComponent component = (MyComponent) WOApplication.application().pageWithName(MyComponent.class.getName(), context);
	134	ERMailDeliveryHTML mail = new ERMailDeliveryHTML();
	135	mail.setComponent(component);
	136	...
2.1	137
6.1	138	{{/code}}
2.1	139
22.1	140	This seems to properly isolate the email to a clone of the current context rather than the actual active context. Your mileage may vary.
10.1	141
	142	If you are using Wonder 3.0 or later and you don't extend ERXApplication, you need to add this line in your Application constructor:
	143
	144	{{code}}
	145
	146	ERJavaMail.sharedInstance ().finishInitialization();
	147
	148	{{/code}}

Wiki source code of ERJavaMail Framework

Applications

Navigation

My Recent Modifications

Need help?