public class SmtpEmail extends java.lang.Object implements WrappedResource, EmailSender, Deletable
SmtpEmail
object is a handle based
resource with attributes and methods that can be used to define the email's state and to send
the email. The sending will occur on the client.
This is a FWD-specific set of functionality. It does not exist and will not run in the Progress 4GL.
To create an SMTP-EMAIL resource use the following syntax:
CREATE SMTP-EMAIL handle [ASSIGN { ATTR_OR_METHOD = value ...}].The following list of attributes are available:
Attribute Data Type Required Description ---------------- ------------ -------- ------------------------------------------------------------------------------------------------ connection-type character Y Must be "UNENCRYPTED", "STARTTLS_WHEN_AVAILABLE", "STARTTLS_REQUIRED" or "SSL". smtp-from character Y This is the FROM address (the email address of the sender). smtp-host character Y This is the SMTP server's IP address or hostname. smtp-html character N If set, this is the content of the HTML body. smtp-port character N Defaults to 25 for UNENCRYPTED, 587 for STARTTLS_* and 465 for SSL. smtp-reply-to character N Optional REPLY-TO address. smtp-subject character Y This is the subject line. smtp-text character N If set, this is the content of the HTML body. smtp-user character N If both the user and the password are NOT set, then no authentication will be attempted. If set, this is the userid for authentication with the SMTP server. smtp-password character N If both the user and the password are NOT set, then no authentication will be attempted. If set, this is the password for authentication with the SMTP server. smtp-validate logical N Defaults to TRUE. If FALSE, the SMTP server's SSL certificate will be treated as trusted. Ignored for UNENCRYPTED mode.
The following list of methods are available:
Method Return Type Return Meaning Required Description -------------------------------- ----------- -------------- -------- ----------------------------------------------------------------------------------------------------- add-to-address(character addr) logical TRUE on success. N This adds a TO address to the mail. At least one recipient is needed. add-cc-address(character addr) logical TRUE on success. N This adds a CC address to the mail. At least one recipient is needed. add-bcc-address(character addr) logical TRUE on success. N This adds a BCC address to the mail. At least one recipient is needed. attach-file(character filename) logical TRUE on success. N This attaches a local file to the email. The file must exist and be accessible to the user. attach-file(character url) logical TRUE on success. N This attaches a resource specified by URL to the email. The resource will be downloaded when the email is sent. The URL must exist and be accessible to the user. clear-attachments-list() logical TRUE on success. N Deletes everything in the attachments list. clear-bcc-list() logical TRUE on success. N Deletes everything in the BCC address list. clear-cc-list() logical TRUE on success. N Deletes everything in the CC address list. clear-embedded-image-list() logical TRUE on success. N Deletes everything in the embedded image list. clear-to-list() logical TRUE on success. N Deletes everything in the TO address list. embed-file(character filename) character CONTENT-ID N Adds a local file to the embedded image list and returns the content ID to be substituted into the IMG tag of the HTML body. The file must exist and be accessible to the user. embed-url(character filename) character CONTENT-ID N Adds a URL resource to the embedded image list and returns the content ID to be substituted into the IMG tag of the HTML body. The resource will be downloaded when the email is sent. The URL must exist and be accessible to the user. get-attachments-list() character[] List as an array. N Returns the attachments list as an array. get-bcc-list() character[] List as an array. N Returns the BCC address list as an array. get-cc-list() character[] List as an array. N Returns the CC address list as an array. get-embedded-image-list() character[] List as an array. N Returns the embedded image list as an array. get-to-list() character[] List as an array. N Returns the TO address list as an array. send() logical TRUE on success. Y Sends the email as previously defined. You can call this more than once (possibly changing the state of the handle each time). Every time this is called it will attempt to send the defined email. This may raise an ERROR condition if there are any problems during send.
At the end of lifetime of the object, it should be deleted, as usual with
DELETE OBJECT handle.
Modifier and Type | Class and Description |
---|---|
private static class |
SmtpEmail.ContextContainer
Simple container that stores and returns a context-local instance of
the remote email sender.
|
Modifier and Type | Field and Description |
---|---|
private EmailDefinition |
def
Serializable container for email state.
|
private static SmtpEmail.ContextContainer |
remoteSender
Stores context-local state variables.
|
private java.lang.Long |
resourceId
The resource id.
|
private boolean |
valid
Flag to determine if this instance has been deleted.
|
Constructor and Description |
---|
SmtpEmail()
Construct an instance.
|
Modifier and Type | Method and Description |
---|---|
logical |
addBccAddress(character addr)
Add a BCC address to the list of recipients.
|
logical |
addBccAddress(java.lang.String addr)
Add a BCC address to the list of recipients.
|
logical |
addCcAddress(character addr)
Add a CC address to the list of recipients.
|
logical |
addCcAddress(java.lang.String addr)
Add a CC address to the list of recipients.
|
logical |
addToAddress(character addr)
Add a TO address to the list of recipients.
|
logical |
addToAddress(java.lang.String addr)
Add a TO address to the list of recipients.
|
logical |
attachFile(character file)
Attach the specified file to the email.
|
logical |
attachFile(java.lang.String file)
Attach the specified file to the email.
|
logical |
attachURL(character url)
Attach the file specified by the given URL to the email.
|
logical |
attachURL(java.lang.String url)
Attach the file specified by the given URL to the email.
|
logical |
clearAttachmentsList()
Clear the list of attachments.
|
logical |
clearBccAddressList()
Clear the list of BCC recipients.
|
logical |
clearCcAddressList()
Clear the list of CC recipients.
|
logical |
clearEmbeddedImageList()
Clear the list of embedded images.
|
logical |
clearToAddressList()
Clear the list of TO recipients.
|
static void |
create(handle h)
Static factory method for initialization of a fresh new SMTP EMAIL as an extension object.
|
void |
delete()
Perform actual delete of all resources.
|
character |
embedImageByFile(character file)
Embed the image specified by the given file and return the content ID needed to substitute
into the HTML (in an IMG tag).
|
character |
embedImageByFile(java.lang.String file)
Embed the image specified by the given file and return the content ID needed to substitute
into the HTML (in an IMG tag).
|
character |
embedImageByURL(character url)
Embed the image specified by the given URL and return the content ID needed to substitute
into the HTML (in an IMG tag).
|
character |
embedImageByURL(java.lang.String url)
Embed the image specified by the given URL and return the content ID needed to substitute
into the HTML (in an IMG tag).
|
character[] |
getAttachmentsList()
Obtain the list of attachments.
|
character[] |
getBccAddressList()
Obtain the list of BCC recipients.
|
character[] |
getCcAddressList()
Obtain the list of CC recipients.
|
character |
getConnectionType()
Gets the connection type for the SMTP communications session.
|
character[] |
getEmbeddedImageList()
Obtain the list of embedded image file and URL names.
|
character |
getSmtpFrom()
Gets the FROM address.
|
character |
getSmtpHost()
Gets the host for the SMTP server.
|
character |
getSmtpHtmlBody()
Gets the HTML body contents.
|
character |
getSmtpPassword()
Gets the password for authenticating with the SMTP server.
|
character |
getSmtpPort()
Gets the port for the SMTP server.
|
character |
getSmtpReplyTo()
Gets the REPLY-TO address.
|
character |
getSmtpSubject()
Gets the SUBJECT line.
|
character |
getSmtpTextBody()
Gets the TEXT body contents.
|
character |
getSmtpUser()
Gets the userid for authenticating with the SMTP server.
|
character[] |
getToAddressList()
Obtain the list of TO recipients.
|
java.lang.Long |
id()
Get this resource's ID, if is already set.
|
void |
id(long id)
Set this resource's ID.
|
logical |
isSmtpValidate()
Returns the state of the SMTP-VALIDATE attribute, which determines if the SMTP server
certificate is validated during an SSL or STARTTLS connection.
|
logical |
send()
Send the email.
|
void |
setConnectionType(character type)
Sets the connection type for the SMTP communications session.
|
void |
setConnectionType(java.lang.String type)
Sets the connection type for the SMTP communications session.
|
void |
setSmtpFrom(character from)
Sets the FROM address.
|
void |
setSmtpFrom(java.lang.String from)
Sets the FROM address.
|
void |
setSmtpHost(character host)
Sets the host for the SMTP server.
|
void |
setSmtpHost(java.lang.String host)
Sets the host for the SMTP server.
|
void |
setSmtpHtmlBody(character html)
Sets the HTML body contents.
|
void |
setSmtpHtmlBody(java.lang.String html)
Sets the HTML body contents.
|
void |
setSmtpPassword(character password)
Sets the password for authenticating with the SMTP server.
|
void |
setSmtpPassword(java.lang.String password)
Sets the password for authenticating with the SMTP server.
|
void |
setSmtpPort(character port)
Sets the port for the SMTP server.
|
void |
setSmtpPort(java.lang.String port)
Sets the port for the SMTP server.
|
void |
setSmtpReplyTo(character replyTo)
Sets the REPLY-TO address.
|
void |
setSmtpReplyTo(java.lang.String replyTo)
Sets the REPLY-TO address.
|
void |
setSmtpSubject(character subject)
Sets the SUBJECT line.
|
void |
setSmtpSubject(java.lang.String subject)
Sets the SUBJECT line.
|
void |
setSmtpTextBody(character text)
Sets the TEXT body contents.
|
void |
setSmtpTextBody(java.lang.String text)
Sets the TEXT body contents.
|
void |
setSmtpUser(character userid)
Sets the userid for authenticating with the SMTP server.
|
void |
setSmtpUser(java.lang.String userid)
Sets the userid for authenticating with the SMTP server.
|
void |
setSmtpValidate(boolean validate)
Setter for SMTP-VALIDATE attribute, which determines if the SMTP server certificate is
validated during an SSL or STARTTLS connection.
|
void |
setSmtpValidate(logical validate)
Setter for SMTP-VALIDATE attribute, which determines if the SMTP server certificate is
validated during an SSL or STARTTLS connection.
|
private character[] |
stringArrayToCharacterArray(java.lang.String[] list)
Convert the given string array into a charaacter array.
|
boolean |
unknown()
Reports if this object is unknown.
|
boolean |
valid()
Checks whether this object is valid.
|
private static SmtpEmail.ContextContainer remoteSender
private java.lang.Long resourceId
WrappedResource
management.private boolean valid
private EmailDefinition def
public static void create(handle h)
h
- The handle
to store the newly created object.public boolean unknown()
unknown
in interface WrappedResource
true
if object is unknown.public java.lang.Long id()
id
in interface WrappedResource
null
if not set.public void id(long id)
id
in interface WrappedResource
id
- The resource's ID.public void delete()
This is called from a handle when working as FWD extension object.
public boolean valid()
valid
in interface WrappedResource
true
if this object is valid.public character getConnectionType()
getConnectionType
in interface EmailSender
public void setConnectionType(character type)
setConnectionType
in interface EmailSender
type
- The connection type which must be "UNENCRYPTED", "STARTTLS_WHEN_AVAILABLE",
"STARTTLS_REQUIRED" or "SSL". Must not be null
or unknown.public void setConnectionType(java.lang.String type)
setConnectionType
in interface EmailSender
type
- The connection type which must be "UNENCRYPTED", "STARTTLS_WHEN_AVAILABLE",
"STARTTLS_REQUIRED" or "SSL". Must not be null
.public character getSmtpHost()
getSmtpHost
in interface EmailSender
public void setSmtpHost(character host)
setSmtpHost
in interface EmailSender
host
- The name or IP address of the SMTP server. Must not be null
or unknown.public void setSmtpHost(java.lang.String host)
setSmtpHost
in interface EmailSender
host
- The name or IP address of the SMTP server. Must not be null
.public character getSmtpPort()
getSmtpPort
in interface EmailSender
public void setSmtpPort(character port)
setSmtpPort
in interface EmailSender
port
- The port used by the SMTP server.public void setSmtpPort(java.lang.String port)
setSmtpPort
in interface EmailSender
port
- The port used by the SMTP server.public character getSmtpUser()
getSmtpUser
in interface EmailSender
public void setSmtpUser(character userid)
setSmtpUser
in interface EmailSender
userid
- The userid for authentication.public void setSmtpUser(java.lang.String userid)
setSmtpUser
in interface EmailSender
userid
- The userid for authentication.public character getSmtpPassword()
getSmtpPassword
in interface EmailSender
public void setSmtpPassword(character password)
setSmtpPassword
in interface EmailSender
password
- The password for authentication.public void setSmtpPassword(java.lang.String password)
setSmtpPassword
in interface EmailSender
password
- The password for authentication.public logical isSmtpValidate()
isSmtpValidate
in interface EmailSender
public void setSmtpValidate(boolean validate)
setSmtpValidate
in interface EmailSender
validate
- true
to validate the server certificate.public void setSmtpValidate(logical validate)
setSmtpValidate
in interface EmailSender
validate
- true
to validate the server certificate.public character getSmtpFrom()
getSmtpFrom
in interface EmailSender
public void setSmtpFrom(character from)
setSmtpFrom
in interface EmailSender
from
- The FROM address.public void setSmtpFrom(java.lang.String from)
setSmtpFrom
in interface EmailSender
from
- The FROM address.public character getSmtpReplyTo()
getSmtpReplyTo
in interface EmailSender
public void setSmtpReplyTo(character replyTo)
setSmtpReplyTo
in interface EmailSender
replyTo
- The REPLY-TO address.public void setSmtpReplyTo(java.lang.String replyTo)
setSmtpReplyTo
in interface EmailSender
replyTo
- The REPLY-TO address.public character getSmtpSubject()
getSmtpSubject
in interface EmailSender
public void setSmtpSubject(character subject)
setSmtpSubject
in interface EmailSender
subject
- The SUBJECT line.public void setSmtpSubject(java.lang.String subject)
setSmtpSubject
in interface EmailSender
subject
- The SUBJECT line.public character getSmtpHtmlBody()
getSmtpHtmlBody
in interface EmailSender
public void setSmtpHtmlBody(character html)
setSmtpHtmlBody
in interface EmailSender
html
- The HTML body contents.public void setSmtpHtmlBody(java.lang.String html)
setSmtpHtmlBody
in interface EmailSender
html
- The HTML body contents.public character getSmtpTextBody()
getSmtpTextBody
in interface EmailSender
public void setSmtpTextBody(character text)
setSmtpTextBody
in interface EmailSender
text
- The TEXT body contents.public void setSmtpTextBody(java.lang.String text)
setSmtpTextBody
in interface EmailSender
text
- The TEXT body contents.public logical addToAddress(character addr)
addToAddress
in interface EmailSender
addr
- The TO address.public logical addToAddress(java.lang.String addr)
addToAddress
in interface EmailSender
addr
- The TO address.public logical addCcAddress(character addr)
addCcAddress
in interface EmailSender
addr
- The CC address.public logical addCcAddress(java.lang.String addr)
addCcAddress
in interface EmailSender
addr
- The CC address.public logical addBccAddress(character addr)
addBccAddress
in interface EmailSender
addr
- The BCC address.public logical addBccAddress(java.lang.String addr)
addBccAddress
in interface EmailSender
addr
- The BCC address.public logical attachFile(character file)
attachFile
in interface EmailSender
file
- The file to attach.public logical attachFile(java.lang.String file)
attachFile
in interface EmailSender
file
- The file to attach.public logical attachURL(character url)
attachURL
in interface EmailSender
url
- The resource to attach.public logical attachURL(java.lang.String url)
attachURL
in interface EmailSender
url
- The resource to attach.public logical clearAttachmentsList()
clearAttachmentsList
in interface EmailSender
public logical clearBccAddressList()
clearBccAddressList
in interface EmailSender
public logical clearCcAddressList()
clearCcAddressList
in interface EmailSender
public logical clearEmbeddedImageList()
clearEmbeddedImageList
in interface EmailSender
public logical clearToAddressList()
clearToAddressList
in interface EmailSender
public character embedImageByFile(character file)
embedImageByFile
in interface EmailSender
file
- The resource to attach.public character embedImageByFile(java.lang.String file)
embedImageByFile
in interface EmailSender
file
- The resource to attach.public character embedImageByURL(character url)
embedImageByURL
in interface EmailSender
url
- The resource to attach.public character embedImageByURL(java.lang.String url)
embedImageByURL
in interface EmailSender
url
- The resource to attach.public character[] getAttachmentsList()
getAttachmentsList
in interface EmailSender
public character[] getBccAddressList()
getBccAddressList
in interface EmailSender
public character[] getCcAddressList()
getCcAddressList
in interface EmailSender
public character[] getEmbeddedImageList()
getEmbeddedImageList
in interface EmailSender
public character[] getToAddressList()
getToAddressList
in interface EmailSender
public logical send() throws ErrorConditionException
send
in interface EmailSender
true
if the send succeeded.ErrorConditionException
- On any failure, unless silent error mode is enabled.private character[] stringArrayToCharacterArray(java.lang.String[] list)
list
- Input array.