
	Version 9.5 SP1	SEARCH CONTENTS \| PDF BOOKS \| HOME UP PREV NEXT

— Configuration —

Web Services Stack Runtime

The information is organized under the following headings:

Understanding axis2.xml Configuration
Runtime Configuration
Client-side Configuration
MTOM in Web Services Stack

Understanding axis2.xml Configuration

The axis2.xml is a configuration file provided by the Apache Software Foundation. For further information about the Axis2 parameters available in this file and their values, see the Axis2 Configuration Guide.

In the axis2.xml file, Web Services Stack also uses some custom parameters. They are set on the server side of the Axis2 configuration. You can find more information about these parameters in the following table:

Parameter Default Value Description

Parameter	Default Value	Description
`includeWrappedTypesDeclaration`	true	Defines whether to include message-wrapper types/elements in the WSDL XSD schema. Axis2 processes an RPC-style WSDL definition and automatically creates a wrapper element and type definition for each message. Then, Axis2 processes internally any request/response as if it is in a document style with an element declaration for each message. Possible values for this parameter are: true (by default) - Axis2 creates the web service instance and automatically adds the autogenerated types to the XSD schema in the original WSDL definition. false - Axis2 creates a copy of the WSDL definition when processing the message types and modifies the copy instead of the original WSDL document.
`enableWSDLValidation`	false	Defines whether to validate WSDL documents. Possible values are: true - Axis2 validates the provided WSDL document against the external resources. false (by default) - No validation against external resources is performed.
`enableSoapValidation`	false	Defines whether to validate SOAP messages. Possible values are: "false" (default value) - When the Axis2 client side and server side exchange SOAP messages, the messages are not validated automatically if they are compliant with the SOAP specification. "true" - The SOAP validation can be enabled both on the server side and on the client side. On the server side, the SOAP validation can be enabled on the following levels: globally - by setting the parameter in the axis2.xml file, you enable the validation globally. on service group level - by setting the parameter inside a ServiceGroup tag in the services.xml file, you enable the validation for a specific group. on service level - by setting the parameter inside a Service tag in the services.xml file, you enable the validation for a specific service. on operation level - by setting the parameter inside an Operation tag in the services.xml file, you enable the validation for a specific operation. on message context level - by setting the parameter programatically to MessageContext, you enable the validation for a specific request. On the client-side, the SOAP validation can be enabled on the following levels: globally - by setting the parameter in the axis2.xml file, you enable the validation globally. for a specific client execution - programatically by calling `Options.setProperty("disableSoapValidation",Boolean.TRUE)`, you enable the validation for operations that expect to deal with huge SOAP messages.

includeWrappedTypesDeclaration

true

Defines whether to include message-wrapper types/elements in the WSDL XSD schema. Axis2 processes an RPC-style WSDL definition and automatically creates a wrapper element and type definition for each message. Then, Axis2 processes internally any request/response as if it is in a document style with an element declaration for each message.

Possible values for this parameter are:

true (by default) - Axis2 creates the web service instance and automatically adds the autogenerated types to the XSD schema in the original WSDL definition.
false - Axis2 creates a copy of the WSDL definition when processing the message types and modifies the copy instead of the original WSDL document.

enableWSDLValidation

false

Defines whether to validate WSDL documents.

Possible values are:

true - Axis2 validates the provided WSDL document against the external resources.
false (by default) - No validation against external resources is performed.

enableSoapValidation

false

Defines whether to validate SOAP messages.

Possible values are:

"false" (default value) - When the Axis2 client side and server side exchange SOAP messages, the messages are not validated automatically if they are compliant with the SOAP specification.
"true" - The SOAP validation can be enabled both on the server side and on the client side.

On the server side, the SOAP validation can be enabled on the following levels:
- globally - by setting the parameter in the axis2.xml file, you enable the validation globally.
- on service group level - by setting the parameter inside a ServiceGroup tag in the services.xml file, you enable the validation for a specific group.
- on service level - by setting the parameter inside a Service tag in the services.xml file, you enable the validation for a specific service.
- on operation level - by setting the parameter inside an Operation tag in the services.xml file, you enable the validation for a specific operation.
- on message context level - by setting the parameter programatically to MessageContext, you enable the validation for a specific request.
On the client-side, the SOAP validation can be enabled on the following levels:
- globally - by setting the parameter in the axis2.xml file, you enable the validation globally.
- for a specific client execution - programatically by calling Options.setProperty("disableSoapValidation",Boolean.TRUE), you enable the validation for operations that expect to deal with huge SOAP messages.

Since messages that Software AG Web Services Stack processes are not always in SOAP format, the message builders and formatters provided by Axis2 are extended to ensure all messages are correctly converted. Below you will find some Web Services Stack specific information about the proprietory message formatters and message builders available in the axis2.xml configuration file.

Message Formatters
The Web Services Stack axis2.xml file has defined proprietary message formatters for the following content types to extend the default functionality provided by Axis2:

"text/xml"
"application/xml"
"application/soap+xml"

The new definitions are as follows:

<messageFormatter contentType="text/xml"
						class="com.softwareag.formatters.RawXMLFormatter" />  
		<messageFormatter contentType="application/xml"
						class="com.softwareag.formatters.RawXMLApplicationXMLFormatter" /> 
  <messageFormatter contentType="application/soap+xml"
						class="com.softwareag.formatters.RawXMLFormatter"/>
  <messageFormatter contentType="application/x-www-form-urlencoded"
      class="org.apache.axis2.transport.http.XFormURLEncodedFormatter"/>
  <messageFormatter contentType="multipart/form-data"
      class="org.apache.axis2.transport.http.MultipartFormDataFormatter"/>

Message Builders
The Web Services Stack axis2.xml file has defined proprietary message builders for the following content types to extend the default functionality provided by Axis2:

"text/xml"
"application/xml"
"application/soap+xml"

The new definitions are as follows:

<messageBuilder contentType="text/xml"
					class="com.softwareag.builders.RawXMLMessageBuilder"/>
		<messageBuilder contentType="application/soap+xml"
					class="com.softwareag.builders.RawXMLMessageBuilder"/>
		<messageBuilder contentType="application/xml"
					class="com.softwareag.builders.RawXMLMessageBuilder"/>
  <messageBuilder contentType="application/x-www-form-urlencoded"
     class="org.apache.axis2.builder.XFormURLEncodedBuilder"/>
  <messageBuilder contentType="multipart/form-data"
     class="org.apache.axis2.builder.MultipartFormDataBuilder"/>

The preceding message builders extend the default functionality provided by Axis 2 and handle some specific scenarios.

Runtime Configuration

This section provides information about the global runtime configuration. There are three kinds of configuration files - axis2.xml, services.xml, and module.xml:

axis2.xml is used for configuring the client side and the server side of all deployed Web services. The axis2.xml file is in the following directory: <Software AG_directory>/profiles/CTP/workspace/wsstack/repository/conf/.
services.xml is used for configuring Web services. The services.xml file is in the META-INF directory that is in the service archive (a file with an .aar extension) or in the unpacked service directory.

Note:
The service archive is in the <Software AG_directory>/profiles/CTP/workspace/wsstack/repository/services/ directory.
module.xml is used for configuring modules. The module.xml file is in the META-INF directory that is in the module archive (a file with a .mar extension) or in the unpacked module directory.

Note:
The module archive is in the <Software AG_directory>/profiles/CTP/workspace/wsstack/repository/modules/ directory.

Warning:
The axis2.xml file contains important information such as the user name and password for the administration console logon. System administrators must change these default credentials to protect the access to the axis2.xml configuration file.

There are some additional Web Services Stack specific configuration files:

SMH Agents Configuration Files:
- The deployclient.properties file is used by Software AG System Management Hub (SMH) for deploying Web services.
- The argusagent.properties file contains information about the host name and server port of the deployed Web Services Stack.
For more information about the deployclient.properties file and the argusagent.properties file, see the overview of The Administration Tool
Client-side Configuration Files:
- wsclientsec.properties - this file contains security-related information.
  
  For information about the wsclientsec.properties file, see the heading "Client-side Configuration" of Message-Level Security.

The installation of Web Services Stack provides the following runtime configuration:

Web Services Stack Client Runtime Configuration
Web Services Stack Runtime Configuration in Standalone Server
Web Services Stack Runtime Configuration in Web Application
Web Services Stack Runtime Configuration in Platform Tomcat Server

Web Services Stack Client Runtime Configuration

The installation of Web Services Stack provides a client runtime configuration. It is primarily used by the Web Services Stack SMH agents but it can be used by any user-implemented Web services client as well. Essentially, the Web Services Stack is administered by an administration service deployed on it and is referred by the SMH agents (the SMH agents are in the role of Web services clients).

Note:
To administer Web Services Stack on Platform Tomcat Server using the SMH web administration user interface, you must install Web Services Stack Administration tools and Core Files.

The client runtime configuration uses the following files:

Runtime configuration file:

<Software AG_directory>/WS-Stack/repository/conf/axis2.xml
Repository directory:

<Software AG_directory>/WS-Stack/repository
1. Web services directory:
  
  <Software AG_directory>/WS-Stack/repository/services
2. Modules directory:
  
  <Software AG_directory>/WS-Stack/repository/modules

Web Services Stack Runtime Configuration in Standalone Server

Web Services Stack provides a Standalone Server that can be started without using a servlet container or application server. The Standalone Server uses the following runtime configuration files by default (when started through <Software AG_directory>WS-Stack/bin/axis2server.bat|sh):

Runtime configuration file:

<Software AG_directory>/WS-Stack/conf/axis2.xml
Repository directory:

<Software AG_directory>/WS-Stack/repository
1. Web services directory:
  
  <Software AG_directory>/WS-Stack/repository/services
2. Modules directory:
  
  <Software AG_directory>/WS-Stack/repository/modules

Web Services Stack Runtime Configuration in Web Application

Web Services Stack is also distributed as a web application (wsstack.war file). In this case the repository is in the web application directory. You can find the wsstack.war file in the Web Services Stack installation directory <Software AG_directory>/WS-Stack/webapp/wsstack. You can deploy this web application on any servlet container. The following runtime configuration is used:

Runtime configuration file:

<WSS_WebApp_Directory>/WEB-INF/conf/axis2.xml
Repository directory:

<WSS_WebApp_Directory>/WEB-INF/
1. Web services directory:
  
  <WSS_WebApp_Directory>/WEB-INF/services
2. Modules directory:
  
  <WSS_WebApp_Directory>/WEB-INF/modules

Web Services Stack Runtime Configuration in Platform Tomcat Server

Web Services Stack is also integrated and distributed with Platform Tomcat Server. Web Services Stack uses the following runtime configuration when the Platform Tomcat Server is started:

Runtime configuration file:

<Software AG_directory>/profiles/CTP/workspace/wsstack/repository/conf/axis2.xml
Repository directory:

<Software AG_directory>/profiles/CTP/workspace/wsstack/repository
1. Web services directory:
  
  <Software AG_directory>/profiles/CTP/workspace/wsstack/repository/services
2. Modules directory:
  
  <Software AG_directory>/profiles/CTP/workspace/wsstack/repository/modules

Client-side Configuration

There is only one Web Services Stack specific configuration at the client side.

You can use the Web Services Security (WS-Security) specification by giving a value to the securityConfigFile parameter in the following way:

<parameter name="securityConfigFile">wsclientsec.properties</parameter>

The value of the parameter in the preceding example must be an absolute or relative path either to the current working directory, or to the <repository path>/conf directory and should point to wsclientsec.properties (the file that contains security-related information).

For more information about the configuration of wsclientsec.properties file, see the heading "Client-side Configuration" from Message-Level Security.

MTOM in Web Services Stack

Apache Axis2 supports Base64 encoding, SOAP with Attachments and MTOM (SOAP Message Transmission Optimization Mechanism).

MTOM is a specification of the World Wide Web Consortium (W3C) that focuses on solving the "Attachments" problem.

Binary content often has to be re-encoded in order to be sent as text data with SOAP messages. MTOM allows you to selectively encode portions of the message. In this case, you can send base64-encoded data as well as externally attached binary data.

For more information about MTOM, see the documentation of W3C.

Following are some useful configurations that you need in order to use MTOM in Web Services Stack.

You can set the enableMTOM parameter at all permitted levels (the global level in axis2.xml, the service level in services.xml, and the operation level in services.xml).

The enableMTOM parameter can have three different values:

"true"
The engine always responds with MTOM-ized messages in case of included binary data of schema type "xmime:base64Binary". For example:

<xsd:element minOccurs="0" name="binaryData" type="xmime:base64Binary"/>
"false"
The response is always non-MTOM-ized, no matter whether the request is MTOM-ized or not.
"optional"
The response is MTOM-ized only if the request is MTOM-ized. Otherwise, it is non-MTOM-ized.

Note:
Setting the value to "optional" prevents you from failures.

SEARCH CONTENTS | PDF BOOKS | HOME UP PREV NEXT