Skip navigation.
Downloads | Product Documentation | Support

Programming WebLogic Web Services

# Internationalization

The Internationalization Guide provides general information about internationalizing a WebLogic Server application. The following sections describe additional information specific to internationalizing a WebLogic Web Service:

- Overview of Internationalization
- Internationalizing a WebLogic Web Service
- Invoking a Web Service Using a Specific Character Set

# Overview of Internationalization

Internationalization refers to the preparation of software so that it behaves properly in multiple locations. Internationalization of WebLogic Web Services primarily involves specifying the character set of the SOAP request and response. You then specify the character set of the SOAP request inside the client application that invokes the Web Service. There are a variety of ways to specify the character set that WebLogic Server uses in its SOAP response, as outlined in later sections. WebLogic Server can also accept many character sets in a SOAP request used to invoke a deployed WebLogic Web Service.

Often the default character sets used by WebLogic Server are adequate and you do not need to explicitly specify a character set for a Web Service. For example, if a client application specifies its preferred character set, and there is no character set specified for a Web Service, then WebLogic Server responds by using the client's preferred character set. Also, non-internationalized WebLogic Server instances use the `US-ASCII` character set by default, and internationalized WebLogic Server instances use the `UTF-8` character set by default, and both of these character sets are compatible when one WebLogic Server instance is communicating with the other. This also means that a Web Service running on a non-internationalized WebLogic Server instance can handle multi-byte characters correctly.

However, if the default character sets are not adequate for your application, use the information here to specify the character set that you need.

# Internationalizing a WebLogic Web Service

This section describes how to set the character set for a WebLogic Web Service. It also describes how WebLogic Server determines what character set it should use when sending the SOAP message response of an invoke of a deployed Web Service.

## Specifying the Character Set for a WebLogic Web Service

When you specify the character set for a WebLogic Web Service, you are specifying the value of the `Content-Type` HTTP header of the SOAP message response to an invoke of a deployed Web Service. You use one of the following two methods to specify the character set for a WebLogic Web Service:

- Update the `web-services.xml` deployment descriptor file.
- Set the `weblogic.webservice.i18n.charset` WebLogic Server system property.

Warning: This method specifies the character set for all deployed Web Services.

### Updating the web-services.xml File

The preferred way to specify the character set used by a particular WebLogic Web Service is by updating its `web-serivces.xml` file.

To specify the character set for a WebLogic Web Service, update the `charset` attribute of the `<web-service>` element in the `web-services.xml` file. Set it equal to the standard name of the character set, as shown in the following sample excerpt:

>     <web-services>
>          <web-service name="stockquotes"
>                       targetNamespace="http://example.com"
>                       uri="/myStockQuoteService"
>                       charset="Shift_JIS">
>           ...

>          </web-service>
>     </web-services>

The default value is `US-ASCII`.

For the full list of character sets, see http://www.iana.org/assignments/character-sets.

If you set this attribute, the WebLogic Web Service always uses the specified character set in its SOAP response to an invoke of any operation in the Web Service.

### Setting a WebLogic Server System Property

You can also specify the character set for all deployed WebLogic Web Services deployed on a WebLogic Server instance by setting the system property `weblogic.webservice.i18n.charset` equal to the name of the character set. Set this system property in the script that starts up the WebLogic Server instance:

>     -Dweblogic.webservice.i18n.charset=utf-8

## Order of Precedence of Character Set Configuration Used By WebLogic Server

The following list shows the order by which WebLogic Server determines the character set of a WebLogic Web Service when it is creating the SOAP response to an invoke of one of its operations:

1. The value of the `charset` attribute in the corresponding `<web-service>` element of the `web-services.xml` deployment descriptor.

If this is not set, then WebLogic Server looks at the following:

2. The character set preferred by the client application that invoked the Web Service operation. If your client application uses the WebLogic Web Services client APIS, the character set is specified using the `weblogic.webservice.binding.BindingInfo.setAcceptCharset()` method.

If this is not set, then WebLogic Server looks at the following:

3. The value of the WebLogic Server system property `weblogic.webservice.i18n.charset`.

If this is not set, then WebLogic Server looks at the following:

4. The character set specified for the JVM. Specifically, if the JVM property `user.language` is set to `en`, then WebLogic Web Services use the `US-ASCII` character set. If the `user.language` property is set to anything else, WebLogic Web Services use the `UTF-8` character set.

# Invoking a Web Service Using a Specific Character Set

This section describes how to use WebLogic Web Service APIs to invoke a Web Service using a character set other than the default. The section also describes the character set settings in the HTTP request headers that are honored by WebLogic Web Services.

## Setting the Character Set When Invoking a Web Service

If you use the WebLogic Web Service client APIs to invoke a Web Service, you use the `weblogic.webservice.binding.BindingInfo.setCharset()` to set the character set of the client application's SOAP request. In particular, this method sets the `Content-Type` HTTP header. This method sets the character set of only the data travelling from the client application to the Web Service. The SOAP response from the Web Service might use a completely different character set; see Order of Precedence of Character Set Configuration Used By WebLogic Server for details on how to determine the character set of the SOAP response from a WebLogic Web Service.

Your client application can specify the character set that it would prefer the Web Service to use in its response by using the `weblogic.webservice.binding.BindingInfo.setAcceptCharset()` method. In particular, this method sets the `Accept-Charset` HTTP header.

The following code excerpt shows how to set the character set when invoking a Web Service operation, as well as specify the preferred character set in the response; in the example, `stub` is the instance of the JAX-RPC `Stub` class for your Web Service:

>     import weblogic.webservice.binding.BindingInfo;

>     ...

>         BindingInfo info =
>          (BindingInfo)stub._getProperty("weblogic.webservice.bindinginfo" );

>         // The following method sets the Content-Type HTTP header
>         info.setCharset( "UTF-8" );
>         port.helloWorld();

>         // The following method sets the Accept-Charset HTTP header
>         info.setAcceptCharset( "UTF-16" );
>         port.helloWorld();

For more information about the `weblogic.webservice.binding` package, see the Javadocs.

Warning: The `weblogic.webservice.binding` package is a proprietary WebLogic API; using it in your client applications might make it difficult to port them to non-WebLogic environments.

## Character Set Settings in HTTP Request Headers Honored by WebLogic Web Services

When a WebLogic Web Service receives an HTTP SOAP request that invokes one of the service's operations, it honors HTTP headers as follows:

- WebLogic Web Services always honor the `charset` attribute of the `Content-Type` HTTP header, which specifies the character set of the SOAP request.
- WebLogic Web Services sometimes honor the `Accept-Charset` HTTP header. This header specifies the character set of the SOAP response preferred by the application that invoked the Web Service operation. If the WebLogic Web Service has not been configured with a specific character set (see Specifying the Character Set for a WebLogic Web Service), the SOAP response uses the character set specified by the `Accept-Charset` HTTP header. If, however, the WebLogic Web Service is configured to use a specific character set, that character set is always used in the SOAP response.
- WebLogic Web Services never honor the `encoding` attribute of the optional `<?xml?>` element that starts the SOAP 1.1 envelope.

Note: This is true only for SOAP 1.1. For SOAP 1.2, if the `ContentType` HTTP Header is missing, then the `encoding` attribute of the `<?xml?>` element is honored.

The following excerpt of a SOAP envelope, including the HTTP headers, shows the three ways of specifying characters sets in bold:

>     POST /StockQuote HTTP/1.1
>     Host: www.sample.com
>     Content-Type: text/xml; charset="US-ASCII"
>     Content-Length: nnnn
>     SOAPAction: "Some-URI"
>     Accept-Charset: UTF-8

>     <?xml version="1.0" encoding="UTF-16"?>
>     <SOAP-ENV:Envelope
>       ...
>     </SOAP-ENV:Envelope>