JavaMail API

The Oracle Javamail Service Provider (OJMA) implements the standard interfaces available with the Sun Javamail API(s) version 1.2. In addition, OJMA provides integration with Oracle Text, integration with Oracle S/MIME toolkit, support for Shared Folders, and support for Server Side Rules. The Javamail APIs can be used to authenticate the user, and perform folder and message operations. OJMA is integrated with Oracle Internet Directory (OID) and provides customized methods in the OracleStore class to authenticate mail users.

See Also:

The Oracle9iAS Unified Messaging JAVA API Documentation on http://otn.oracle.com for information about the OJMA Extensions

See Also:

The Javamail Web site for Javamail documentation

This section provides the following examples for using the JavaMail API:

Creating a Shared Folder and Granting User Permissions

The following is an example of creating a shared folder and granting permissions to a user. The shared folder name and the user(grantee) are taken in as parameters in addition to the shared folder owner and the owner password.

Directory Management API

The directory management API is a set of Java classes that can be used to create, access, and manage various entries, such as mail users, public distribution lists, and private address book entries (contact information and private distribution lists). The entries are stored in the LDAP directory for a given domain.

Directory Components

In Oracle9iAS Unified Messaging, an e-mail system can contain more than one domain. Mail users and public distribution lists exist for a particular domain. A mail user for a given domain is a valid user in that domain who can send and receive e-mail and use all of the exposed e-mail server functionality.

A public distribution lists is a mailing list that has an its own e-mail ID and contains a group of e-mail IDs or other mailing lists. When an e-mail is sent to a public distribution list, all the members of the list receive the e-mail. A valid mail user can subscribe to any public distribution list.

A private distribution list consists of private contact information, such as the contact's phone number, e-mail ID, and address. Users can use the private address book entries from the Thin Client to send and receive e-mails. These entries are also used by the Calendar application.

Authentication

Before a caller can access any of the directory components, the caller must authenticate with the LDAP directory using the oracle.mail.OESContext class. Once authenticated, the instance of oracle.mail.OESContext representing a trusted session must be passed to all of the directory APIs.

Authentication Example:

Retrieving the MetaData and Validation

Before an entry is created in the directory, the caller needs to retrieve the metadata for that particular entry from the directory. The metadata for a particular entry consists of the mandatory and optional attributes the caller must set in order to create an entry. It also contains information about all the attributes, such as the syntax, multiplicity of the attributes, and default values for attributes (if any defaults are set in the directory.

When the caller sets the attribute value on the metadata object, validation is performed to ensure that the caller sets the value of an attribute that is present in that particular entry. In UI-based applications using the metadata, the caller can perform any input validations for the data entered.

Similarly, the ldapobj.getOptionalAttribs() method returns the list of optional attributes and in a similar manner, the optional attributes and the metadata can be retrieved. After retrieving the metadata, the user can set the value of an attribute in the following manner. When creating an entry, the attribute value can be set using the setAttributeValue method of the ESDSLdapObject class.

Example:

This example sets the value for the telephonenumber attribute.

//This sets the value to the default values provided mdata.getDefaultValues() is
not null
ldapobj.setAttributeValue("telephonenumber", mdata.getDefaultValues());

This example sets a new set of values for the telephonenumber attribute.

Private Address Book Contact Information Examples

The following code describes how to use the private address book contact information APIs to create, modify, look up, resolve, and search contacts.

/** Getting Contact Info Metadata And Creating A New Contact Info **/ ESDSLdapObject ldapobj = dirAccess.GetContactInfoMetaData(oesctx); //This example sets the name and email id of the new contact. Other attributes
can be set in a similar way. ldapobj.setAttributeValue("name","myfriend1"); ldapobj.setAttributeValue("orclmailemail","test@hotmail.com"); // Now Create The Contact dirAccess. CreateContactInfo(oesctx, ldapobj);/** Looking up a Contact Info **/ ldapobj = dirAccess.LookupContactInfo(oesctx,"myfriend1");/*** Modifying a Contact **/ //Modifying the given name of the contact Vector modify = new Vector(); modify.add ("myfriend_name"); ldapobj.modifyAttributeValue("givenname", modify, ESDSConstants.DS_MODIFY_ADD);dirAccess.ModifyContactInfo(oesctx, "myfriend1",ldapobj);/*** Delete A Contact Info ***/ dirAccess.DeleteContactInfo(oesctx,"friend ");/** Get All Contacts **/ String[] contacts = dirAccess.GetAllContacts(oesctx); /** Get All Contacts For a Given Filter **/ contacts = dirAccess.SearchContacts(oesctx,"name=t*");

Private Distribution List Example

The following code describes how to use the private distribution list APIs to create, modify, look up, resolve, and search contacts.

/** Getting Private List Metadata And Creating A New Private List **/ ESDSLdapObject ldapobj = dirAccess.GetPrivateListMetaData(oesctx); //This example sets the name and email id of the new contact. Other attributes
can be set in a similar way. ldapobj.setAttributeValue("name","myfriends"); ldapobj.setAttributeValue("orclmailemail","test@hotmail.com"); ldapobj.setAttributeValue("orclmailemail","test2@hotmail.com"); // Now Create The Contact dirAccess.CreatePrivateList(oesctx, ldapobj);/** Looking up Private List **/ ldapobj = dirAccess.LookupPrivateList(oesctx,"myfriends");/*** Modifying a private list **/ //Modifying the given name of the contact Vector modify = new Vector(); modify.add ("myfriend_name"); ldapobj.modifyAttributeValue("givenname", modify, ESDSConstants.DS_MODIFY_ADD);dirAccess.ModifyContactInfo(oesctx, "myfriends_new",ldapobj); /*** Delete A Private List ***/ dirAccess.DeletePrivateList(oesctx,"friends ");/** Get All Private Lists **/ String[] lists= dirAccess.GetAllPrivateLists((oesctx); /** Get All Lists For a Given Filter **/ lists = dirAccess.SearchPrivateLists(oesctx,"name=t*"); /** Private list resolution **/ Vector resolved = dirAccess.ResolvePrivateList(oesctx, "friends" ,
"orclmailemail"); // This call resolves the given entry to the attribute "orclmailemail". It
resolved the other private dl's and contacts also to this type.

Rule Management API

The rule management API is a set of Java classes that can be used to create, access and manage server side rules. Rules are represented as Java objects and can be saved persistently in the LDAP directory as an attribute of a user.

What Are Server Side Rules?

A mail rule is a potential action that, when a certain event happens and a certain condition is satisfied, is taken upon an e-mail message on behalf of the owner of the rule. Rules can be created and stored persistently on the mail server.

The following is an example of a rule, expressed in English:

If an e-mail message arrives in my inbox and its subject contains the phrase "Get paid to surf," then delete the message.

In this example:

The event is the arrival of an e-mail message in the inbox

The condition is the presence of the phrase in the subject

The action is the deletion of the message

Each event represents a change of state on a particular message during its lifecycle in the mail server. In the above example, the event changes the state of the message from To be delivered to Delivered.

Conditions are similar to Boolean expressions, in which relational and logical operations test message attributes. In the example, the subject is the mail attribute to be tested, and the conditional expression is a relational operation that tests whether the attribute contains "Get paid to surf."

Optionally, multiple conditions can be combined using logical operators such as And and Or to form compound conditions. Additionally, a condition can be an external function call that returns a Boolean value.

Actions are operations that can act upon a message, such as the deletion of the message. In addition, an action can be any external procedure that is callable in PL/SQL from within the mail server.

Rule Components

Rules are owned by either individual users or a group of users collectively. The top-level entity owning the rules can therefore be either a mail user, a domain, or an entire e-mail system, which can contain more than one domain. The top-level entities are referred to as accounts.

For every account, one can have rules defined under a set of events, such as when new mail is delivered or when the message is read. Each event is associated with a rule list, and an account can have several rule lists, with at most one per event. For any event, a rule list can contain a list of rules that are executed sequentially when the event occurs.

A rule is defined by a condition and a list of actions. A rule with no condition is said to be unconditional, therefore the actions are always carried out.

Conditions can be simple and complex. For example, a condition that compares an attribute with a literal value using the relational operator "contains" is a simple condition. A complex condition can combine several sub-conditions. A condition can be also be a user-defined procedure, referred to as an external condition. There is also a special kind of condition, called an InSection condition, which performs a content-based search on a message.

When a rule's conditions are met, actions are taken. Actions are defined by the rule's commands, such as "move message to a folder" or "forward message to a recipient," and associated parameters, such as the name of the folder to which the message is moved or the address of the recipient to whom the message is forwarded. Once all the rules for a user are constructed in Java objects, the RuleParser object can be used to save it.

Authentication

Before a caller can access a user's rules, it must be authorized. The caller must authenticate with the LDAP directory using the oracle.mail.OESContext class. Once authenticated, the instance of the oracle.mail.OESContext class representing a trusted session must be passed into the RuleParser rule management class using the setAuthContext() method.

Example:

RuleParser parser = new RuleParser();
parser.setAuthContext(oesctx);

Validation

Before a rule is created on the server, the content of the rule is validated, preventing illegal rules from being executed at runtime. You can disable validation using the RuleParser.setValidation() method, which is useful if you want to temporarily save an incomplete rule. A non-validated rule can be saved persistently, but cannot be run during runtime.

Validation is disabled as follows:

parser.setValidation(false);

Rule Visibility, Activeness, and Group Affiliation

Visibility

A rule can be visible or invisible. An invisible rule functions as a normal rule, except that it is not shown to the user. The actual implementation of hiding a rule is left to the caller. The API is able to retrieve both visible and invisible rules.

Visibility is set using the setVisible() RuleType class method.

Activeness

A rule can be active or inactive. An inactive rule exists on the server but is not executed at runtime.

Activeness is set using the setActive() RuleType class method.

Group Affiliation

A rule can belong to a group. All rules belonging to the same group can be retrieved, activated, and disabled together in one call.

External Condition

Given the current folder ID, the current message's UID, and the current message ID, the function should return a number that indicates whether the condition is met. If the return value is 0, the server regards it as a positive condition match, and if the return value is non-zero, it is regarded as a failed condition match. If a rule uses an external condition, the condition function must be manually loaded to the database server where the user resides before the condition can take effect.

To set a condition to be an external condition, use the ConditionType class method addProcCall().

The procedure also takes the user ID, current folder name in its full path, the current message UID and ID, and two user-defined parameters set at rule creation time. After the procedure is completed, it should put a execution result value in the status parameter. A zero value in status indicates a normal execution, and a positive status indicates an abnormal execution.

To set an external action in rules, use the Action Type class addCommand() method, then call addParameter() three times, with the first added parameter being the procedure name, and the second and third parameters being the user-defined parameters p_param1 and p_param2 above.

External Action Example:

Message Templates

Some rules require an action to generate a new message as a reply or a notification. The reply or notification can be stored in the rule content as templates containing substitutable parameters denoted by a parameter name enclosed by two percent (%) signs.

For example, an auto-reply template can be "Your e-mail regarding %rfc822subject% sent on %rfc822date% has been received." When the rule engine generates the reply message, the variables %rfc822subject% and %rfc822date% are replaced by the real subject and date sent information obtained from the incoming message. The set of supported substitutable parameters is the same as the set of supported message attributes.

See Also:

The Javadoc for Unified Messaging for information on the AttributeType class on ***OTN.

Message template text is used as parameter values for rule actions such as Notify, Reply, Replyall, and Forward.

Auto-Reply Effective Duration

To prevent auto-reply messages from flooding user inboxes, there is a concept of effective duration for a specific reply action. The duration is specified as a number of days. If an auto-reply is sent to a particular address using a particular message template, the same reply is not sent to the same user again for the period of the effective duration, starting from the time when the first reply is sent. The value is required in rule actions Reply and Replyall.

XML Representation

Rule data can be serialized, or converted into plain text format using XML. It can then be easily transported between applications or stored off line. In fact, the rule API internally uses XML as the format to store in the LDAP directory. To flatten rule Java objects into XML text, use the print() method from the Account class.