Skip to content

Latest commit

 

History

History
172 lines (130 loc) · 8.42 KB

README-source.adoc

File metadata and controls

172 lines (130 loc) · 8.42 KB

mail: E-Mail Example using CDI and JSF

The mail quickstart demonstrates how to send and receive emails using CDI and JSF and with custom Mail provider configured in {productName}.

What is it?

The mail quickstart demonstrates sending and receiving emails with the use of CDI (Contexts and Dependency Injection) and JSF (JavaServer Faces) in {productNameFull}.

The mail provider is configured in the mail subsystem of the {jbossHomeName}/standalone/configuration/standalone.xml configuration file if you are running a standalone server or in the {jbossHomeName}/domain/configuration/domain.xml configuration file if you are running in a managed domain.

You can use the default mail provider that comes out of the box with {productName}. It uses your local mail relay and the default SMTP port of 25. However, this quickstart demonstrates how to define and use a custom mail provider.

This example is a web application that takes To, From, Subject, and Message Body input and sends mail using SMTP. These emails can be later read by using IMAP or POP3. The front end is a JSF page with a simple POJO backing, leveraging CDI for resource injection.

Configure a Mail Server on Your Local Machine

To run the Mail Quickstart, you need a Mail Server configured with the following protocols and ports:

  • SMTP port:1025

  • POP3 port:1110

  • IMAP port:1143

In addition, the Mail Subsystem configuration and the test cases expect you have the following Mail accounts configured on your Mail Server:

You can use any Mail Server you consider, although to facilitate this task, you will find under the Mail Quickstart root directory a docker compose file prepared to launch a Greenmail mail server with all the required configuration. You will need to have installed a Container Engine capable of working with Docker compose files and Linux images. The following command assumes you have Podman and Podman Compose installed in your local environment.

To launch the Greenmail server, open the terminal and navigate to the Mail Quickstart root directory and execute the following:

$ podman compose up --wait
>>>> Executing external compose provider "/usr/local/bin/docker-compose". Please refer to the documentation for details. <<<<

Once you have finished with the Mail Quickstart, you can shutdown and remove the Greenmail server with the following command:

$ podman compose down --volumes
>>>> Executing external compose provider "/usr/local/bin/docker-compose". Please refer to the documentation for details. <<<<

Configure the Server

You configure the custom mail session in {productName} by running Management CLI commands. For your convenience, this quickstart batches the commands into a configure-mail-session.cli script provided in the root directory of this quickstart.

  1. Before you begin, make sure you do the following:

  2. Review the configure-mail-session.cli file in the root of this quickstart directory. This script creates custom outbound socket binding port for SMTP, POP3, and IMAP. It then creates the custom MyOtherMail mail session and configures it to use the custom outbound socket binding ports and default user credentials for SMTP and IMAP.

  3. Open a new terminal, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server:

    $ {jbossHomeName}/bin/jboss-cli.sh --connect --file=configure-mail-session.cli
    Note
    		 For Windows, use the {jbossHomeName}\bin\jboss-cli.bat script.

    You should see the following result when you run the script.

    The batch executed successfully
process-state: reload-required

  4. Stop the {productName} server.

Review the Modified Server Configuration

After stopping the server, open the {jbossHomeName}/standalone/configuration/standalone.xml file and review the changes.

The following outbound-socket-binding groups are added to the standard-sockets <socket-binding-group> element.

<socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:0}">
  ...
  <outbound-socket-binding name="my-imap-binding">
      <remote-destination host="localhost" port="1143"/>
  </outbound-socket-binding>
  <outbound-socket-binding name="my-pop3-binding">
      <remote-destination host="localhost" port="1110"/>
  </outbound-socket-binding>
  <outbound-socket-binding name="my-smtp-binding">
     <remote-destination host="localhost" port="1025"/>
  </outbound-socket-binding>
</socket-binding-group>

The MyOtherMail mail session is added to the mail subsystem and configured to use the custom outbound socket binding ports.

<subsystem xmlns="{MailSubsystemNamespace}">
   <mail-session name="default" jndi-name="java:jboss/mail/Default">
      <smtp-server outbound-socket-binding-ref="mail-smtp"/>
   </mail-session>
   <mail-session name="MyOtherMail" debug="true" jndi-name="java:jboss/mail/MyOtherMail">
     <smtp-server outbound-socket-binding-ref="my-smtp-binding" username="[email protected]" password="1234"/>
     <pop3-server outbound-socket-binding-ref="my-pop3-binding"/>
     <imap-server outbound-socket-binding-ref="my-imap-binding" username="[email protected]" password="1234"/>
   </mail-session>
</subsystem>

Access the Application

The application will be running at the following URL: http://localhost:8080/{artifactId}/.

Note
 If you see Error processing request in the browser when you access the application and attempt to send email, followed by jakarta.servlet.ServletException: MailConnectException: Couldn't connect to host, port: localhost, 1025; timeout -1; nested exception is: java.net.ConnectException: Connection refused, make sure you followed the instructions above to Configure an SMTP Server on Your Local Machine. ../shared-doc/run-integration-tests-with-server-distribution.adoc ../shared-doc/undeploy-the-quickstart.adoc ../shared-doc/restore-standalone-server-configuration.adoc

This script removes the custom MyOtherMail session from the mail subsystem in the server configuration. file You should see the following result when you run the script:

The batch executed successfully
process-state: reload-required