|
Oracle® Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference
10g Release 2 (10.1.2) B14016-02 |
|
 Previous |
 Next |
|
Oracle® Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference
10g Release 2 (10.1.2) B14016-02 |
|
|
Previous |
Next |
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:
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:
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.
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. |
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 ( |
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.
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: Thejava.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 aConnBean 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.
|
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.
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 recursive 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".)
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
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 fileojsputil.jar is installed and in your classpath. This file is provided with OC4J.
|
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.
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.
Here are descriptions of the public methods of HttpUploadBean.
|
Note: Many of the attributes and setter methods forHttpUploadBean 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, thedestination 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.)
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 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 forDownloadServlet 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.
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.
Here are descriptions of the public methods of HttpDownloadBean.
|
Note: Many of the attributes and setter methods forHttpDownloadBean 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: ThelistFiles() 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, thesource 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.
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>
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.
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.
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.
The 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:
|
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.
<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: ThehttpUploadForm tag can optionally use a body. For example, the body might consist of a user prompt.
|
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".
This tag wraps the functionality of the HttpUploadBean JavaBean, paralleling its attributes. See "Overview of File Uploading" and "The HttpUploadBean" for related information.
<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. |
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, thedestination 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.
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 thedbOpen tag in this example, assume that the data source specifies the user name and password as well as the URL.
|
This tag wraps the functionality of the HttpDownloadBean JavaBean, paralleling its attributes. See "Overview of File Downloading" and "The HttpDownloadBean" for related information.
<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:
|
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, thesource 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.
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 thedbOpen tag in this example, assume that the data source specifies the user name and password as well as the URI.
|
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:
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
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.
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.
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 asendmail.properties file is treated as equivalent to the presence of sendmail.properties with a setting of none. Mail attachments are disabled in this case.
|
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).
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.
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".)
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.
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. |
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:
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 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>
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 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. |
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.
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.
