Oracle® Containers for J2EE Support for JavaServer Pages Developer's Guide 10g (10.1.3.1.0) Part Number B28961-01 |
|
|
View PDF |
The Web container in OC4J provides standard globalization support (also known as National Language Support, or NLS) according to the JSP specification, and also offers extended support for servlet environments that do not support multibyte parameter encoding.
Standard Java support for localized content depends on the use of Unicode for uniform internal representation of text. Unicode is used as the base character set for conversion to alternative character sets. (The Unicode version depends on the JDK version. You can find the Unicode version through the Sun Microsystems Javadoc for the java.lang.Character
class.)
This chapter describes key aspects of JSP support for globalization and internationalization. The following sections are included:
Note: For detailed information about Oracle Application Server Globalization Support, see the Oracle Application Server Globalization Guide. |
The following sections cover standard ways to statically or dynamically specify the content type for a JSP page. There is also discussion of an Oracle extension method that enables you to specify a non-IANA (Internet Assigned Numbers Authority) character set for the JSP writer object.
The page
directive has two attributes, pageEncoding
and contentType
, that affect the character encoding of the JSP page source (during translation) or response (during runtime). The contentType
attribute also affects the MIME type of the response. The function of each attribute is as follows:
You can use contentType
to set the character encoding of the page source and response, and the MIME type of the response.
You can use pageEncoding
to set the character encoding of the page source. The main purpose of this attribute is to allow you to set a page source character encoding that is different than the response character encoding. However, this setting also acts as a default for the response character encoding if there is no contentType
attribute that specifies a character set.
There is more information about the relationship between contentType
and pageEncoding
later in this section.
Use the following syntax for contentType
:
contentType="TYPE; charset=character_set"
Alternatively, to set the MIME type while using the default character set:
contentType="TYPE"
Use the following syntax for pageEncoding
:
pageEncoding="character_set"
Use the following syntax to set everything:
<%@ page ... contentType="TYPE; charset=character_set" pageEncoding="character_set" ... %>
TYPE
is an IANA MIME type; character_set
is an IANA character set. When specifying a character set through the contentType
attribute, the space after the semicolon is optional.
Here are some examples of contentType
and pageEncoding
settings:
<%@ page language="java" contentType="text/html" %>
or:
<%@ page language="java" contentType="text/html; charset=ISO-8859-1" %>
or:
<%@ page language="java" contentType="text/html; charset=ISO-8859-1" pageEncoding="US-ASCII" %>
Without any page
directive settings, default settings are as follows:
The default MIME type is text/html
for traditional JSP pages; it is text/xml
for JSP XML documents.
The default for the page source character encoding (for translation) is ISO-8859-1
(also known as Latin-) for traditional JSP pages; it is UTF-8
or UTF-16
for JSP XML documents.
The default for the response character encoding is ISO-8859-
1 for traditional JSP pages; it is UTF-8
or UTF-16
for JSP XML documents.
The determination of UTF-8
versus UTF-16
is according to "Autodetection of Character Encodings" in the XML specification, at http://www.w3.org/TR/REC-xml.html
.
Be aware, however, that there is a relationship between pageEncoding
and contentType
regarding character encodings, as documented in the following table.
|
contentType Encoding Is Specified | contentType Encoding Is Not Specified |
---|---|---|
pageEncoding Is Specified |
Page source encoding is according to Response encoding is according to |
Page source encoding is according to Response encoding is according to |
pageEncoding Is Not Specified |
Page source encoding is according to Response encoding is according to |
Page source encoding is according to the default. Response encoding is according to the default. |
Be aware of the following important usage notes.
A page
directive that sets contentType
or pageEncoding
should appear as early as possible in the JSP page.
When a page is a JSP XML document, any pageEncoding
setting is ignored. The Web container will instead use the XML encoding declaration of the document. Consider the following example:
<?xml version="1.0" encoding="EUC-JP"> <jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.0"> <jsp:directive.page contentType="text/html;charset=Shift_Jis" /> <jsp:directive.page pageEncoding="UTF-8" /> ...
The effective page encoding would be EUC-JP
, not UTF-8
.
You should use pageEncoding
only for pages where the byte sequence represents legal characters in the target character set.
You should use contentType
only for pages or response output where the byte sequence represents legal characters in the target character set.
The target character set of the response output (as specified by contentType
, for example) should be a superset of the character set of the page source. For example, UTF-8
is the superset of Big5
, but ISO-8859-
is not.
The parameters of a page
directive are static. If a page discovers during execution that a different character set specification is necessary for the response, it can do one of the following:
Use the servlet response object API to set the content type during execution, as described in "Dynamic Content Type Settings".
or:
Forward the request to another JSP page or to a servlet.
A traditional JSP page source (not a JSP XML document) written in a character set other than ISO-8859-
must set the appropriate character set in a page
directive (through the contentType
or pageEncoding
attribute). The character set for the page encoding cannot be set dynamically, because the Web container has to be aware of the setting during translation.
This manual, for simplicity, assumes the typical case that the page text, request parameters, and response parameters all use the same encoding (although other scenarios are technically possible). Request parameter encoding is controlled by the browser, although Netscape and Internet Explorer browsers follow the setting you specify for the response parameters.
The IANA maintains a registry of MIME types at the following site:
ftp://www.isi.edu/in-notes/iana/assignments/media-types/media-types
The IANA maintains a registry of character encodings at the following site. Use the indicated "preferred MIME name" if one is listed:
http://www.iana.org/assignments/character-sets
You should use only character sets from the IANA list, except for any additional Oracle extensions as described in "Oracle Extension for the Character Set of the JSP Writer Object".
For situations where the appropriate content type for the HTTP response is not known until runtime, you can set it dynamically in the JSP page. The standard javax.servlet.ServletResponse
interface specifies the following method for this purpose:
void setContentType(java.lang.String contenttype)
Important: To use dynamic content type settings in an OC4J environment, you must enable the JSPstatic_text_in_chars configuration parameter. |
The implicit response
object of a JSP page is a javax.servlet.http.HttpServletResponse
instance, where the HttpServletResponse
interface extends the ServletResponse
interface.
The setContentType()
method input, like the contentType
setting in a page
directive, can include a MIME type only, or both a character set and a MIME type. For example:
response.setContentType("text/html; charset=UTF-8");
or:
response.setContentType("text/html");
As with a page
directive, the default MIME type is text/html
for traditional JSP pages or text/xml
for JSP XML documents, and the default character encoding is ISO-8859-
1.
Set the content type as early as possible in the page, before writing any output to the JspWriter
object.
The setContentType()
method has no effect on interpreting the text of the JSP page during translation. If a particular character set is required during translation, that must be specified in a page
directive, as described in "Content Type Settings in the page Directive".
In standard usage, the character set of the content type of the response
object, as determined by the page
directive contentType
parameter or the response.setContentType()
method, automatically becomes the character set of the JSP writer object as well. The JSP writer object is a javax.servlet.jsp.JspWriter
instance.
There are some character sets, however, that are not recognized by IANA and therefore cannot be used in a standard content type setting. For this reason, OC4J provides the static setWriterEncoding()
method of the oracle.jsp.util.PublicUtil
class:
static void setWriterEncoding(JspWriter out, String encoding)
You can use this method to specify the character set of the JSP writer directly, overriding the character set of the response
object. The following example uses Big5
as the character set of the content type, but specifies MS950
, a non-IANA Hong Kong dialect of Big5
, as the character set of the JSP writer:
<%@ page contentType="text/html; charset=Big5" %> <% oracle.jsp.util.PublicUtil.setWriterEncoding(out, "MS950"); %>
Note: Use thesetWriterEncoding() method as early as possible in the JSP page. |
The servlet specification has a method, setCharacterEncoding()
, in the javax.servlet.ServletRequest
interface. This method is useful in case the default encoding of the servlet container is not suitable for multibyte request parameters and bean property settings, such as for a getParameter()
call in Java code or a jsp:setProperty
tag to set a bean property in JSP code.
The setCharacterEncoding()
method and equivalent Oracle extensions affect parameter names and values, specifically:
Request object getParameter()
method output
Request object getParameterValues()
method output
Request object getParameterNames()
method output
jsp:setProperty
settings for bean property values
These topics are covered in the following sections:
Beginning with the servlet 2.3 specification, the setCharacterEncoding()
method is specified in the javax.servlet.ServletRequest
interface as the standard mechanism for specifying a nondefault character encoding for reading HTTP requests. The signature of this method is as follows:
void setCharacterEncoding(java.lang.String enc) throws java.io.UnsupportedEncodingException
The enc
parameter is a string specifying the name of the desired character encoding and overrides the default character encoding. Call this method before reading request parameters or reading input through the getReader()
method, which is also specified in the ServletRequest
interface.
There is also a corresponding getter method:
String getCharacterEncoding()