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

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

Skip navigation bar  Back to Top Previous Next