JavaMail Support | Professional Apache Geronimo (Wrox Professional Guides)

Geronimo supports programmatic sending and receiving of email. Out of the box, Geronimo allows J2EE applications to work with email messages using the industry standard JavaMail 1.3 APIs. JavaMail is a set of APIs that enables developers to manipulate email independently of the underlying operating system and hardware platform, and independent of the actual mail transport protocols. For more information on the JavaMail API, see the following URL:

http://java.sun.com/products/javamail/index.jsp

JavaMail Transports

While the JavaMail API can work with all popular email transports such as SMTP, POP, and IMAP, the included Geronimo 1.1 implementation supports only SMTP. If your installation requires protocol support beyond SMTP, you must add third-party libraries. A more extensive module is currently under development in the Geronimo sandbox. When ready, this library will support additional protocols such as POP, and may become available as a Geronimo plug-in.

The Geronimo sandbox is where new contributions for Geronimo are incubated. These are typically system modules or sample applications. These modules are developed and tested in isolation, within the sandbox, until the Geronimo community (voted by committers) feels that the module is ready for integration into the mainstream code base.

The JavaMail API is a client-side unified API for working with differing email transport protocols. It is important to note that JavaMail support on a J2EE 1.4 server does not imply that the server may be used as a server for relaying email across the Internet. Internet mail servers are specialized servers that can work with a variety of email formats, protocols, and a very high volume of email continuously.

Handling email relay is out of the scope of the J2EE 1.4 specification, which focuses on the construction of componentized business applications. In contrast to a mail server, the JavaMail support is in J2EE 1.4, and Geronimo plays a purely client-side role.

MailSession GBean

Geronimo 1.1 provides JavaMail support through a specialized GBean. This GBean is implemented as a system module. The module is installed, but not started, by default. Following is the module ID for the JavaMail support module:

 geronimo/javamail/1.1/car

The actual programming of the JavaMail API is out of the scope of this chapter. However, Geronimo administrators should know how to enable the use of this API and to configure the component to use a specific email server (by specifying the TCP address and port of the mail server).

The geronimo/javamail/1.1/car module is not started by default. You can start this module by performing one or both of the following:

Specifying it as a dependency in your application
Manually starting the module in the Web console or command-line deployer

Enabling JavaMail System Module via config.xml

To enable JavaMail support, and to configure the SMTP server that you will be using, you must edit the var/config/config.xml file. Remember to make sure that the Geronimo server is not running locally before editing this file.

The following shows the modifications that you need to make to enable JavaMail support.

 ... <module load="false" name="geronimo/javamail/1.1/car"> <gbean name="SMTPTransport"> <attribute name="host">localhost</attribute> <attribute name="port">25</attribute> </gbean> </module> ...

In the preceding listing, the module’s load attribute value is changed to load="true". This will cause the Geronimo server to load the geronimo/javamail/1.1/car module on the next startup. The host and port attributes for the SMTP transport are configured (overridden) via attributes of the SMTPTransport GBean.

 <module     xmlns="http://geronimo.apache.org/xml/ns/deployment-1.1"     >     <gbean name="mail/MailSession" >         <attribute name="transportProtocol">smtp</attribute>     </gbean>     <gbean name="SMTPTransport" >         <attribute name="host">localhost</attribute>         <attribute name="port">25</attribute>     </gbean> </module>

Reference to the Container-Managed JavaMail Session

Developers creating applications can reference this container-managed mail session by adding a <resource-ref> entry in their J2EE deployment descriptor. For a Web application, this can be included in the web.xml deployment descriptor, in a form similar to the following highlighted code:

 <?xml version="1.0" encoding="ISO-8859-1"?> <web-app xmlns="http://java.sun.com/xml/ns/j2ee"     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"     xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"     version="2.4">     <servlet>       <servlet-name>myservlet</servlet-name>       <servlet-class>MyServlet</servlet-class>    </servlet>    <servlet-mapping>      <servlet-name>myservlet</servlet-name>      <url-pattern>/mymail.cgi</url-pattern>    </servlet-mapping>    <resource-ref>       <res-ref-name>wrox/mailSession</res-ref-name>       <res-type>javax.mail.Session</res-type>       <res-auth>Container</res-auth>       <res-sharing-scope>Shareable</res-sharing-scope>    </resource-ref> </web-app>

This deployment descriptor configures a <resource-ref> with name wrox/mailSession, pointing to a container-managed javax.mail.Session object. This session can be accessed by application code by looking up via JNDI the name java:comp/env/wrox/mailSession.

Linking to the Container-Managed JavaMail Session

To link the reference name of wrox/mailSession to the JavaMail support system module’s mail/Mail Session GBean, the Geronimo administrator must create a Geronimo-specific deployment plan. For a Web application, this can be configured in a geronimo-web.xml plan similar to the following:

 <?xml version="1.0" encoding="ISO-8859-1"?>    <web-app   xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1"    >     <environment>     <moduleId>         <groupId>wrox</groupId>         <artifactId>progeronjmail</artifactId>         <version>1.0</version>         <type>car</type>       </moduleId>      <dependencies>        <dependency>         <groupId>geronimo</groupId>         <artifactId>javamail</artifactId>         <version>1.1</version>         <type>car</type>         </dependency>       </dependencies>      </environment>       <context-root>/progeron</context-root>       <resource-ref>           <ref-name>wrox/mailSession</ref-name>           <resource-link>mail/MailSession</resource-link>       </resource-ref>  </web-app>

The highlighted code tells Geronimo that this module is dependent on the Geronimo/javamail/ 1.1/car module. It also configures a <resource-ref>, with the name wrox/mailSession, pointing to a Geronimo-managed resource named mail/MailSession. This is the JavaMail session GBean configured in the geronimo/javamail/1.1/car module, and with properties configured in the config.xml file.