JavaMail Integration Information

The JavaMail integration code provided in this demonstration shows how you can use middle tier Java integration via the Java Importer to integrate Forms with widely available Java functions and utilities.

In this case the integration is with the javax.mail package (see http://java.sun.com/products/javamail/index.html).  This allows you to send e-mails, with or without attachments, using the Simple Mail Transport Protocol (SMTP).  In order for this demo to work, you will need access to an SMTP server.

The integration takes the Form of a simple wrapper java class (oracle.forms.demos.javamail.SendMessage) that provides a simple interface in the form of a single method send().  This class has been integrated into PL/SQL using the PL/SQL importer to create a PL/SQL package SENDMESSAGE.  The send method is a static Java Method, so it can be used from PL/SQL just like a normal PL/SQL function, and without the need to create a new SendMessage object first.

As well as the SendMessage class there is a second Java class as part of the utility which is the oracle.forms.demos.javamail.SendMessageException Class.  If the E-mail cannot be send for some reason then an exception of type SendMessageException will be raised.  See the section Handling Errors for information on how to diagnose the problem

Modules In This Demo

The JavaMail integration demo consists of the following files (relative directories shown in brackets):

  1. javamail.fmb/fmx [forms]- The demo form
  2. SendMessage.java [src/oracle/forms/demo/javamail] - source code for mail integration class
  3. SendMessageException.java [src/oracle/forms/demo/javamail] - source code for mail integration exception class
  4. sendmail.jar [classes]- the compiled and jarred java classes.

The doc directory and the classes directory contain the JavaDoc for the code and the compiled classes respectively

Reusing the code

Setting up Forms Services

In order for an application to be able to reuse the JavaMail integration code provided, some changes need to be made to the environment that Forms Services on the middle tier is running with.  The easy way to do this is to create a custom environment file which you can then reference from the relevant configuration in the formsweb.cfg file.

This environment file should make sure that the CLASSPATH used by Forms Services includes the following JAR files: 

A sample .env might be.

# javamail.env
# Environment file used for JavaMail Integration
ORACLE_HOME=c:\oracle\DevSuiteHome
PATH=c:\oracle\DevSuiteHome\jdk\jre\bin\classic;c:\oracle\DevSuiteHome\bin
CLASSPATH=c:\oracle\DevSuiteHome\\forms\\demos\jars\javamailintegration.jar,c:\oracle\DevSuiteHome\\forms\\demos\jars\mail.jar;c:\oracle\DevSuiteHome\\forms\\demos\jars\activation.jar;c:\oracle\DevSuiteHome\\forms\\demos\jars\uploadserver.jar;c:\oracle\DevSuiteHome\jdk\jre\lib\rt.jar
FORMS_path=c:\oracle\DevSuiteHome\\forms\\demos\lib;c:\oracle\DevSuiteHome\\forms\\demos\JavaMail\forms

 

In this case the Environment file also includes uploadserver.jar in the Classpath.  This is the Java code used by the fileupload facility which the Java Mail demo uses to pull attachments from the client machine for inclusion in the e-mail.

An entry in the formsweb.cfg file to call the JavaMail integration demo would look like this, note t he addition of the custom env file javamail.env:

 

[JavaMail]
pageTitle=OracleAS Forms Services - JavaMail Integration
IE=jinitiator
baseHTMLJInitiator=demobasejini.html
archive_jini=frmall_jinit.jar,/formsdemo/jars/demo.jar 
width=675
height=480
separateFrame=false
splashScreen=no
lookAndFeel=oracle
colorScheme=blue
form=javamailforms/java
background=/formsdemo/images/blue.gif
otherparams=demo_root=c:\demo
envFile=javamail.env

 

Adding the code to your Form

To integrate the SendMessage code into your Form or Library you can simply copy the SendMessage and SendMessageException packages (bodies and headers) from the sample Form.  You could also manually import the oracle.forms.demos.javamail.SendMessage and oracle.forms.demos.javamail.SendMessageException classes using the Java Importer.

Calling the Send function

As mentioned above, the send() method in the provided SendMessage class is a static function.  There is no need to create a instance of a SendMessage object first.  So to send an e-mail, simply call the SendMessage.send() procedure with the required arguments for the e-mail. The prototype for the send procedure is:

 PROCEDURE send(
  SMTP_SERVER      VARCHAR2,
  FROM             VARCHAR2,
  TO               VARCHAR2,
  SUBJECT          VARCHAR2,
  MESSAGE_TEXT     VARCHAR2,
  ATTACHMENT_LIST  VARCHAR2);

If you want to send attachments with the e-mail, the attachments should be passed to the SendMessage.send() procedure as a comma separated list of filenames.  Any files that are provided in this argument should already be present on the Forms Server machine and accessible to the Forms Runtime.  If you need to attach files from the end users machine you can use the FileUpload Bean to transfer the file to the middle tier before sending the mail.  This is done as an example by the provided demo form. 

Handling Errors

Errors in Java code that has been imported using the Java Importer are raised in the form of PL/SQL exceptions.  Two possible exceptions will be raised

If an problem occurs in the SendMessage.send() procedure an exception of type SendMessageException will be raised. The typical code to handle this would be:

DECLARE
  jex      ORA_JAVA.JEXCEPTION;
BEGIN
  ...
  SendMessage.send(...);
  ...
EXCEPTION
  WHEN ORA_JAVA.EXCEPTION_THROWN then
    begin
      jex := ORA_JAVA.LAST_EXCEPTION;
      Message(SendMessageException.toString(jex));
    exception
    	WHEN ORA_JAVA.EXCEPTION_THROWN then
    	  -- can't find the SendmessageException class therefore classpath is wrong
    	  Message('Your classpath is not correctly defined in your environment file.  The JavaMail jar files cannot be located');
    end;
  WHEN ORA_JAVA.JAVA_ERROR then
    -- some sort of unexpected Java Error such as being unable to start the JVM
    message('Java Error: '||ORA_JAVA.LAST_ERROR);
END;