Email (value of stereotype)

From JRapid

Jump to: navigation, search

Email is a value of stereotype.


Contents

Description

The Email stereotype adds the necessary functionality to send emails.

The entity implementing the Email stereotype must declare all the necessary properties for an email, as detailed in the usage section below.

Declaring an entity with the Email stereotype does not mean that an email will be sent when the form is submitted. You need to override the method executed when the form is submitted to include the code that will send the email. The necessary code to send the email is very simple as all the logic needed is implemented by the stereotype. See the example below to see how this can be done.

By default, the application will try to use an SMTP running on the same host as the servlet container. Keep in mind that in shared development servers on the JRapid Cloud you won't be able to upload the necessary custom Java code and the SMTP server will not be available.

To change the SMTP server the application must use, you may add the corresponding properties to the jrapid.properties file. Any property with its name beginning with default.mail.smtp. on this file will be used when creating the Java SMTP transport.


If you want to use a GMail account to send mails, these are the property values you should include.

default.mail.smtp.host=smtp.gmail.com
default.mail.smtp.port=465
default.mail.smtp.auth=true
default.mail.smtp.username=youraddress@gmail.com
default.mail.smtp.password=your_password

default.mail.smtp.starttls.enable=true
default.mail.smtp.socketFactory.port=465
default.mail.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory
default.mail.smtp.socketFactory.fallback=false

Usage

<entity label= LABEL name= NAME stereotype="Email">
       <property collection="set" label=LABEL name="recipients"/>
       <property hidden="hidden" collection="set" label="CC Recipients" name="ccRecipients"/>
       <property hidden="hidden" collection="set" label="BCC Recipients" name="bccRecipients"/>
       <property display="primary" label=LABEL name="emailFrom" />
       <property hidden="hidden" label=LABEL name="replyTo"/>
       <property display="primary" label=LABEL name="subject" required="required"/>
       <property collection="set" hidden="hidden" label=LABEL name="attachmentUrls"/>
       <property hidden="hidden" label=LABEL name="txtBody" type="text"/>
       <property label=LABEL name="htmlBody" type="text"/>
       <property default="now" display="primary" fixed="fixed" hidden="hidden" 
                 label=LABEL name="emailDate" required="required" type="datetime"/>
       <property default="false" display="primary" hidden="hidden" label=LABEL name="sent" type="boolean"/>
       <property display="primary" hidden="hidden" label=LABEL name="wasRead" type="boolean"/>
</entity>

Example

If you declare your entity as shown in the next code snippet, then the generated form will look like the image below.

 <entity label="Email" name="Email" stereotype="Email">
        <property collection="set" label="Recipients" name="recipients"/>
        <property hidden="hidden" collection="set" label="CC Recipients" name="ccRecipients"/>
        <property hidden="hidden" collection="set" label="BCC Recipients" name="bccRecipients"/>
        <property display="primary" label="From" name="emailFrom" />
        <property hidden="hidden" label="Reply-To " name="replyTo"/>
        <property display="primary" label="Subject" name="subject" required="required"/>
        <property collection="set" hidden="hidden" label="Attachment" name="attachmentUrls"/>
        <property hidden="hidden" label="Message" name="txtBody" type="text"/>
        <property label="Message" name="htmlBody" type="text"/>
        <property default="now" display="primary" fixed="fixed" hidden="hidden" 
                  label="Date" name="emailDate" required="required" type="datetime"/>
        <property default="false" display="primary" hidden="hidden" label="Sent" name="sent" type="boolean"/>
        <property display="primary" hidden="hidden" label="Read" name="wasRead" type="boolean"/>
 </entity>

Note that the CC and BCC recipient properties are hidden. Remove the hidden attribute to make them visible on the form.

Email entity form

When the user fills the fields and submits the form, the application, by default, will only take care of persisting the data, but it will not send any email. You must first override the store() method in the services class and make use of the functionality added through the use of the stereotype.

The code below shows a simple example of this. In this case, the corresponding file to modify is EmailServices.java:

public class EmailServices extends EmailServicesAbstract {
   @Override
   public Object store(String id, Email voobj) {
   	voobj.send(true);
   	return super.store(id, voobj);
   }
}

The email is being sent with HTML body content due to the true value passed for the isHTML boolean parameter. This means the body content will be filled using the htmlBody property. If the parameter value is false, then the txtBody property is used to fill the body content.

Suppose you have a Company entity and you want to send an email to a sales representative every time a new record is created. The Company entity definition could be as simple as this.

<entity label="Company" menu="Menu" name="Company">
    <property display="primary" label="Name" name="name"/>
</entity>

To send the notification through email you need to overwrite the store() method in the CompanyServices class as follows. The code creates a new Email object, sets the necessary properties with values and send the email before persisting the object.

public class CompanyServices extends CompanyServicesAbstract {

	@Override
	public Object store(String id, Company voobj) {
		//Send email to Sales Representative every time a new Company is added
		if("0".equals(id)) {
			Email email = new Email();
			email.setEmailFrom("info@example.com");
			email.getRecipients().add("salesrepresentative@example.com");
			email.setSubject("New Company added! -  " + voobj.getName());
			email.setHtmlBody("The company " + voobj.getName() + " was added to the application");
			email.setEmailDate(new GregorianCalendar());
			if(email.send(true)) {
				email.setSent(true);
			}
			email.store();
		}
		
		return super.store(id, voobj);
	}
}

Methods inherited

As previously said, specifying a stereotype will make the target entity's class extend a class that will provide methods to address the specific functionality.

These are the methods provided by the Email stereotype:

  • boolean send(boolean isHTML): sends the email using the default Java mail Session and Transport. The isHTML parameter indicates if the body of the email should be sent as HTML content or plain text. Note that the entity includes an htmlBody and a txtBody property for each case.
  • boolean send(javax.mail.Transport t, javax.mail.Session session, boolean isHTML): sends the email using the Transport and Session provided by parameters. The isHTML parameter indicates if the body of the email should be sent as HTML content or plain text. Note that the entity includes an htmlBody and a txtBody property for each case.

See also

Personal tools