PATH |
Sending E-mail from a WebObjects Application
Discussion
Composing and delivering e-mail from a WebObjects application is accomplished by using the WOMailDelivery class. WOMailDelivery has several methods for composing, addressing, and delivering e-mail messages.
Overview of WOMailDelivery
To perform e-mail delivery, WOMailDelivery uses a command-line tool that is compiled on all supported WebObjects platforms. The executable can be found in <NeXT_ROOT>\Library\WebObjects\Executables\WOSendMail[.exe]
This tool constructs an e-mail message from a file and uses SMTP to send it. It has a default SMTP server hostname (called "smtp"). However, you will most likely need to change it to reflect your site's SMTP server. This can be accomplished by setting the WOSMTPHost default for your application. Like all other WebObjects defaults, it can be set by either the defaults command-line tool, or by passing it as an argument when starting your WebObjects application.
Option 1 - Using the "defaults" tool to set WOSMTPHost
Assuming your WebObjects application is called MyApp and your SMTP host is called " postoffice.acme.com ", type the following on the command line:
defaults write MyApp WOSMTPHost "postoffice.acme.com"
You could set this for all applications by setting the default on NSGlobalDomain rather than on MyApp:
defaults write NSGlobalDomain WOSMTPHost "postoffice.acme.com"
Using WOMailDelivery in Source Code
Your source code, perhaps in an action method on one of your components, must perform the following steps to deliver e-mail:
Create an instance of the WOMailDelivery class. This is easily accomplished via the sharedInstance class method, which returns a shared instance of WOMailDelivery, creating the instance as necessary.
Creating a WOMailDelivery object (Java)
public.static.native com.apple.yellow.webobjects.WOMailDelivery.sharedInstance()
Creating a WOMailDelivery object (Objective-C)
+ (WOMailDelivery *)sharedInstance
- Compose and send your WOMailDelivery object using plain text or HTML encoding. Separate methods are provided to compose messages in the two encodings.
Plain Text Message -- Composes an e-mail message setting the content type of the e-mail as (Content-type: TEXT/PLAIN; CHARSET=US-ASCII). If sendNow is true, the e-mail is sent at once.
Composing a plain text message (Java)
public native java.lang.string composePlainTextEmail ( java.lang.String, // From: string com.apple.yellow.foundation.NSArray, // To: array of e-mail addresses com.apple.yellow.foundation.NSArray, // Cc: array of e-mail addresses java.lang.String, // Subject: string java.lang.String, // MessageBody: string boolean) // send it now?
Composing a plain text message (Objective-C)
-(NSString *)composeEmailFrom:(NSString *)aSender to:(NSArray *)somePeople cc:(NSArray *)otherPeople subject:(NSString *)aSubject plainText:(NSString *)aMessage send:(BOOL)sendNow
HTML Message -- Composes an e-mail message, calling generateResponse on the WOComponent argument and embedding the resulting HTML in the body of the message. This is convenient if you want to send the actual HTML generated by one of your custom WOComponents. It uses the WOCGIAdaptorURL default to complete all URLs in the page to be mailed. If sendNow is true, the e-mail is sent at once.
Composing a HTML message (Java)
public native java.lang.string composeComponentEmail ( java.lang.String, // From: string com.apple.yellow.foundation.NSArray, // To: array of e-mail addresses com.apple.yellow.foundation.NSArray, // Cc: array of e-mail addresses java.lang.String, // Subject: string com.apple.yellow.webobjects.WOComponent, // MessageBody: WOComponent boolean) // send it now?
Composing a HTML message (Objective-C)
-(NSString *)composeEmailFrom:(NSString *)aSender to:(NSArray *)somePeople cc:(NSArray *)otherPeople subject:(NSString *)aSubject component:(WOComponent *)aComponent send:(BOOL)sendNow
- If you specify true/YES as the send argument in step 2, then delivery will occur immediately. However, if you specify false/NO as the send argument, then you must explicitly tell the WOMailDelivery object to deliver the message. This is accomplished by calling the sendEmail method with the fully composed mailString (returned by one of the methods from Step 2) as the only argument.
The sendEMail method (Objective-C)
-(void)sendEmail:(NSString *)mailString
The mailed component should not contain any image or resource requiring a callback to the web server. Links and forms in e-mailed WOComponents will work correctly as long as the application is available to serve them.
Source Code Example
The following example composes and delivers two messages: one with plain text and one with HTML. This method could be the target of an action or WOForm submit.
Sending mail (Java)
String message; // Bound to a WOText element in this component // Remember to set the WOSMTPHost or this code will not work public WOComponent sendEmail() { String from = "ACME WebObjects Program <acme_app@acme.com>"; Object tos[]={"acme_admin@acme.com", "acme_hr@acme.com>"}; NSArray to = new NSArray(tos); NSArray cc = new NSArray("acme_support@acme.com"); String htmlMessage; // Delivers a plain text message by grabbing the contents // of the WOText element bound to message. Delivers // immediately since the last argument is true. WOMailDelivery.sharedInstance().composePlainTextEmail( from, to, cc, "WebSite Feedback", message, true); // This delivers an HTML message created by passing this // as the WOComponent argument. generateResponse will be sent to // this and will result in a formatted HTML string. This time, // instead of delivering immdediately, the last argument is // false and we use the sendEmail method with the return // value from composeComponentEmail(). htmlMessage = WOMailDelivery.sharedInstance().composeComponentEmail( from, to, cc, "WebSite Feedback", this, false); WOMailDelivery.sharedInstance().sendEmail(htmlMessage); return null; }
Sending Mail (Objective-C)
NSString *message; // Bound to a WOText element in this component // Remember to set the WOSMTPHost or this will not work - (void)sendEmail { NSString *from = @"ACME WebObjects Program <acme_app@acme.com>"; NSArray *to = [NSArray arrayWithObject:@"acme_admin@acme.com"]; NSArray *cc = [NSArray arrayWithObject:@"acme_support@acme.com"]; NSString *htmlMessage; // This delivers a plain text message by grabbing the contents // of the WOText element bound to message. It also delivers // immediately since the last argument is true. [[WOMailDelivery sharedInstance] composeEmailFrom: from to: to cc: cc subject: @"WebSite Feedback" plainText: message send: YES]; // This delivers an HTML message created by passing self // as the WOComponent argument. generateResponse will be sent to // self and will result in a formatted HTML string. This time, // instead of delivering immdediately, the last argument is // false and we use the sendEmail method with the return // value from composeEmailFrom:to:cc:subject:component:send:. htmlMessage = [[WOMailDelivery sharedInstance] composeEmailFrom: from to: to cc: cc subject: @"WebSite Feedback" component: self send: NO]; [[WOMailDelivery sharedInstance] sendEmail:htmlMessage]; return nil; }
© 1999 Apple Computer, Inc.