com.smartgwt.client.docs.serverds
Class Mail

java.lang.Object
  com.smartgwt.client.docs.serverds.Mail

public class Mail
extends java.lang.Object

This class is not meant to be created and used, it is actually documentation of settings allowed in a DataSource descriptor (.ds.xml file). See com.smartgwt.client.docs.serverds for how to use this documentation.

A Mail object describes an email that will be sent automatically by the Smart GWT Server as part of a normal DataSource operation. Mail definitions are part of an OperationBinding, and they can only be specified in a DataSource's XML definition. Despite the declarative nature of mail definitions, templating support via Velocity makes it very flexible; it is very easy to include values from records just fetched from permanent storage by this operation, for example. See VelocitySupport for an overview of Smart GWT Server's pervasive support for templated declarative operations using Velocity.

The default context for the message is the dsResponse.data; that is, $foo in the message refers to the field "foo" in the DataSource response (the equivalent of calling dsResponse.getFieldValue("foo") in Java). You also have access to the normal Velocity variables described in the overview linked to above.

If multiple records appear in the dsResponse, one message will be sent per record in the response unless "multiple" is set to false. This allows a set of recipients to be selected by a "fetch" operationBinding and messages sent to each. This also means that if no data is selected by a fetch or affected by an update, no mail is sent.

If you have the Transaction Chaining feature, all of the variables normally accessible in other Velocity contexts are available in the message template as well, for example, $responseData.last('order').orderId. See transaction chaining for more details.

You can provide the body of the email directly in the messageTemplate tag, or you can provide a filename in the templateFile attribute, which tells Smart GWT to use the contents of that file as the body of the email. If you provide neither of these, your email will have no body; if you provide both, Smart GWT will ignore the file and just use the content directly provided.

Mail server configuration
The mail server to use for sending emails is configured in the server.properties file. The following values can be provided:

mail.system.mail.smtp.host: The name of the SMTP server to use; defaults to "localhost"
mail.system.mail.smtp.port: What port is the MTA listening on; defaults to 25
mail.system.mail.smtp.auth: Whether this server requires authentication; defaults to false
mail.system.mail.smtp.user: SMTP user, if authentication is on; no default
mail.system.mail.smtp.password: Password, if authentication is on; no default

Note that we will also pass any other properties that start mail.system through to the underlying Javamail Session object, so you can use Javamail features that aren't explicitly exposed by Smart GWT's mail support. For example, many cloud-based SMTP providers require that you issue a STARTTLS command before authenticating; you can achieve this by adding the following line to server.properties:

mail.system.mail.smtp.starttls.enable: true

Field Summary

java.lang.String	bcc Comma-separated list of "BCC" recipients.
java.lang.String	cc Comma-separated list of "CC" recipients.
java.lang.String	contentType Used to override the content-type header applied to the email.
java.lang.String	encoding Used to override the character encoding we apply to the email body.
java.lang.String	from The email address the message will appear to come from.
VelocityExpression	messageData Allows you to specify an alternative source of substitution values for the templating process (by default, the data record(s) returned by the DataSource operation are used).
java.lang.String	messageTemplate The text that will form the body of the mail message.
java.lang.Boolean	multiple By default, multiple mail messages are sent if the dsResponse contains multiple records.
java.lang.String	replyTo An email address to indicate as the reply-to address on the message.
java.lang.String	subject The string to appear in the subject line of the message.
java.lang.String	templateFile Qualified name of the file containing the message template, relative to webroot.
java.lang.String	to Comma-separated list of recipients.

Constructor Summary

Mail()

Method Summary

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

templateFile

public java.lang.String templateFile

Qualified name of the file containing the message template, relative to webroot. Like all the other String properties of Mail, you can use Velocity substitution variables in this property. The content itself (ie, the contents of the file named in this property) can also contain Velocity substitutions, of course.

You must specify either this property or messageTemplate, but clearly it makes no sense to specify them both.

Default value is null

to

public java.lang.String to

Comma-separated list of recipients. Like all other String properties of Mail, you can use Velocity substitution variables in this property.

If you specify a "To:" line in the body of your email, recipient addresses will be parsed and this property will be ignored.

Default value is null

messageData

public VelocityExpression messageData

Allows you to specify an alternative source of substitution values for the templating process (by default, the data record(s) returned by the DataSource operation are used). If set, this VelocityExpression should evaluate to a Java Map object, or a Java List containing only Maps.

For example, assuming you had suitable context stored in a Map that is held in the current session as attribute "foo", the following would cause the mail templating system to look in there for values when running substitution:

      messageData="$session.foo"
  

Default value is null

messageTemplate

public java.lang.String messageTemplate

The text that will form the body of the mail message. Like all other String properties of Mail, you can use Velocity substitution variables in this property.

You must specify either this property or templateFile, but clearly it makes no sense to specify them both.

Default value is null

subject

public java.lang.String subject

The string to appear in the subject line of the message. Like all other String properties of Mail, you can use Velocity substitution variables in this property.

If you specify a "Subject:" line in the body of your email, the subject will be parsed and this property will be ignored.

Default value is null

replyTo

public java.lang.String replyTo

An email address to indicate as the reply-to address on the message. Like all other String properties of Mail, you can use Velocity substitution variables in this property.

Default value is null

from

public java.lang.String from

The email address the message will appear to come from. Like all other String properties of Mail, you can use Velocity substitution variables in this property.

If you specify a "From:" line in the body of your email, the from address will be parsed and this property will be ignored.

Default value is null

bcc

public java.lang.String bcc

Comma-separated list of "BCC" recipients. Like all other String properties of Mail, you can use Velocity substitution variables in this property.

If you specify a "Bcc:" line in the body of your email, recipient addresses will be parsed and this property will be ignored.

Default value is null

encoding

public java.lang.String encoding

Used to override the character encoding we apply to the email body. If you do not set this property, it is derived from the server.properties setting mail.system.default.encoding, which is set to "UTF-8" by default. This setting should be appropriate for most use cases.

Default value is null

multiple

public java.lang.Boolean multiple

By default, multiple mail messages are sent if the dsResponse contains multiple records. Set this property to false to prevent this behavior.

Default value is null

contentType

public java.lang.String contentType

Used to override the content-type header applied to the email. Primarily used to send HTML emails rather than plain text ones (use "text/html" to do this).

Default value is null

cc

public java.lang.String cc

Comma-separated list of "CC" recipients. Like all other String properties of Mail, you can use Velocity substitution variables in this property.

If you specify a "Cc:" line in the body of your email, recipient addresses will be parsed and this property will be ignored.

Default value is null

Constructor Detail

Mail

public Mail()