Skip Headers

Oracle® Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference 10g Release 2 (10.1.2) B14016-02 |
| Library | Product | Contents | Index

Previous | Next |

# 8 File Access and Mail Beans and Tags

This chapter covers OC4J tags and JavaBeans for file access (uploading and downloading) and for e-mail. The e-mail tag and JavaBean make use of the file access functionality for attachments. The chapter is organized as follows:

- File-Access JavaBeans and Tags

- Mail JavaBean and Tag

## File-Access JavaBeans and Tags

OC4J provides a standards-compliant tag library and JavaBeans that add convenient file upload and file download functionality for JSP pages and servlets. Files can be uploaded to or downloaded from a file system or database.

The following sections document the file-access tags and beans:

- Overview of OC4J File-Access Functionality

- File Upload and Download Tag Descriptions

- File Upload and Download JavaBean and Class Descriptions

### Overview of OC4J File-Access Functionality

Developers have the option of using either custom tags or JavaBeans to program applications that allow users to upload or download files. In either case, the application is presumably programmed so that users specify through the browser where files come from on the client system for uploading or where they go to on the client system for downloading. For JSP pages for uploading, OC4J supplies a convenience tag, `httpUploadForm`, to create a form to use in specifying where the files come from.

For processing an upload, including specifying the destination file system or database location, use the `HttpUploadBean` JavaBean or the `httpUpload` tag. For processing a download, including specifying the source file system or database location, use `HttpDownloadBean` or the `httpDownload` tag. The beans extend `HttpFileAccessBean`, which is not intended for public use. All of the beans are in the `oracle.jsp.webutil.fileaccess` package.

#### Overview of File Uploading

For user specification in a JSP page of where uploaded files will come from, you can use the `httpUploadForm` tag to create a form. This tag lets users select the files for uploading and creates the necessary multipart HTTP request. You also have the option of using a standard HTML form to create the request.

Use the `HttpUploadBean` JavaBean or the `httpUpload` tag to receive and process the multipart form-encoded data stream and write the files to the appropriate location, either in the file system or a database. There is functionality to let you decide whether previous data will be overwritten if the target file or database row already exists.

Note: The maximum file size for any upload is 2 GB.

##### File System Destination

If the destination is in a file system, you must provide a properties file that designates a base directory. The properties file must be named `fileaccess.properties`, must be located in the `/WEB-INF` directory of your application, and must have a `fileaccess.basedir` entry that indicates an absolute directory path. Here is an example:

    fileaccess.basedir=/tmp

Note: On a Windows system, you must still use a forward-slash, not a back-slash, for the directory path:
    fileaccess.basedir=c:/tmp
Furthermore, the specified drive (`C:` in this case) must be the same drive on which OC4J is installed.

There should be subdirectories as appropriate under the base directory, such as a subdirectory for each authorized user. Destination subdirectories under the base directory must be specified through an attribute of the upload bean or tag. All directories and subdirectories must already exist and be writable; they cannot be created or made writable through OC4J functionality.

##### Database Destination

If the destination is in a database, you can optionally use a default table, `fileaccess`, that you create through the supplied `fileaccess.sql` script, or you can use any other previously existing table containing the required column types. In either case, you must provide a connection to the database, as an instance of either `oracle.jsp.dbutil.ConnBean` or the standard `java.sql.Connection`. You can provide a `ConnBean` instance explicitly, or in a JSP page you also have the option of providing it implicitly as a result of nesting the `httpUpload` tag inside a `dbOpen` tag. (For information about the `ConnBean` JavaBean and `dbOpen` tag, see Chapter 4, "Data-Access JavaBeans and Tags".)

Note: The `java.sql.Connection` type is currently supported for the file-access beans only, not the tags.

You are also required to specify a destination through an attribute of the upload bean or tag. The destination is simply a Java string value that will be placed in the prefix column of the database table. The prefix is equivalent to a file system path.

File data is written to a database as either a BLOB or a CLOB. You can specify which through an upload bean or tag attribute.

If you do not use the default `fileaccess` table, you must use attributes of the upload bean or tag to specify the database table name and the names of the columns that will contain the file data, the file prefix, and the file name. Any other table you use must adhere to the pattern of `fileaccess`, as follows:

- It must have a concatenated unique key consisting of the column that holds the file name and the column that holds the prefix.

- It must have a BLOB or CLOB column for the file data.

- Any column other than the file data column must allow null data.

Note: When you use a `ConnBean` instance, the connection will be closed automatically at the end of the scope designated in the `jsp:useBean` tag that invokes it. There is no such functionality for a `Connection` instance.

##### Security Con siderations for Uploading

For uploading to a database, the database table does not have a column to indicate a particular authorized user for any given file. Therefore, without precaution, each user can see files that were uploaded by other users, without having to know the file prefixes. To prevent this, you can prepend an appropriate user name to each prefix.

#### Overview of File Downloading

Use the `HttpDownloadBean` JavaBean or the `httpDownload` tag as follows:

- To allow users to specify the file system source directory or the database prefix to match for file retrieval

  Note the following:

  - Matching the prefix for downloads from a database is case-sensitive.

  - Matching the source directory for downloads from a file system is case-sensitive in a case-sensitive operating system, such as UNIX.

  - There is currently no support for specifying file names, either partial or complete.

- To obtain and display a list of the files that are available for download

  Once presented with a list of available files, the user can download them one at a time from the list.

There is also functionality to specify whether you want recu rsive downloading, where files in subdirectories or with additional database prefix information will also be available for download. For database downloading, a prefix is equivalent to a file system path and can be used to group files into a hierarchy. As an example of recursive downloading from a database, assume you have specified `/user` as the prefix. Recursive downloading would find matches for files with any prefixes starting with "`/user`", such as "`/user/bill`" and "`/user/mary`", and also such as "`/user1`", "`/user2`", "`/user1/tom`", and "`/user2/susan`".

For downloading files from a file system, utilize the mechanism described in "Overview of File Uploading". Use the `fileaccess.properties` file to specify a base directory and use attributes in the download bean or tag to specify the rest of the file path.

For downloading files from a database, as with uploading files to a database, you must provide an instance of `oracle.jsp.dbutil.ConnBean` or `java.sql.Connection`. In addition, if you are not using the default `fileaccess` table (that you can create using the supplied `fileaccess.sql` script), you must provide all the necessary information about the database table and columns. Specify this information through attributes of the download bean or tag.

The actual downloading of the files is accomplished by `DownloadServlet`, supplied with OC4J. In using the download tag, specify the path of this servlet through a tag attribute. For a file system source, hyperlinks are automatically created to the servlet so that the user can select a link for each file in order to download the file. For a database source, the servlet will fetch the selected CLOB or BLOB data that forms the file contents. (See "The Download Servlet".)

##### Sec urity Considerations for Downloading

For downloading, consider limiting the users' ability to see what is in the source (server-side) file system or database. Without precaution, the following scenarios are possible:

- For file system downloading, a source value of "`*`" (perhaps specified through user input) would mean that all directories under the base directory would be available for downloading, with the names of all the files presumably being displayed for the user to choose from.

- For recursive downloading from a database, all files having a prefix beginning with the `source` string (perhaps specified through user input) would be available for downloading, with the names of all these files presumably being displayed. A source of "`*`" matches all prefixes.

If this is of concern, you can consider protective measures such as the following:

- Not accepting `source` values of "`*`" when downloading from file systems

- Not allowing recursive downloading from databases

- Automatically prepending the `source` value with a partial directory path or prefix string, such as a user name, to restrict the areas to which users have access

### File Upload and Download JavaBean and Class Descriptions

This section describes attributes and methods of the file upload and download JavaBeans provided with OC4J: `HttpUploadBean` and `HttpDownloadBean`, respectively.

There is also brief discussion of `DownloadServlet`, provided with OC4J to perform the actual file downloading, and the class `FileAccessException` that is used by the file-access JavaBeans for exceptions relating to file uploads and downloads.

To comply with the JavaBean specification, the file upload and download JavaBeans provide no-argument constructors.

Note: To use the file upload and download JavaBeans, verify that the file `ojsputil.jar` is installed and in your classpath. This file is provided with OC4J.

#### The Ht tpUploadBean

The `oracle.jsp.webutil.fileaccess.HttpUploadBean` JavaBean provides numerous setter methods for specifying information used for the uploading. It also includes most corresponding getter methods. Once you have set all the required and appropriate attributes, use the `upload()` method to perform the upload. There is also a method to display the names of the files that were uploaded, typically so you can provide an informative message to the browser.

`HttpUploadBean`, as with `HttpDownloadBean`, extends `HttpFileAccessBean`, which itself is not intended for public use.

See "Overview of File Uploading" for related information.

##### Summary of Required Attributes

The following list summarizes required attributes for `HttpUploadBean`:

- Always required: `destination`

- Also required for uploads to a database: `destinationType`, `connection`

- Also required for uploads to a database table other than the default `fileaccess` table: `table`, `prefixColumn`, `fileNameColumn`, `dataColumn`

- Also required for uploads to a database table using a CLOB column for file data: `fileType`

In addition, for an upload to a file system, you must call the `setBaseDir()` method to provide a servlet context and HTTP request object so that the bean can find the `fileaccess.properties` file that specifies the base directory.

##### Methods

Here are descriptions of the public methods of `HttpUploadBean`.

Note: Many of the attributes and setter methods for `HttpUploadBean` are the same as for `HttpDownloadBean`.

- `void upload(javax.servlet.http.HttpServletRequest req) throws FileAccessException`

  Once all required and appropriate bean attributes have been set, use this method for the upload. The `req` parameter is the HTTP request instance containing the multipart form-encoded files. For a JSP page, use the implicit `request` object.

- `void setBaseDir(javax.servlet.ServletContext sc, javax.servlet.http.HttpServletRequest req) throws FileAccessException`

  For an upload to a file system, use this method to determine what to use as a base directory. It gets this information from the `fileaccess.properties` file in your application `/WEB-INF` directory, which it finds through the servlet context input parameter. The `baseDir` setting, together with the `destination` setting, specifies the absolute path to the upload directory.

  The `req` parameter is the servlet request instance to use in requesting the base directory information. For JSP pages, use the implicit `request` object.

  This method is not relevant for database uploads.

- `void setDestination(String destination)`

  This method is always required.

  For an upload to a file system, `destination` and the base directory together specify the absolute path to the upload directory.

  For an upload to a database, `destination` is used as the file prefix. (There is no "base directory".) The prefix is equivalent to a file system path and can be used to group files into a hierarchy. It is permissible to include separator characters such as "`.`" and "`/`" in the destination string.

  Note: Typically, the `destination` value will be based at least partially on user input.

- `void setDestinationType(String destinationType) throws FileAccessException`

- `void setDestinationType(int destinationType) throws FileAccessException`

  Use the overloaded `setDestinationType()` method to specify whether the upload is to a file system or a database.

  To upload to a database, set `destinationType` to one of the following: the string "`database`", the defined `String` constant `FileAccessUtil.DATABASE`, the `int` value 1, or the defined `int` constant `FileAccessUtil.LOCATION_TYPE_DATABASE`.

  Uploading to a file system is the default, but if you want to specify this explicitly, set `destinationType` to one of the following: the string "`filesystem`", the defined `String` constant `FileAccessUtil.FILESYSTEM`, the `int` value 0, or the defined `int` constant `FileAccessUtil.LOCATION_TYPE_FILESYSTEM`.

  `FileAccessUtil` is in the `oracle.jsp.webutil.fileaccess` package.

- `String getDestinationType()`

  Retrieve the destination information. Note there is a getter method for the string version only.

- `void setOverwrite(String overwrite) throws FileAccessException`

- `void setOverwrite(boolean overwrite)`

  Use the overloaded `setOverwrite()` method to overwrite existing files or update rows with the same file name and prefix. This is relevant for both file system and database uploads.

  Overwriting is enabled by default, but you can enable it explicitly with an `overwrite` setting of the string "`true`" or the boolean value `true`. Disable overwriting with a setting of the string "`false`" or the boolean value `false`. String settings are case-insensitive. No settings are accepted other than those listed here.

- `void setFileType(String fileType) throws FileAccessException`

- `void setFileType(int fileType) throws FileAccessException`

  For an upload to a database, use the overloaded `setFileType()` method to specify whether the data is to be stored in a BLOB for binary data (the default) or a CLOB for character data. For a CLOB, set `fileType` to one of the following: the string "`character`", the defined `String` constant `FileAccessUtil.CHARACTER_FILE`, or the `int` value 1. To explicitly specify a BLOB, set `fileType` to one of the following: the string "`binary`", the defined `String` constant `FileAccessUtil.BINARY_FILE`, or the int value 0. String settings are case-insensitive. No settings are accepted other than those listed here.

  `FileAccessUtil` is in the `oracle.jsp.webutil.fileaccess` package.

- `String getFileType()`

  Retrieve the file type information. Note there is a getter method for the string version only.

- `void setTable(String tableName)`

  For an upload to a database table other than the default `fileaccess` table, use this method to specify the table name.

- `String getTable()`

  Retrieve the table name.

- `void setPrefixColumn(String prefixColumnName)`

  For an upload to a database table other than the default `fileaccess` table, use this method to specify the name of the column containing the file prefix. (In `fileaccess`, this column name is `fileprefix`.) The `destination` value will be written into this column.

- `String getPrefixColumn()`

  Retrieve the name of the column containing the file prefix.

- `void setFileNameColumn(String fileNameColumnName)`

  For an upload to a database table other than the default `fileaccess` table, use this method to specify the name of the column containing the file name. (In `fileaccess`, this column name is `filename`.) File names will include any file name extensions.

- `String getFileNameColumn()`

  Retrieve the name of the column containing the file name.

- `void setDataColumn(String dataColumnName)`

  For an upload to a database table other than the default `fileaccess` table, use this method to specify the name of the BLOB or CLOB column containing the file contents. (In `fileaccess`, this column name is `data`.)

- `String getDataColumn()`

  Retrieve the name of the column containing the file contents.

- `void setConnection(ConnBean conn)`

- `void setConnection(java.sql.Connection conn)`

  For an upload to a database table (default table or otherwise), use this overloaded method to provide a database connection. You can provide an instance of either `oracle.jsp.dbutil.ConnBean` or the standard `java.sql.Connection` type. For information about the `ConnBean` JavaBean, see "ConnBean for a Database Connection".

  If you use a `Connection` instance, you must explicitly open and close it. For a `ConnBean` instance, this is handled automatically.

- `java.util.Enumeration getFileNames()`

  This method returns an `Enumeration` instance containing the names of the files that were uploaded. (This functionality is not available through the `httpUpload` tag.)

##### Example:

This example uses a plain HTML form to specify a file to upload to a file system, then uses a JSP page that employs `HttpUploadBean` for the upload.

Here is the HTML form, which specifies `beanUploadExample.jsp` for its action and will generate the multipart upload stream.

Note: Remember to set the base directory appropriately for uploads to a file system. See "File System Destination".

    <html><body>
    <form action="beanUploadExample.jsp" ENCTYPE="multipart/form-data" method=POST>
    <br> File to upload: <INPUT TYPE="FILE" NAME="File" SIZE="50" MAXLENGTH="120" >
    <br><INPUT TYPE="SUBMIT" NAME="Submit" VALUE="Send"> </form>
    </body></html>

And here is the `beanUploadExample.jsp` page.

    <%@ page language="java"
             import="java.util.*, oracle.jsp.webutil.fileaccess.*" %>
    <html><body>
    <% String userdir = "fileaccess"; %>   // user's part of the upload directory
    <jsp:useBean id="upbean"
       class="oracle.jsp.webutil.fileaccess.HttpUploadBean" >
       <jsp:setProperty name="upbean" property="destination"
                         value="<%= userdir %>" />
    </jsp:useBean>
    <%   upbean.setBaseDir(application, request);
             upbean.upload(request);
             Enumeration fileNames = upbean.getFileNames();
             while (fileNames.hasMoreElements()) { %>
                  <br><%= (String)fileNames.nextElement() %>
      <% } %>
    <br>Done!
    </body></html>

#### The Ht tpDownloadBean

The `oracle.jsp.webutil.fileaccess.HttpDownloadBean` JavaBean provides numerous setter methods for specifying information used for downloading. It also includes most corresponding getter methods. Once you have set all the required and appropriate attributes, use the `listFiles()` method to list the files available for download. The actual downloading is accomplished through `DownloadServlet`, supplied with OC4J, one file at a time. See "The Download Servlet".

Note: You must construct the URL for `DownloadServlet` in your application code.

`HttpDownloadBean`, as with `HttpUploadBean`, extends `HttpFileAccessBean`, which itself is not intended for public use.

See "Overview of File Uploading" for related information.

##### Summary of Required Attributes

The following list summarizes required attributes for `HttpDownloadBean`:

- Always required: `source`

- Also required for uploads to a database: `sourceType`, `connection`

- Also required for downloads from a database table other than the default `fileaccess` table: `table`, `prefixColumn`, `fileNameColumn`, `dataColumn`

- Also required for downloads from a database table using a CLOB column for file data: `fileType`

In addition, for a download from a file system, you must call the `setBaseDir()` method to provide a servlet context and HTTP request object so that the bean can find the `fileaccess.properties` file that specifies the base directory.

##### Methods

Here are descriptions of the public methods of `HttpDownloadBean`.

Note: Many of the attributes and setter methods for `HttpDownloadBean` are the same as for `HttpUploadBean`.

- `void listFiles(javax.servlet.http.HttpServletRequest req) throws FileAccessException`

  Once all required and appropriate bean attributes have been set, use this method to list the files available for download. These are files in the source directory or matching the source database prefix. The `req` parameter is the HTTP response instance. For a JSP page, use the implicit `request` object.

  For use from the file list, you can create `HREF` links to `DownloadServlet`, passing it each file and file prefix, allowing users to select the link for each file they want to download.

  Note: The `listFiles()` method writes the file names to memory and to the JSP page or servlet. If you later want to access the file names again, use the `getFileNames()` method to read them from memory.

- `java.util.Enumeration getFileNames()`

  This method returns an `Enumeration` instance containing the names of the files that are available for download. It requires that the `listFiles()` method was already called. The `listFiles()` method writes the file names to memory and to the JSP page or servlet. The `getFileNames()` method reads them from memory.

- `void setBaseDir(javax.servlet.ServletContext sc, javax.servlet.http.HttpServletRequest req) throws FileAccessException`

  For a download from a file system, use this method to determine what to use as the base directory. It gets this information from the `fileaccess.properties` file in your application `/WEB-INF` directory, which it finds through the servlet context input parameter. The `baseDir` setting, together with the `source` setting, specifies the absolute path to the directory from which files will be downloaded.

  The `sc` parameter is the servlet context instance for the application. For JSP pages, use the implicit `application` object.

  The `req` parameter is for the HTTP request instance to use in requesting the base directory information. For JSP pages, use the implicit `request` object.

  A base directory is not relevant for downloads from a database.

- `void setSource(String source)`

  This is always required.

  For a download from a file system, `source` and the base directory together specify the absolute path to the directory from which files will be downloaded. If `source` is set to "`*`", then all directories under the base directory will be available for downloading.

  For a download from a database, `source` is used as the file prefix. (The base directory is not relevant.) The prefix is equivalent to a file system path and can be used to group files into a hierarchy. If recursive downloading is enabled (through the `setRecurse()` method), "`%`" will be appended onto the `source` value, and the `WHERE` clause for the query will contain an appropriate `LIKE` clause. Therefore, all files with prefixes that are partially matched by the `source` value will be available for download. If you want to match all rows in the database table, set `source` to "`*`".

  Note: Typically, the `source` value will be based at least partially on user input.

- `void setSourceType(String sourceType) throws FileAccessException`

- `void setSourceType(int sourceType) throws FileAccessException`

  Use the overloaded `setSourceType()` method to specify whether the download is from a file system or a database.

  To download from a database, set `sourceType` to one of the following: the string "`database`", the defined `String` constant `FileAccessUtil.DATABASE`, the `int` value 1, or the defined `int` constant `FileAccessUtil.LOCATION_TYPE_DATABASE`.

  Downloading from a file system is the default, but if you want to specify this explicitly, set `sourceType` to one of the following: the string "`filesystem`", the defined `String` constant `FileAccessUtil.FILESYSTEM`, the `int` value 0, or the defined `int` constant `FileAccessUtil.LOCATION_TYPE_FILESYSTEM`.

  `FileAccessUtil` is in the `oracle.jsp.webutil.fileaccess` package.

- `String getSourceType()`

  Retrieve the source type information. Note there is a getter method for the string version only.

- `void setRecurse(String recurse) throws FileAccessException`

- `void setRecurse(boolean recurse)`

  Use the overloaded `setRecurse()` method to enable or disable recursive downloading functionality, where files in file system subdirectories or with additional database prefix information will also be listed as available for downloading. As an example of this functionality from a database, assume `source` is set to "`/user`". Recursiveness would also find matches for files with prefixes such as "`/user/bill`" and "`/user/mary`", and also such as "`/user1`", "`/user2`", "`/user1/tom`", and "`/user2/susan`".

  Recursiveness is enabled by default, but you can enable it explicitly with a `recurse` setting of the string "`true`" or the boolean `true`. Disable the recursive functionality with a setting of the string "`false`" or the boolean `false`. String settings are case-insensitive. No settings are accepted other than those listed here.

- `void setFileType(String fileType) throws FileAccessException`

- `void setFileType(int fileType) throws FileAccessException`

  For a download from a database, use the overloaded `setFileType()` method to specify whether the data is stored in a BLOB for binary data (the default) or a CLOB for character data. For a CLOB, set `fileType` to one of the following: the string "`character`", the defined `String` constant `FileAccessUtil.CHARACTER_FILE`, or the `int` value 1. To explicitly specify a BLOB, set `fileType` to one of the following: the string "`binary`", the defined `String` constant `FileAccessUtil.BINARY_FILE`, or the `int` value 0. String settings are case-insensitive. No settings are accepted other than those listed here.

  `FileAccessUtil` is in the `oracle.jsp.webutil.fileaccess` package.

- `String getFileType()`

  Retrieve the file type information. Note there is a getter method for the string version only.

- `void setTable(String tableName)`

  For a download from a database table other than the default `fileaccess` table, use this method to specify the table name.

- `String getTable()`

  Retrieve the table name.

- `void setPrefixColumn(String prefixColumnName)`

  For a download from a database table other than the default `fileaccess` table, use this method to specify the name of the column containing the file prefix. (In `fileaccess`, this column name is `fileprefix`.)

- `String getPrefixColumn()`

  Retrieve the name of the column containing the file prefix.

- `void setFileNameColumn(String fileNameColumnName)`

  For a download from a database table other than the default `fileaccess` table, use this method to specify the name of the column containing the file name. (In `fileaccess`, this column name is `filename`.) The file name includes any file name extension.

- `String getFileNameColumn()`

  Retrieve the name of the column containing the file name.

- `void setDataColumn(String dataColumnName)`

  For a download from a database table other than the default `fileaccess` table, use this method to specify the name of the BLOB or CLOB column that holds the file contents. (In `fileaccess`, this column name is `data`.)

- `String getDataColumn()`

  Retrieve the name of the column containing the file contents.

- `void setConnection(ConnBean conn)`

- `void setConnection(java.sql.Connection conn)`

  For a download from a database table (default table or otherwise), use this method to provide a database connection. You can provide an instance of either `oracle.jsp.dbutil.ConnBean` or the standard `java.sql.Connection` type. For information about the `ConnBean` JavaBean, see "ConnBean for a Database Connection".

  If you use a `Connection` instance, you must explicitly open and close it. For a `ConnBean` instance, this is handled automatically.

##### Example

This example is a JSP page that uses `HttpDownloadBean` for a download from a file system. Note that the page must construct the URL for the download servlet.

    <%@ page language="java" import="java.util.*, oracle.jsp.webutil.fileaccess.*" %>
    <html><body>
    <% String servletPath = "/servlet/download/";  // path to the download servlet
       String userDir = "fileaccess/";   // user part of  download directory
    %>
    <jsp:useBean id="dbean"
       class="oracle.jsp.webutil.access.HttpDownloadBean" >
       <jsp:setProperty name="dbean" property="source" value='<%=userDir %>' />
    </jsp:useBean>
    <%    dbean.setBaseDir(application, request);
          dbean.listFiles(request); %>
    The following files were found:
    <%   Enumeration fileNames = dbean.getFileNames();
             while (fileNames.hasMoreElements()) {
                    String name = (String)fileNames.nextElement();  %>
                   <br><a href="<%= servletPath + name %>" > <%= name %></a>
    <%    } %>
    <br>Done!
    </body></html>

#### The Dow nload Servlet

To use download functionality, through either `HttpDownloadBean` or the `httpDownload` tag, you must have the class `oracle.jsp.webutil.fileaccess.DownloadServlet` available in your Web server. Its mapping in your Web server must be reflected in your servlet path settings, either through the `servletPath` attribute if you use the `httpDownload` tag, or in your application code if you use `HttpDownloadBean`.

#### FileAc cessException Class

The `oracle.jsp.webutil.fileaccess.FileAccessException` class is a convenience class supplied with OC4J for file-access exception-handling. It wraps the functionality of the standard `java.sql.SQLException` and `java.io.IOException` classes. It handles exceptions from either of the file-access beans in addition to handling SQL and I/O exceptions.

### File Upload and Download Tag Descriptions

For file uploading, OC4J supplies the `httpUpload` tag. This tag, in turn, uses `HttpUploadBean`. For convenience, you can also use the `httpUploadForm` tag in programming the form through which users specify the files to upload, or you can code the form manually.

For file downloading, OC4J provides the custom `httpDownload` tag.This tag uses `HttpDownloadBean`. This section describes these tags and their attributes.

Note the following requirements for the file upload and download tags:

- Verify that the file `ojsputil.jar` is installed and in your classpath. This file is provided with OC4J, in the "well-known" tag library directory.

- Th``e tag library descriptor, `fileaccess.tld`, must be available to the application, and any JSP page using the library must have an appropriate `taglib` directive. In an Oracle Application Server installation, the TLD is in `ojsputil.jar`. The `uri` value for `fileaccess.tld` is the following:

      http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/fileaccess.tld

You can refer to the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide for information about `taglib` directives, the well-known tag library directory, TLD files, and the meaning of `uri` values.

Notes: The prefix "fileaccess:" is used in the tag syntax here. This is by convention but is not required. You can specify any desired prefix in your `taglib` directive. See "Tag Syntax Symbology and Notes" for general information about tag syntax conventions in this manual.

#### The ht tpUploadForm Tag

For convenience, you can use the `httpUploadForm` tag to create a form in your application, using multipart encoded form data, that allows users to specify the files to upload.

##### Syntax

    <fileaccess:httpUploadForm formsAction = "action"
                             [ maxFiles = "max_number" ]
                             [ fileNameSize = "file_input_box_num_chars" ]
                             [ maxFileNameSize = "max_file_name_num_chars" ]
                             [ includeNumbers = "true" | "false" ]
                             [ submitButtonText = "button_label_text" ] />

Note: The `httpUploadForm` tag can optionally use a body. For example, the body might consist of a user prompt.

##### Attributes

- `formsAction` (required): This is to indicate the action that will be performed after the form is submitted. For example, `formsAction` could be the name of a JSP page that uses `HttpUploadBean` or the `httpUpload` tag.

- `maxFiles`: Use this if you want to specify the number of input lines you want to appear in the form. The default is 1.

- `fileNameSize`: Use this if you want to specify the character-width of the file name input box (or boxes). The default is 20 characters.

- `maxFileNameSize`: Use this if you want to specify the maximum number of characters allowed in a file name. The default is 80 characters.

- `includeNumbers`: Set this to "`true`" if you want the file name input boxes to be numbered. The default setting is "`false`".

- `submitButtonText`: Use this if you want to specify the text that appears on the "submit" button of the form. The default is "`Send`".

#### The ht tpUpload Tag

This tag wraps the functionality of the `HttpUploadBean` JavaBean, paralleling its attributes. See "Overview of File Uploading" and "The HttpUploadBean" for related information.

##### Syntax

    <fileaccess:httpUpload destination = "dir_path_or_prefix"
                     [ destinationType = "filesystem" | "database" ]
                     [ connId = "id" ]
                     [ scope = "request" | "page" | "session" | "applicaton" ]
                     [ overwrite = "true" | "false" ]
                     [ fileType = "character" | "binary" ]
                     [ table = "table_name" ]
                     [ prefixColumn = "column_name" ]
                     [ fileNameColumn = "column_name" ]
                     [ dataColumn = "column_name" ] />

Note: For uploads to a file system, the base directory is automatically retrievable by the tag handler from the JSP page context.

##### Attributes

- `destination` (required): For uploading to a file system, this indicates the path, beneath the base directory supplied in the `/WEB-INF/fileaccess.properties` file, of the directory into which files will be uploaded. For uploading to a database, `destination` indicates the file prefix, conceptually equivalent to a file system path.

  Note: Typically, the `destination` value will be based at least partially on user input.

- `destinationType`: Set this to "`database`" for uploading to a database. The default is to upload to a file system, but you can also explicitly set it to "`filesystem`". These values are case-insensitive.

- `connId`: For uploading to a database, use this attribute to provide a `ConnBean` connection ID for the database connection to be used. Or, alternatively, use the `httpUpload` tag inside a `dbOpen` tag to implicitly use the `dbOpen` connection. For information about the `ConnBean` JavaBean and `dbOpen` tag provided with OC4J, see Chapter 4, "Data-Access JavaBeans and Tags".

- `scope`: For uploading to a database, use this attribute to specify the scope of the `ConnBean` instance for the connection. The scope setting here must match the scope setting when the `ConnBean` instance was created, such as in a `dbOpen` tag. If the `httpUpload` tag is nested inside a `dbOpen` tag, then there is no need to specify `connId` or `scope`. In this case, information will be taken from the `dbOpen` tag. Otherwise, the default scope setting is "`page`".

- `overwrite`: Set this to "`false`" if you do not want to overwrite existing files that have the same paths and names as the files you are uploading, or if you do not want to update rows with the same file name and prefix for database uploading. In this case, an error will be generated if a file already exists. By default, `overwrite` is set to "`true`" and `httpUpload` overwrites files.

- `fileType`: For uploading to a database, set this attribute to "`character`" for character data, which will be written into a CLOB. The default setting is "`binary`" for binary data, which will be written into a BLOB.

- `table`: For uploading to a database table other than the default `fileaccess` table, use this attribute to specify the table name.

- `prefixColumn`: For uploading to a database table other than the default `fileaccess` table, use this attribute to specify the name of the column containing file prefixes. This column is where the `destination` values will be written.

- `fileNameColumn`: For uploading to a database table other than the default `fileaccess` table, use this attribute to specify the name of the column containing file names.

- `dataColumn`: For uploading to a database table other than the default `fileaccess` table, use this attribute to specify the name of the column containing file contents.

##### Example

This example has a page that uses the `httpUploadForm` tag to create the HTML form for specifying files to upload. The `httpUploadForm` tag specifies `httpUploadExample.jsp` as its forms action. The `httpUploadExample.jsp` page uses the `httpUpload` tag to upload to the default `fileaccess` table in a database.

Here is the page for the HTML form:

    <%@ page language="java" import="java.io.*"  %>
    <%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/fileaccess.tld"
               prefix="upload" %>
    <html> <body>
    <fileaccess:httpUploadForm
          formsAction="httpUploadExample.jsp"
          maxFiles='<%= request.getParameter("MaxFiles") %>'
          includeNumbers="true"  fileNameSize="50"  maxFileNameSize="120" >
              <br> File:
    </fileaccess:httpUploadForm>
    </body> </html>

And following is the `httpUploadExample.jsp` page. Note that the `httpUpload` tag gets its database connection as a result of being inside a `dbOpen` tag. Also note that `useDataSource.jsp` is used to obtain the connection, if necessary. See "useDataSource.jsp".

    <%@ page language="java" %>
    <%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/fileaccess.tld"
               prefix="upload" %>
    <%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/sqltaglib.tld"
               prefix="sql" %>
    <% String dataSrcStr=request.getParameter("dataSrcStr"); // get conn string
       if (dataSrcStr==null) {  dataSrcStr=(String)session.getValue("dataSrcStr"); }
       else {  session.putValue("dataSrcStr",dataSrcStr); }
       if (dataSrcStr==null) { %>
           <jsp:forward page="useDataSource.jsp" />
    <% } %>
    <html><body>
    <sql:dbOpen dataSource="<%= dataSrcStr %>" >
       <fileaccess:httpUpload  destinationType = "database"
                               destination="tagexample" />
    </sql:dbOpen>
    Done! </body></html>

Note: For the `dbOpen` tag in this example, assume that the data source specifies the user name and password as well as the URL.

#### The ht tpDownload Tag

This tag wraps the functionality of the `HttpDownloadBean` JavaBean, paralleling its attributes. See "Overview of File Downloading" and "The HttpDownloadBean" for related information.

##### Syntax

    <fileaccess:httpDownload servletPath = "path"
                       source = "dir_path_or_prefix"
                     [ sourceType = "filesystem" | "database" ]
                     [ connId = "id" ]
                     [ scope = "request" | "page" | "session" | "applicaton" ]
                     [ recurse = "true" | "false" ]
                     [ fileType = "character" | "binary" ]
                     [ table = "table_name" ]
                     [ prefixColumn = "column_name" ]
                     [ fileNameColumn = "column_name" ]
                     [ dataColumn = "column_name" ] />

Notes: The `httpDownload` tag can optionally use a body. For example, the body might consist of a user prompt. For downloads from a file system, the base directory is automatically retrievable by the tag handler from the JSP page context.

##### Attributes

- `servletPath` (required): This is the path to the Oracle `DownloadServlet`, which executes the actual download of each file. For example, if `DownloadServlet` has been installed in the application `app` and mapped to the name `download`, then use "`/app/download/`", with leading and trailing slashes, as the `servletPath` setting. The `httpDownload` tag handler uses this path in constructing the URL to `DownloadServlet`.

  See "The Download Servlet" for more information about this servlet.

- `source` (required): For downloading from a file system, this attribute indicates the path, beneath the base directory supplied in the file `/WEB-INF/fileaccess.properties`, of the directory from which files are retrieved. A value of "`*`" results in all directories under the base directory being available.

  For downloading from a database, this attribute indicates the file prefix, conceptually equivalent to a file system path. If recursive downloading is enabled (through the `recurse` attribute), "`%`" will be appended onto the `source` value, and the `WHERE` clause for the query will contain an appropriate `LIKE` clause. Therefore, all files with prefixes that are partially matched by the source value will be available for download. If you want to match all rows in the database table, set `source` to "`*`".

  Note: Typically, the `source` value is based at least partially on user input.

- `sourceType`: Set this to "`database`" for downloading from a database. The default is to download from a file system, or you can explicitly set this to "`filesystem`".

- `connId`: For downloading from a database, use this attribute to provide a `ConnBean` connection ID for the database connection to be used. Or, alternatively, you can use the `httpDownload` tag inside a `dbOpen` tag to implicitly use the `dbOpen` connection. For information about the `ConnBean` JavaBean and `dbOpen` tag provided with OC4J, see Chapter 4, "Data-Access JavaBeans and Tags".

- `scope`: For downloading from a database, use this attribute to specify the scope of the `ConnBean` instance for the connection. The scope setting here must match the scope setting when the `ConnBean` instance was created, such as in a `dbOpen` tag. If the `httpDownload` tag is nested inside a `dbOpen` tag, then there is no need to specify `connId` or `scope`. In this case, information will be taken from the `dbOpen` tag. Otherwise, the default scope setting is "`page`".

- `recurse`: Set this to "`false`" if you do not want recursive downloading functionality, where files in file system subdirectories or with additional database prefix information will also be listed as available for download. As an example of this functionality from a database, assume you have set `source` to "`/user`". Recursiveness would also find matches for files with prefixes such as "`/user/bill`" and "`/user/mary`", and also such as "`/user1`", "`/user2`", "`/user1/tom`", and "`/user2/susan`". The default mode is recursiveness, or you can enable it explicitly with a setting of "`true`".

- `fileType`: For downloading from a database, set this attribute to "`character`" for character data, which will be retrieved from a CLOB. The default setting is "`binary`" for binary data, which will be retrieved from a BLOB.

- `table`: For downloading from a database table other than the default `fileaccess` table, use this attribute to specify the table name.

- `prefixColumn`: For downloading from a database table other than the default `fileaccess` table, use this attribute to specify the name of the column containing file prefixes, which is where `source` values are stored.

- `fileNameColumn`: For downloading from a database table other than the default `fileaccess` table, use this attribute to specify the name of the column containing file names. File names include any file name extensions.

- `dataColumn`: For downloading from a database table other than the default `fileaccess` table, use this attribute to specify the name of the column that stores the file contents.

##### Example

This example is a JSP page that uses the `httpDownload` tag to download from the default `fileaccess` table of a database. The tag body content ("`<br>:`") will be output before each file name in the list of files available for download. Note that you must specify the `DownloadServlet` servlet path in the `httpDownload` tag. The tag handler will use it in constructing the URL to `DownloadServlet`, which performs the actual downloading.

    <%@ page language="java" %>
    <%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/fileaccess.tld"
               prefix="download" %>
    <%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/sqltaglib.tld"
               prefix="sql" %>
    <% String dataSrcStr=request.getParameter("dataSrcStr");
       if (dataSrcStr==null) { dataSrcStr=(String)session.getValue("dataSrcStr");}
       else { session.putValue("dataSrcStr",dataSrcStr);}
       if (dataSrcStr==null) { %>
          <jsp:forward page="useDataSource.jsp" />
    <% } %>
    <html> <body>
    <% String servletPath = "/servlet/download/"; %>
    <sql:dbOpen dataSource="<%= dataSrcStr %>" >
    <fileaccess:httpDownload sourceType = "database"
                source="tagexample" servletPath = '<%= servletPath %>' >
       <br>:
    </fileaccess:httpDownload>
    </sql:dbOpen>
    <br>Done!
    </body> </html>

Note: For the `dbOpen` tag in this example, assume that the data source specifies the user name and password as well as the URI.

## Mail JavaBean and Tag

It is often useful to send e-mail messages from a Web application, based on Web site status or user actions, for example. Sun Microsystems has specified a platform-independent and protocol-independent framework for this through its `javax.mail` package and subpackages, known as the JavaMail API.

For further convenience, Oracle supplies a JavaBean and JSP custom tag based on the JavaMail API to use in providing e-mail functionality through your servlets or JSP pages. The bean and tag, as with other JavaBeans and custom tags supplied with OC4J, are implemented according to JSP and servlet standards.

The following sections describe the mail JavaBean and tag:

- General Considerations for the Mail JavaBean and Tag

- Mail Attachments

- SendMailBean Description

- The sendMail Tag Description

For more information about the JavaMail API, refer to the following Sun Microsystems Web site:

    http://java.sun.com/products/javamail/1.2/docs/javadocs/index.html

### General Considerations for the Mail JavaBean and Tag

Be aware of the following points, which apply to use of either the mail JavaBean (`SendMailBean`) or the mail tag (`sendMail`):

- The files `mail.jar`, containing the JavaMail packages, and `jaf.jar`, for the JavaBeans Activation Framework, must be in your classpath for mail functionality. These files are provided with OC4J.

- To enable support for attachments, the file `sendmail.properties` must exist, with an appropriate setting, in the application `/WEB-INF` directory. See "Enabling Attachments", which follows shortly.

- There is no particular limit to the size of an e-mail message, other than limits of the JVM, system memory, or mail server.

- Setting up default mail sessions is specific to the particular Web server. The current implementations of the mail bean and tag do not support automatic use of the default mail session. As an alternative, you can write your own code to obtain the default mail session if one exists for your platform, and to make the session available to the mail bean or tag.

### Mail Atta chments

The mail bean and tag support the sending of attachments with e-mail messages. (This support was introduced in the OC4J 9.0.3 implementation.) There are three modes of operation:

- No support for attachments

- Support for attaching one or more files that are on the OC4J server machine, known as server-side attachments

- Support for attaching one file that is on the client machine, known as a client-side attachment

For a client-side attachment, the file is automatically uploaded to the server machine as part of the process. Multiple client-side attachments are not supported.

#### Enabling Attachments

Whether attachments are enabled, and which kind of attachments, is determined by a `sendmail.properties` file in the application `/WEB-INF` directory. A file with the following content disables attachments:

    ## email attachment permissions
    sendmail.attachment=none

You must create this file in `/WEB-INF` and update it appropriately for any OC4J instance that will use mail attachments.

Any single application can support server-side attachments or client-side attachments, but not both.

To enable server-side attachments, change the setting to `server`, as follows:

    sendmail.attachment=server

To enable client-side attachments, change the setting to `client`:

    sendmail.attachment=client

Having multiple settings is an error condition.

Note: The absence of a `sendmail.properties` file is treated as equivalent to the presence of `sendmail.properties` with a setting of `none`. Mail attachments are disabled in this case.

#### Sending Attachments

For the mail tag, if server-side attachments are enabled, use the `serverAttachment` tag attribute if you want to specify one or more server-side files to attach to a message. If client-side attachments are enabled, use the `clientAttachment` tag attribute if you want to specify a client-side file to attach to a message (maximum of one file). See "The sendMail Tag Description". Note that either one of the two attachment modes, but not both, can be supported for any single application.

For both the server attachment mode and the client attachment mode, the mail bean includes methods to specify or retrieve the name (or names) of the file (or files) to attach. See information about `setServerAttachment()`, `getServerAttachment()`, `setClientAttachment()`, and `getClientAttachment()` in "SendMailBean Method Descriptions".

With either the mail tag or mail bean, a list of server-side files to attach can be either comma-delimited or semicolon-delimited, but not space-delimited (given that spaces are allowed in file names in some operating systems).

#### Attachment Usage Notes

Be aware of the following usage notes for mail attachments, applying to both the mail tag and mail bean.

- For a client-side file attachment, the file-access `httpUpload` tag is used behind the scenes. The file is uploaded to a temporary location on the OC4J server machine, then deleted once the message has been sent. Any limitations or requirements of the `httpUpload` tag apply to a client-side mail attachment as well. See "File Upload and Download Tag Descriptions".

- Many e-mail servers have somewhat restrictive size limitations, often approximately 4 MB for any one attachment. The only restrictions for the mail tag or bean are according to disk or memory limitations of the server machine.

- If a problem is encountered with any attachment, the e-mail message is terminated.

- Path names are not exposed to the mail recipient in either the server attachment or client attachment mode. Only the file name itself is indicated.

- For server-side attachments, attaching multiple files of the same name (but obviously with different paths) is supported. How this is handled at the recipient end, regarding any possible file renaming to avoid conflict, is according to the mail client being used. Similarly, in either attachment mode, the mail client might rename a file if an attachment has the same name as an attachment to a previous message. This is all beyond the scope and control of the OC4J mail attachment feature.

- You cannot use wild-card characters for file names.

### Send MailBean Description

The `oracle.jsp.webutil.email.SendMailBean` JavaBean is supplied with OC4J to support e-mail functionality from servlet or JSP applications. To use it in a JSP page, you can instantiate it through the standard `jsp:useBean` tag. (For JSP applications, however, you would typically use the `sendMail` tag instead of `SendMailBean`. See "The sendMail Tag Description".)

#### SendMailBean Requirements

To use `SendMailBean`, verify that the files `ojsputil.jar`, `mail.jar`, and `activation.jar` are installed and in your classpath. These files are supplied with OC4J.

When you use `SendMailBean` in your code, you must provide the following:

- Message sender

  Use the `setSender()` method to specify the sender.

- Primary recipient (or recipients) of the message

  Use the `setRecipient()` method to specify the primary recipient (or recipients).

- Valid JavaMail session object (`javax.mail.Session`), either directly or indirectly

  There are three ways to supply a JavaMail session:

  - Use the `setHost()` method to specify a host system. In this case, a JavaMail session object will be created automatically.

  - Use the `setMailSession()` method to provide a JavaMail session object directly.

  - For JSP applications, use the `setSession()` method to specify the name of a JavaMail session object that already exists and is accessible through a "session string, `javax.mail.Session` object" pair in the JSP page context. In this case, you must supply the page context instance as an input parameter when you call the `sendMessage()` method to send the e-mail message.

All other `SendMailBean` attributes are optional.

#### SendMailBean Method Descriptions

This section lists and describes `SendMailBean` methods to send mail messages, close mail sessions, and set or get bean attributes.

Note: To comply with the JavaBean specification, `SendMailBean` has a no-argument constructor.

Here are the public `SendMailBean` methods:

- `void sendMessage()`

- `void sendMessage(javax.servlet.jsp.PageContext)`

  Use the `sendMessage()` method to send the e-mail message.

  If you use the `setSession()` method to supply a JavaMail session, then you must use the `sendMessage(PageContext)` signature and provide the page context instance that holds the specified mail session instance.

  If you use the `setMailSession()` or `setHost()` method to supply a JavaMail session, then you do not have to provide a page context in using the `sendMessage()` method.

  Also be aware, however, that specifying a page context instance might be relevant in determining the character set of an e-mail message with a "text" content type. If you provide no page context when invoking the `sendMessage()` method, then the default character set is `ISO-8859-1`. If you do provide a page context, then the default character set is that of the `response` object of the page context. Also note that you can specify the content type and character set directly through the `setContentType()` method.

- `void close()`

  Use this method if you want to release the resources of the JavaMail session instance from the `SendMailBean` instance. This method does not actually close the session.

- `void setBcc(String s)`

  Specify a space-delimited or comma-delimited list of any IDs (e-mail addresses or aliases) to receive blind copies of the message. These IDs will be suppressed from the message Cc field.

- `String getBcc()`

  Retrieve the list of IDs to receive blind copies of the message.

- `void setCc(String s)`

  Specify a space-delimited or comma-delimited list of any IDs (e-mail addresses or aliases) to receive copies of the message. These IDs will appear in the message Cc field.

- `String getCc()`

  Retrieve the list of IDs to receive copies of the message.

- `void setContent(String s)`

  Specify the contents of the e-mail message.

- `String getContent()`

  Retrieve the contents of the e-mail message.

- `void setContentEncoding(String s)`

  Specify the content encoding of the e-mail message. Specify "`base64`" or "`B`" for base64 encoding, "`quoted-printable`" or "`Q`" for quoted-printable encoding, "`7bit`" for seven-bit encoding, or "`8bit`" for eight-bit encoding. These content encodings are part of the JavaMail and RFC 2047 standards. Entries are case-insensitive.

  The default content encoding setting is "`null`", in which case the encoding of the message and headers will be determined by the content. If most characters to be encoded are in ASCII, then quoted-printable encoding will be used; otherwise, `base64` encoding will be used.

- `String getContentEncoding()`

  Retrieve the content encoding of the message.

- `void setContentType(String s)`

  Specify the MIME type and optionally the character set of the message, such as in the following examples:

      setContentType("text/html");

      setContentType("text/html; charset=US-ASCII");

  The default MIME type setting is "`text/plain`", but you cannot specify a character set without explicitly specifying that or some other "`text/``xxxx`" MIME type setting.

  The default character set depends on whether you provide a JSP page context instance when you call the `sendMessage()` method to send the e-mail message. If you provide no page context, then the default character set is `ISO-8859-1`. If you do provide a page context, then the default character set is that of the `response` object of the page context.

- `String getContentType()`

  Retrieve the MIME type (and character encoding, if applicable) of the message.

- `void setHost(String s)`

  One of the ways to supply a JavaMail session is to specify a mail server host name, in which case `SendMailBean` will obtain a session automatically. Use the `setHost()` method for this purpose, providing a mail host name such as "`gmail.oraclecorp.com`".

  See "SendMailBean Requirements" for an overview of supplying the JavaMail session.

- `String getHost()`

  Retrieve the specified mail server host name.

- `void setMailSession(javax.mail.Session sessobj)`

  One of the ways to supply a JavaMail session is to provide the session object directly. Use the `setMailSession()` method for this purpose, providing a `javax.mail.Session` instance.

  See "SendMailBean Requirements" for an overview of supplying the JavaMail session.

- `javax.mail.Session getMailSession()`

  This returns a JavaMail session that you had previously set.

- `void setRecipient(String s)`

  Specify a space-delimited or comma-delimited list of IDs (e-mail addresses or aliases) of the primary recipients of the message. These IDs will appear in the To field of the message. You must specify at least one recipient.

- `String getRecipient()`

  Retrieve the list of IDs of the primary recipients of the message.

- `void setSender(String s)`

  Specify the ID (e-mail address or alias) of the message sender. This ID will appear in the From field of the message. You must specify the sender.

- `String getSender()`

  Retrieve the ID of the message sender.

- `void setSession(String s)`

  One of the ways to supply a JavaMail session is to provide the name of a `javax.mail.Session` instance that already exists in the JSP page context object. Use the `setSession()` method for this purpose, specifying the name of the session instance.

  In this case, when you use the `sendMessage()` method to send the e-mail message, you must provide the `javax.servlet.jsp.PageContext` instance as input.

  See "SendMailBean Requirements" for an overview of supplying the JavaMail session.

- `String getSession()`

  Retrieve the name of the session instance.

- `void setSubject(String s)`

  Specify the subject line of the message.

- `String getSubject()`

  Retrieve the subject line of the message.

- `void setServerAttachment(String s)`

  Specify a comma-delimited or semicolon-delimited list of file names (including paths), for server-side files to attach to an e-mail message. These must be files on the OC4J server machine. Server-side attachments must be enabled in the `sendmail.properties` file.

- `String getServerAttachment()`

  Retrieve the file name list for server-side files to attach to the message. This might be useful in presenting a user confirmation page, for example.

- `void setClientAttachment(String s)`

  Specify the path and file name of the client-side file to attach to the e-mail message (maximum of one). This must be a file on the user's client machine. Client-side attachments must be enabled in the `sendmail.properties` file.

- `String getClientAttachment()`

  Retrieve the name of the client-side file to attach to the message. This might be useful in presenting a user confirmation page, for example.

  Note: Regarding mail attachments, see "Mail Attachments" for related information. Be aware that for any one application, you can use server-side attachments or client-side attachments but not both.

### The se ndMail Tag Description

As a convenience for JSP developers, OC4J supplies the `sendMail` tag to provide e-mail functionality for a JSP page. The following sections describe the tag:

- The sendMail Tag Syntax

- The sendMail Tag Attribute Descriptions

- Sample Application for sendMail Tag

Be aware of the following requirements for the `sendMail` tag:

- Verify that the files `ojsputil.jar`, `mail.jar`, and `activation.jar` are installed and in your classpath. These files are supplied with OC4J; `ojsputil.jar` is in the "well-known" tag library directory.

- In the current implementation, the `sendMail` tag has its own tag library descriptor, `email.tld`. This must be available to the application, and any JSP page using the tag must have an appropriate `taglib` directive. In an Oracle Application Server installation, the TLD is in `ojsputil.jar`. The `uri` value for `email.tld` is the following:

      http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/email.tld

You can refer to the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide for information about `taglib` directives, the well-known tag library directory, TLD files, and the meaning of `uri` values.

#### The sendMail Tag Syntax

The `sendMail` tag has the following syntax:

    <mail:sendMail host = "SMTP_host_name" | session = "JavaMail_session_name"
                   sender = "sender_address"
                   recipient = "primary_recipient_IDs"
                 [ cc = "cc_recipient_IDs" ]
                 [ bcc = "bcc_recipient_IDs" ]
                 [ subject = "subject_line" ]
                 [ contentType = "MIME_type; [charset=charset]" ]
                 [ contentEncoding = "B"|"base64"|"Q"|"quoted-printable"|
                                     "7bit"|"8bit" ]
                 [ serverAttachment = "server_file_list" |
                   clientAttachment = "client_file" ] >
    ...
    E-mail body
    ...
    </mail:sendMail>

##### sendMail Tag Usage Notes

Be aware of the following when using the `sendMail` tag:

- The `sender` and `recipient` attributes are required, and either the `host` or `session` attribute is required.

- Multiple recipients, cc targets, or bcc targets are space-delimited or comma-delimited.

- Use of `serverAttachment` assumes server-side attachments are enabled in the `sendmail.properties` file. Similarly, use of `clientAttachment` assumes client-side attachments are enabled in `sendmail.properties`. Only one mode can be enabled for a single application. See "Enabling Attachments".

- File names in the `serverAttachment` setting can be comma-delimited or semicolon-delimited, but not space-delimited.

- The e-mail body can contain JSP syntax, which will be processed by the JSP translator.

- Attributes used by the tag are typically input by the user in form fields. All attributes accept request-time expressions.

- The prefix "mail:" is used in the tag syntax here. This is by convention but is not required. You can specify any desired prefix in your `taglib` directive.

- See "Tag Syntax Symbology and Notes" for general information about tag syntax conventions in this manual.

#### The sendMail Tag Attribute Descriptions

The `sendMail` tag supports the following attributes:

- `host` (required if `session` is not specified): This is the appropriate mail host name, such as "`gmail.oraclecorp.com`". This is used in creating a JavaMail session object for the mail message. Alternatively, you can determine a JavaMail session through the `session` attribute.

- `session` (required if `host` is not specified): This is the name of an existing JavaMail session object that can be retrieved from the JSP page context. Alternatively, you can determine a JavaMail session through the `host` attribute.

- `sender` (required): This is the ID (e-mail address or alias) of the sender of the message. This ID will appear in the From field of the message.

- `recipient` (required): This is a space-delimited or comma-delimited list of IDs of the primary recipients of the message. These IDs will appear in the To field of the message.

- `cc` : This is a space-delimited or comma-delimited list of IDs to receive a copy of the message. These IDs will appear in the Cc field of the message.

- `bcc` : This is a space-delimited or comma-delimited list of IDs to receive a blind copy of the message. These IDs will be suppressed from the Cc field.

- `subject`: This is the subject line of the message.

- `contentType`: This is for the MIME type of the message, and optionally a character set as well, as in the following examples:

      contentType="text/html"

      contentType="text/html; charset=US-ASCII"

  The default MIME type setting is "`text/plain`", but you cannot specify a character set without explicitly specifying that or some other `text/``xxxx` MIME type.

  The default character set is that of the `response` object of the JSP page context.

- `contentEncoding`: Specify "`B`" or "`base64`" for base64 encoding, "`Q`" or "`quoted-printable`" for quoted-printable encoding, "`7bit`" for seven-bit encoding, or "`8bit`" for eight-bit encoding. These are standard JavaMail and RFC 2047 encodings. Entries are case-insensitive.

  The default content encoding setting is "`null`", in which case the encoding of the message and headers will be determined by the content. If most characters to be encoded are in ASCII, then quoted-printable encoding will be used. Otherwise, `base64` encoding will be used.

- `serverAttachment`: This is a comma-delimited or semicolon-delimited list of server-side files to attach to the e-mail message. Server-side attachments must be enabled in the `sendmail.properties` file.

  Here is an example:

      serverAttachment="/tmp/confirm.pdf,/home/schedule.doc"

- `clientAttachment`: This is the name of a client-side file (maximum of one) to attach to the e-mail message. Client-side attachments must be enabled in the `sendmail.properties` file.

  Here is an example:

      clientAttachment="c:\finance\budget02.xls"

  Note: Regarding e-mail attachments, see "Mail Attachments" for related information. Be aware that for any one application, you can use server-side attachments or client-side attachments but not both.

#### Sa mple Application for sendMail Tag

This sample application illustrates use of the `sendMail` tag with no attachments. During the first execution cycle through the page, before the user has specified the sender (or anything else), the HTML form is displayed for user input. During the next execution cycle through the page, after the user has sent the input, the `sendMail` tag is executed. This page also uses an error page, `error.jsp` (shown below), to display any exceptions that are thrown.

    <%@ page language="java" errorPage="error.jsp" %>
    <%@ taglib uri="http://xmlns.oracle.com/j2ee/jsp/tld/ojsp/email.tld"
               prefix="mail" %>
    <%
    if (request.getParameter("sender")==null) {
    %>
    <HTML>
    <HEAD><TITLE>SendMail Sample</TITLE></HEAD>
    <FORM METHOD=post>
    <TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="20%">
    <TR><TD>Host:</TD><TD><INPUT TYPE="text" name="host" ></TD></TR>
    <TR><TD>From:</TD><TD><INPUT TYPE="text" name="sender" ></TD></TR>
    <TR><TD>To:</TD><TD><INPUT TYPE="text" name="recipient"  ></TD></TR>
    <TR><TD>Cc:</TD><TD><INPUT TYPE="text" name="cc" ></TD></TR>
    <TR><TD>Bcc:</TD><TD><INPUT TYPE="text" name="bcc" ></TD></TR>
    <TR><TD>Subject:</TD><TD><INPUT TYPE="text" name="subject"
    VALUE="Hi"></TD></TR>
    </TABLE><br>
    <TEXTAREA name="body" ROWS=4 COLS=30>"How are you!"</TEXTAREA><br><br>
    <INPUT TYPE="submit" value="Send">
    </FORM>
    <%
    }
    else{
    %>
    <BODY BGCOLOR="#FFFFFF">
    <P>Result:
           <HR>
           <mail:sendMail host='<%=request.getParameter("host")%>'
                 sender='<%=request.getParameter("sender")%>'
                 recipient='<%=request.getParameter("recipient")%>'
                 cc='<%=request.getParameter("cc")%>'
                 bcc='<%=request.getParameter("bcc")%>'
                 subject='<%=request.getParameter("subject")%>'>
                 <%=request.getParameter("body")%>
           </mail:sendMail>
    Sent out Successfully!
           <HR>
    </BODY>
    <%
    }
    %>
    </HTML>

Here is the error page, `error.jsp`:

    <%@ page language="java" isErrorPage="true"%>
    <HTML>
    Error: <%= exception.getMessage() %>
    </HTML>

When you run this application, you will initially see the default screen shown in Figure 8-1.

Figure 8-1 Message with Default Input

Description of "Figure 8-1 Message with Default Input"

And Figure 8-2 shows user input for a message from `brian.wright@oracle.com` to `blodney.treehut@oracle.com` through the host `gmail.oraclecorp.com`.

Figure 8-2 Message with User Input

Description of "Figure 8-2 Message with User Input"