oracle.context.isearch.query
Class MailTool

java.lang.Object
  |
  +--oracle.context.isearch.query.MailTool

public class MailTool

extends java.lang.Object

This class implements the Ultra Search Java Email API.

It defines all constants and methods for accessing email source data.

An email source represents all emails sent to a specific email address or it's aliases. The most popular use of an email source is to represent all emails sent to a mailing list.

The methods implemented by this API can be classified as follows:

• Methods that retrieve email data.
• Methods that return HTML or are related to the presentation of HTML code.
• Ultra Search database session methods.
• Utility methods.

Methods that retrieve email data

These methods return email data such as the list of existing email sources in the Ultra Search instance, information about a particular email source, the number of messages in an email source and the header fields of a message.

The methods that fall under this class are as follows:

• getMessageCount
• getEmailSource
• getEmailSources
• getEmailHeader
• getEmailHeaders
• getMimeMessage

Methods that return HTML code or are related to the presentation of HTML code

These methods perform the following tasks:

• Return HTML code that can be embedded by the client web application.
• Alter the state of this object to directly affect the HTML code generated by this object.

The methods that fall under this class are as follows:

• setMailPagePath and getMailPagePath
• The three createLink methods

Ultra Search database session methods

These methods are related to the jdbc database session. They include setting the username, password and session language.

The methods that fall under this class are as follows:

• setResourceFileName and getResourceFileName
• setUser and getUser
• setPassword and getPassword
• setSessionLang and getSessionLang

Utility methods

These methods exist as convenience method for the client web application developer. They encapsulate commonly performed tasks.

The methods that fall under this class are as follows:

• htmlEncode

Since:

1.0.2

Field Summary

static int	DATE A constant that is used to retrieve the 'Date' header field information from the string array returned by the getEmailHeader method.
static int	FROM A constant that is used to retrieve the 'From' header field information from the string array returned by the getEmailHeader method.
static int	SEQ_NUM A constant that is used to retrieve the email sequence number from the string array returned by the getEmailHeader method.
static int	SUBJECT A constant that is used to retrieve the 'Subject' header field information from the string array returned by the getEmailHeader method.

Constructor Summary

MailTool()
Default constructor

Method Summary

java.lang.String	createLink(int emailSourceId) A utility method that creates a link that when clicked on, will render a page showing emails belonging to an email source.
java.lang.String	createLink(int emailSourceId, int messageId) A utility method that creates a link that when clicked on, will render a page showing the contents of an email.
java.lang.String	createLink(int emailSourceId, int messageId, int attachId) A utility method that creates a link that when clicked on, will render a page showing the contents of an email attachment of a specific email.
java.lang.String[]	getEmailHeader(int emailSourceId, int messageId) Gets the header information of an email.
java.util.Vector	getEmailHeaders(int emailSourceId, int startIndex, int endIndex) Gets the header information of an email.
Item	getEmailSource(int emailSourceId) Get one email source Returns an Item object whose ID is the email source ID, name is the email address of the email source and description is the description of the email source.
Item[]	getEmailSources() Gets a list of email sources that are defined in the Oracle Ultra Search instance.
java.lang.String	getMailPagePath() Gets the URL path of the web application (JSP or Servlet) that will render the contents of an email.
int	getMessageCount(int emailSourceId) Gets the number of messages in an email source.
javax.mail.internet.MimeMessage	getMimeMessage(int emailSourceId, int messageId) Gets an email message as a javax.mail.internet.MimeMessage object.
java.lang.String	getResourceFileName() Gets the name of the .properties file that contains the database resource settings.
java.lang.String	getSchema()
java.lang.String	getSessionLang() Gets the session language for the database SQL session.
java.lang.String	getUser() Gets the database username of the Ultra Search instance that should be accessed.
java.lang.String	htmlEncode(java.lang.String str) Convenience method for converting certain characters into HTML encoding.
void	setMailPagePath(java.lang.String s) Sets the URL path of the web application (JSP or Servlet) that will render the contents of an email.
void	setPassword(java.lang.String s) Sets the database username password of the Ultra Search instance that should be accessed.
void	setResourceFileName(java.lang.String s) Sets the name of the .properties file that contains the database resource settings.
void	setSessionLang(java.lang.String str) Sets the session language for database SQL session.
void	setUser(java.lang.String s) Sets the database username of the Ultra Search instance that should be accessed.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FROM

public static final int FROM

A constant that is used to retrieve the 'From' header field information from the string array returned by the getEmailHeader method.

SUBJECT

public static final int SUBJECT

A constant that is used to retrieve the 'Subject' header field information from the string array returned by the getEmailHeader method.

DATE

public static final int DATE

A constant that is used to retrieve the 'Date' header field information from the string array returned by the getEmailHeader method.

SEQ_NUM

public static final int SEQ_NUM

A constant that is used to retrieve the email sequence number from the string array returned by the getEmailHeader method.

Constructor Detail

MailTool

public MailTool()

Default constructor

Method Detail

setMailPagePath

public void setMailPagePath(java.lang.String s)

Sets the URL path of the web application (JSP or Servlet) that will render the contents of an email.

Parameters:

s - a portion of a URL string representing the mail rendering application.

getMailPagePath

public java.lang.String getMailPagePath()

Gets the URL path of the web application (JSP or Servlet) that will render the contents of an email.

Returns:

a portion of a URL string representing the mail rendering application.

setResourceFileName

public void setResourceFileName(java.lang.String s)
                         throws java.sql.SQLException

Sets the name of the .properties file that contains the database resource settings. The file that is shipped with Oracle Ultra Search is named database.properties.

Parameters:

s - the database resource filename

Throws:

java.sql.SQLException - when a database error occurs.

getResourceFileName

public java.lang.String getResourceFileName()

Gets the name of the .properties file that contains the database resource settings.

Returns:

the database resource filename

setUser

public void setUser(java.lang.String s)

Sets the database username of the Ultra Search instance that should be accessed.

Parameters:

s - This must be an Oracle database username.

getUser

public java.lang.String getUser()

Gets the database username of the Ultra Search instance that should be accessed.

Returns:

The Oracle database username.

setPassword

public void setPassword(java.lang.String s)

Sets the database username password of the Ultra Search instance that should be accessed.

Parameters:

s - This must be the password of an Oracle database user.

setSessionLang

public void setSessionLang(java.lang.String str)

Sets the session language for database SQL session.

The session language determines how Oracle Text choose a lexer to interpret the query string.

The session language is a string that the Oracle Server understands. This list can be found in the Oracle National Language Support Guide. The languages returned by the getLanguages method are not exactly the same as those needed by the Oracle Server. Do not use the languages returned by the getLanguages method.

Parameters:

str - Theh Oracle Server compatible language string.

getSessionLang

public java.lang.String getSessionLang()

Gets the session language for the database SQL session.

Returns:

the session language that the Oracle Server is using.

createLink

public java.lang.String createLink(int emailSourceId)

A utility method that creates a link that when clicked on, will render a page showing emails belonging to an email source.

This method uses the URL defined by the setMailPagePath method. Therefore, setMailPagePath must be correctly called first.

Parameters:

emailSourceId - The ID of the email source.

Returns:

A url that points to the page that displays emails belonging to the email source.

createLink

public java.lang.String createLink(int emailSourceId,
                                   int messageId)

A utility method that creates a link that when clicked on, will render a page showing the contents of an email.

This method uses the URL defined by the setMailPagePath method. Therefore, setMailPagePath must be correctly called first.

Parameters:

emailSourceId - The ID of the email source.

messageId - The ID of the message within the email source.

Returns:

A url that points to the page that displays the email.

createLink

public java.lang.String createLink(int emailSourceId,
                                   int messageId,
                                   int attachId)

A utility method that creates a link that when clicked on, will render a page showing the contents of an email attachment of a specific email.

This method uses the URL defined by the setMailPagePath method. Therefore, setMailPagePath must be correctly called first.

Parameters:

emailSourceId - The ID of the email source.

messageId - The ID of the message within the email source.

attachId - The ID of the attachment to the specified email.

Returns:

A url that points to the page that displays the email.

htmlEncode

public java.lang.String htmlEncode(java.lang.String str)

Convenience method for converting certain characters into HTML encoding.

This method analyzes the input string and performs the following conversions:

• The '&' character is converted to '&'
• The '<' character is converted to '&lt;'
• The '>' character is converted to '&gt;'
• The '"' character is converted to '&quot;'

Parameters:

str - The input string to convert.

Returns:

The converted version of the input string.

getMessageCount

public int getMessageCount(int emailSourceId)
                    throws java.sql.SQLException

Gets the number of messages in an email source.

Parameters:

emailSourceId - The number id of the email source.

Returns:

The number of messages in the email source.

Throws:

java.sql.SQLException - when a database error occurs.

getEmailSource

public Item getEmailSource(int emailSourceId)
                    throws java.sql.SQLException

Get one email source

Returns an Item object whose ID is the email source ID, name is the email address of the email source and description is the description of the email source.

For example:
ID is 5
name is "all_users@company.com"
description is "email source for All Users"

Parameters:

emailSourceId -

Returns:

null if no email source found.

Throws:

java.sql.SQLException - when a database error occurs.

getSchema

public java.lang.String getSchema()
                           throws java.sql.SQLException

getEmailSources

public Item[] getEmailSources()
                       throws java.sql.SQLException

Gets a list of email sources that are defined in the Oracle Ultra Search instance.

Returns:

An array of Item objects where each Item object encapsulates information about one email source. The item id is the email source id. The item name is the email address of the email source. The item description is the description of the email source.

Throws:

java.sql.SQLException - when a database error occurs.

getEmailHeader

public java.lang.String[] getEmailHeader(int emailSourceId,
                                         int messageId)
                                  throws java.sql.SQLException

Gets the header information of an email.

Returns an array of Strings where the
1st element is the FROM header field of the email.
2nd element is the SUBJECT header field of the email.
3rd element is the DATE header field of the email.

The client web application may use the following constants to access the string array values instead of using index numbers:

• MailTool.FROM
• MailTool.SUBJECT
• MailTool.DATE

Parameters:

emailSourceId - The ID of the email source.

messageId - The ID of the message within the email source.

Returns:

A string array containing the header information.

Throws:

java.sql.SQLException - when a database error occurs.

getEmailHeaders

public java.util.Vector getEmailHeaders(int emailSourceId,
                                        int startIndex,
                                        int endIndex)
                                 throws java.sql.SQLException

Gets the header information of an email.

Returns a Vector of arraies of Strings where the
1st element is the FROM header field of the email.
2nd element is the SUBJECT header field of the email.
3rd element is the DATE header field of the email.
4th element is the SEQ_NUM of the email.

The client web application may use the following constants to access the string array values instead of using index numbers:

• MailTool.FROM
• MailTool.SUBJECT
• MailTool.DATE
• MailTool.SEQ_NUM

Parameters:

emailSourceId - The ID of the email source.

startIndex - The index of the first email header returned.

endIndex - The index of the last email header returned.

Returns:

A Vector of string arraies containing the header information.

Throws:

java.sql.SQLException - when a database error occurs.

getMimeMessage

public javax.mail.internet.MimeMessage getMimeMessage(int emailSourceId,
                                                      int messageId)
                                               throws java.sql.SQLException,
                                                      java.io.IOException,
                                                      javax.mail.MessagingException

Gets an email message as a javax.mail.internet.MimeMessage object.

The email message comes from the email archive directory which is directly accessible by the database server machine (which may not be the same machine as the application server).

Parameters:

emailSourceId - The ID of the email source.

messageId - The ID of the message within the email source.

Returns:

A MimeMessage object representing the email.

Throws:

java.sql.SQLException - when a database error occurs.

java.io.IOException - when an error occurs while opening the cached email file.

MessagingException - when an error occurs in the Java Mail layer.