# com.bea.p13n.mail
MailService Interface

public interface MailService
extends `EJBObject`

Remote interface to the MailService stateless session bean. This bean provides basic mail-sending capabilities for sending text email messages.

The smtp server can be specified in the bean's deployment descriptor, or in the application's `MailServiceMBean```.

All Superinterfaces
  `EJBObject`, `Remote`

## Method Summary

`public void` | `addToBatch`(`MailMessage` message, `String` batch) Add a MailMessage to a batch so that it can be sent later.
`public void` | `deleteBatch`(`String` batch) Delete a batch and all of its messages
`public `ArrayList`` | `getBatchNames`() Return all batch names in the system
`public int` | `getBatchSize`(`String` batch) Return the size of a batch.
`public `ServletResults`` | `getJSPResults`(`String` url, `Map` params) Similar to getTextFromJSP; but will retrieve contents of the jsp page as a byte array to cut down on string encoding hassles.
`public `ArrayList`` | `getMessagesInBatch`(`String` batchName, boolean getText) Retrieve all messages in a batch.
`public `String`` | `getTextFromJSP`(`String` url, `Map` params) Generate text from a JSP page for use in an email message.
`public boolean` | `isValidAddress`(`String` address) Is the specified email address valid for this mail service.
`public void` | `sendBatch`(`String` batch, boolean delete) Send all the messages in a batch, optionally deleting the batch when finished.
`public void` | `sendMail`(`String` to, `String` from, `String` subject, `String` text) The simplest way to send a mail message; supply the basic information and the message will be sent immediately.
`public void` | `sendMail`(`MailMessage` message) Send an email message immediately.

Methods from interface `javax.ejb.`EJBObject``
`getEJBHome, getHandle, getPrimaryKey, isIdentical, remove`

## Method Detail

### addToBatch(MailMessage, String) Method

    public void addToBatch(MailMessage message,
                           String batch)
         throws RemoteException, IllegalArgumentException, MailServiceException

Add a MailMessage to a batch so that it can be sent later. If the specified batch does not exist, it will be created.

#### Parameters

message
  A MailMessage to batch

batch
  the name of the batch to add it to

#### Exceptions

``RemoteException``
``IllegalArgumentException``
  if the MailMessage is not valid
``MailServiceException``

### deleteBatch(String) Method

    public void deleteBatch(String batch)
         throws RemoteException, MailServiceException

Delete a batch and all of its messages

#### Parameters

batch
  the name of the batch to delete

#### Exceptions

``RemoteException``
``MailServiceException``

### getBatchNames() Method

    public ArrayList getBatchNames()
         throws RemoteException, MailServiceException

Return all batch names in the system

#### Returns

an ArrayList of batch names

#### Exceptions

``RemoteException``
``MailServiceException``

### getBatchSize(String) Method

    public int getBatchSize(String batch)
         throws RemoteException, MailServiceException

Return the size of a batch.

#### Parameters

batch
  the name of the batch to examine

#### Returns

the number of messages in the batch

#### Exceptions

``RemoteException``
``MailServiceException``

### getJSPResults(String, Map) Method

    public ServletResults getJSPResults(String url,
                                        Map params)
         throws RemoteException, IOException

Similar to getTextFromJSP; but will retrieve contents of the jsp page as a byte array to cut down on string encoding hassles. The ServletResults object also includes the content-type directive of the JSP page, if any is given.

#### Exceptions

``RemoteException``
``IOException``

### getMessagesInBatch(String, boolean) Method

    public ArrayList getMessagesInBatch(String batchName,
                                        boolean getText)
         throws RemoteException, MailServiceException

Retrieve all messages in a batch. If the getText flag is false, all message information will be retrieved except for the message text. This option is provided to avoid memory/bandwidth problems for batches that may contain large mail messages.

#### Parameters

batchName
  the name of the batch to examine

getText
  flag to retrieve message text

#### Returns

an ArrayList of MailMessage objects

#### Exceptions

``RemoteException``
``MailServiceException``

### getTextFromJSP(String, Map) Method

    public String getTextFromJSP(String url,
                                 Map params)
         throws RemoteException, IOException

Generate text from a JSP page for use in an email message. Any parameters will be passed as HTTP POST parameters. If the URL is relative, it will be assumed it is an HTTP request to the local server, at the local server's port.

#### Parameters

url
  the URL of the jsp page.

params
  a map of parameters to pass to the JSP

#### Returns

the generated text

#### Exceptions

``RemoteException``
``IOException``

### isValidAddress(String) Method

    public boolean isValidAddress(String address)
         throws RemoteException

Is the specified email address valid for this mail service.

#### Parameters

address
  the email address.

#### Exceptions

``RemoteException``

### sendBatch(String, boolean) Method

    public void sendBatch(String batch,
                          boolean delete)
         throws RemoteException, MailServiceException

Send all the messages in a batch, optionally deleting the batch when finished.

#### Parameters

batch
  the name of the batch to send

delete
  if true, will delete the batch after sending it

#### Exceptions

``RemoteException``
``MailServiceException``

### sendMail(String, String, String, String) Method

    public void sendMail(String to,
                         String from,
                         String subject,
                         String text)
         throws RemoteException, IllegalArgumentException, MailServiceException

The simplest way to send a mail message; supply the basic information and the message will be sent immediately.

#### Parameters

to
  The address to mail to

from
  The "from" address

subject
  The message's subject. Can be null.

text
  The message's text. Can be null.

#### Exceptions

``RemoteException``
``IllegalArgumentException``
  If the "to" address is null or invalid
``MailServiceException``

### sendMail(MailMessage) Method

    public void sendMail(MailMessage message)
         throws RemoteException, IllegalArgumentException, MailServiceException

Send an email message immediately. A valid MailMessage is required; i.e., there must be at least one recipient.

#### Parameters

message
  A MailMessage to send.

#### Exceptions

``RemoteException``
``IllegalArgumentException``
  if the MailMessage is not valid
``MailServiceException``