Programming WebLogic Web Services
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:
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.
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.
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:
web-services.xml
deployment descriptor file.weblogic.webservice.i18n.charset
WebLogic Server system property. 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.
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
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:
charset
attribute in the corresponding <web-service>
element of the web-services.xml
deployment descriptor.
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.
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.
When a WebLogic Web Service receives an HTTP SOAP request that invokes one of the service's operations, it honors HTTP headers as follows:
charset
attribute of the Content-Type
HTTP header, which specifies the character set of the SOAP request.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. 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>