8
JSP Globalization Support

The JSP container in OC4J provides standard globalization support (also known as National Language Support, or NLS) according to the Sun Microsystems JavaServer Pages Specification, Version 1.1, 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 2.0 for uniform internal representation of text. Unicode is used as the base character set for conversion to alternative character sets.

This chapter describes key aspects of JSP support for globalization and internationalization. The following topics are covered:

• Content Type Settings

• JSP Support for Multibyte Parameter Encoding

  Note: For detailed information about Oracle9iAS Globalization Support, see the Oracle9i Application Server Globalization Support Guide.

Content Type Settings

This section covers standard ways to statically or dynamically specify the content type for a JSP page. It also discusses an Oracle extension method that allows you to specify a non-IANA (Internet Assigned Numbers Authority) character set for the JSP writer object. The section is organized as follows:

• Content Type Settings in the page Directive

• Dynamic Content Type Settings

• Oracle Extension for the Character Set of the JSP Writer Object

Content Type Settings in the page Directive

You can use the standard page directive contentType parameter to set the MIME type and to optionally set the character encoding for a JSP page. The MIME type applies to the HTTP response at runtime. The character encoding, if set, applies to both the page text during translation and the HTTP response at runtime.

Use the following syntax for the page directive:

<%@ page ... contentType="TYPE; charset=character_set" ... %>

or, to set the MIME type while using the default character set:

<%@ page ... contentType="TYPE" ... %>

TYPE is an IANA MIME type; character_set is an IANA character set. (When specifying a character set, the space after the semicolon is optional.)

For example:

<%@ page language="java" contentType="text/html; charset=UTF-8" %>

or:

<%@ page language="java" contentType="text/html" %>

The default MIME type is text/html. 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 default character encoding is ISO-8859-1 (also known as Latin-1). 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

There is no JSP requirement to use an IANA character set as long as you use a character set that Java and the Web browser support, but the IANA site lists the most common character sets. Using the preferred MIME names they document is recommended.

The parameters of a page directive are static. If a page discovers during execution that a different setting 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".

• Forward the request to another JSP page or to a servlet.

  Notes: The page directive that sets contentType should appear as early as possible in the JSP page. A JSP page written in a character set other than ISO-8859-1 must set the appropriate character set in a page directive. It cannot be set dynamically, because the page has to be aware of the setting during translation. Dynamic settings are for runtime only. The JSP 1.1 specification assumes that a JSP page is written in the same character set that it will use to deliver its content. This document, 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.

Dynamic Content Type Settings

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:

public void setContentType(java.lang.String contenttype)

(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 and the default character encoding is ISO-8859-1.

This 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".

Be aware of the following important usage notes:

• The JSP page cannot be unbuffered if you are using the setContentType() method. It is buffered by default; do not set buffer="none" in a page directive.

• The setContentType() call must appear early in the page, before any output to the browser or any jsp:include command (which flushes the JSP buffer to the browser).

• In servlet 2.2 environments, the response object has a setLocale() method that sets a default character set based on the specified locale, overriding any previous character set. For example, the following method call results in a character set of Shift_JIS:

  response.setLocale(new Locale("ja", "JP"));
  

Oracle Extension for the Character Set of the JSP Writer Object

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:

public 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 Big-5 as the character set of the content type, but specifies MS950, a non-IANA Hong Kong dialect of Big-5, as the character set of the JSP writer:

<%@ page contentType="text/html; charset=Big-5" %>
<% oracle.jsp.util.PublicUtil.setWriterEncoding(out, "MS950"); %>

Note: Use the setWriterEncoding() method as early as possible in the JSP page.

JSP Support for Multibyte Parameter Encoding

The Sun Microsystems servlet 2.3 specification documents a method, setCharacterEncoding(), that 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

This section covers the following topics:

• Standard setCharacterEncoding() Method

• Overview of Oracle Extensions for Older Servlet Environments

Standard setCharacterEncoding() Method

Effective with the servlet 2.3 specification, the setCharacterEncoding() method is specified in the javax.servlet.ServletRequest interface as the standard mechanism for specifying a non-default 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 (also specified in the ServletRequest interface).

There is also a corresponding getter method:

String getCharacterEncoding()

Overview of Oracle Extensions for Older Servlet Environments

In pre-2.3 servlet environments, the setCharacterEncoding() method is not available. For such environments, particularly the JServ servlet 2.0 environment, Oracle provides two alternative mechanisms:

• oracle.jsp.util.PublicUtil.setReqCharacterEncoding() static method (preferred)

• translate_params configuration parameter (or equivalent code)

For information about these mechanisms, see "Multibyte Parameter Encoding in JServ".