The information is organized under the following headings:
Following are the top-level elements that can be seen in the axis2.xml configuration file:
Parameters
In Axis 2, a parameter is a name value pair. Each top level parameter
available in the axis2.xml file (direct sub-elements of a
root element) is transformed into properties in
AxisConfiguration. Therefore, if you want to access the
top level parameters in the configuration document, you must use the
AxisConfiguration in the running system.
Following is the correct way of defining a parameter:
<parameter name="name of the parameter" >parameter value </parameter>
Transport Receivers
You must use a corresponding transport receiver for every other
transport that Axis 2 runs on. Following is an example of how you can add and
define transport receivers in the axis2.xml file:
<transportReceiver name="http" class="org.apache.axis2.transport.http.SimpleHTTPServer">
<parameter name="port" >6060</parameter>
</transportReceiver>
The attribute name of the
transportReceiver property is the name of the
transport itself. It can be HTTP, TCP, SMTP, etc. As soon as the system starts
up, or when you set the transport at the client side, you actually load the
transport that you have specified. The class attribute defines the actual Java
class that implements the interfaces required for the transport. Transports can
have zero parameters, but they can also have one or more than one.
Nevertheless, the corresponding transport receiver gives access to the
parameters.
Transport Senders
You can register transport senders in the system in the same way as
transport receivers. Later, at run time, those senders can be used to send
messages. As an example, consider Axis 2 running under Tomcat. In this case,
Axis can use TCP rather HTTP transport senders to send messages. Following is
the way to specify transport senders:
<transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender">
<parameter name="PROTOCOL" locked="xsd:false">HTTP/1.0</parameter>
</transportSender>
In the preceding example, the attribute
name is the name of the transport. The attribute
class is the implementation class of the corresponding transport. Transport
senders can have zero or more than one parameters in the same way as transport
receivers. If there are any parameters specified, then you can access them at
run time through the corresponding transport.
Phase Orders
The specifying order of phases in the execution chain has to be done
using a phase order element. Following is an example of such an element:
<phaseOrder type="inflow">
<phase name="TransportIn"/>
.
.
</phaseOrder>
If you want to add a handler that must go into
that phase, you can do that by adding directly a handler element into it. In
addition, configurations for handler chains in Axis 2 are also done in the
phase order element.
Following is an example of the complete configuration of the order of phases in the execution chain with specified corresponding handlers:
<phaseOrder type="InFlow"> <!-- System pre-defined phases --> <phase name="Transport"> <handler name="RequestURIBasedDispatcher" class="org.apache.axis2.engine.RequestURIBasedDispatcher"> <order phase="Transport"/> </handler> <handler name="SOAPActionBasedDispatcher" class="org.apache.axis2.engine.SOAPActionBasedDispatcher"> <order phase="Transport"/> </handler> </phase> <phase name="Security"/> <phase name="PreDispatch"/> <phase name="Dispatch" class="org.apache.axis2.engine.DispatchPhase"> <handler name="RequestURIBasedDispatcher" class="org.apache.axis2.engine.RequestURIBasedDispatcher"/> <handler name="SOAPActionBasedDispatcher" class="org.apache.axis2.engine.SOAPActionBasedDispatcher"/> <handler name="AddressingBasedDispatcher" class="org.apache.axis2.engine.AddressingBasedDispatcher"/> <handler name="RequestURIOperationDispatcher" class="org.apache.axis2.engine.RequestURIOperationDispatcher"/> <handler name="SOAPMessageBodyBasedDispatcher" class="org.apache.axis2.engine.SOAPMessageBodyBasedDispatcher"/> <handler name="HTTPLocationBasedDispatcher" class="org.apache.axis2.engine.HTTPLocationBasedDispatcher"/> </phase> <!-- System pre-defined phases --> <!-- After Postdispatch phase module author or service author can add any phase he or she wants --> <phase name="MyOwnPhase"/> <phase name="soapmonitorPhase"/> </phaseOrder>
The attribute type represents the type
of message flow and can be only one of the following kinds:
In-Flow
Out-Flow
In-FaultFlow
Out-FaultFlow
The following diagram shows a sample message flow with default phases:
In addition to the <handler> child element allowed inside the
phaseOrder, the other possible element is the
<phase> element. It represents available phases in the execution chain.
Following is the right way to specify phases inside
phaseOrder:
<phase name="Transport"/>
In this example, name is the name of
the phase.
There are two types of phases: pre-defined ones (required by Axis 2) and user-defined ones. In addition to the pre-defined phases, a user can add user-defined phases to the flows in the configuration file. For the in-flow, user-defined phases can be added only after the PostDispatch pre-defined phase. This is because the Axis 2 engine keeps the flow related information attached to the operations, and it is only after the Dispatch phase that the operation is found. There are no rules restricting the placement of user-defined phases in the out-flow. If any of the user-defined phases has the same name as that of a pre-defined phase, the engine fails to operate.
Web Services Stack 8.0 uses Axis 2 1.4 with the following definition of the default pre-defined system phases for the In-Flows:
<phase name="Transport"/>
<phase name="Addressing"/>
<phase name="PreSecurity"/>
<phase name="Security"/>
<phase name="PreDispatch"/>
<phase name="Dispatch"/>
<phase name="RMPhase"/>
<phase name="OperationInPhase"/>
<phase name="soapmonitorPhase"/>
Add your own phases after the system ones in In-Flows.
Web Services Stack 8.0 uses Axis 2 1.4 with the following definition of default pre-defined system phases for the Out-Flows:
<phase name="soapmonitorPhase"/>
<phase name="OperationOutPhase"/>
<phase name="RMPhase"/>
<phase name="PolicyDetermination"/>
<phase name="MessageOut"/>
<phase name="PreSecurity"/>
<phase name="Security"/>
Add your own phases before the system ones in Out-Flows.
Important:
Do not change the order of the system pre-defined phases in
all four kinds of flows. If you want to add a new phase, you can do that after
the system pre-defined phase, as is done in the default
axis2.xml file.
Module References
If you want to engage a module system-wide, you can do so by adding a
top-level module element in the axis2.xml file. Following
is an example of how to do it:
<module ref="addressing"/>
The parameter ref in the preceding
example is the module name that is going to be engaged system-wide.
Listeners (Observers)
In Axis 2, AxisConfiguration is observable, so
that one can register observers into that, and they are automatically informed
whenever a change occurs in AxisConfiguration. The
observers are informed of the following events:
Deploying a service
Removing a service
Activating/Deactivating a service
Deploying a module
Removing a module
Registering observers is very useful for additional features (such as RSS feed generation). Those observers provide service information to subscribers. The correct way of registering observers is the following:
<listener class="org.apache.axis2.ObserverIMPL">
<parameter name="RSS_URL" >http://127.0.0.1/rss</parameter>
</listener>
The parameter class represents an
observer implementation class. The implementation class must implement
AxisObserver interface, and the class has to be
available in the classpath.
Message Formatters
The Web Services Stack axis2.xml file has defined
new mesage 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.RawXMLFormatter" /> <messageFormatter contentType="application/soap+xml" class="com.softwareag.formatters.RawXMLApplicationXMLFormatter"/>
Message builders
The Web Services Stack axis2.xml file has defined
new mesage 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"/>
The preceding message builders extend the default functionality provided by Axis 2 and handle some specific scenarios.
Note:
See the axis2.xml file for additional
information about the possible settings and their values. The file also
contains additional comments and samples.
This section provides information on the configuration of global runtime through the axis2.xml file.
In Axis 2, there are three kinds of configuration files for configuring the system - the axis2.xml, the services.xml, and the module.xml:
axis2.xml for the global configuration
The file is used for configuration of the client side and the server side of all the deployed web services.
services.xml for the service configuration
The file is used for the configuration of web services and is only contained in service archives (AAR).
Note:
The service archive (AAR) is in the
WEB-INF\services\ folder.
module.xml for the module configuration
The file is used for the configuration of modules and is only contained in module archives (MAR).
Note:
The module archive (MAR) is in the
WEB-INF\modules\ folder.
There are some additional Web Services Stack-specific configuration files:
The deployclient.properties file that is used by SMH for the deployment functionality provided by it
The argusagent.properties file that is used by SMH for the Agents
For information on the deployclient.properties file and the argusagent.properties file, see the overview of The Administration Tool
The wsclientsec.properties file.
For information on the wsclientsec.properties file, see the heading "Client-side Configuration" of Message-Level Security.
Following are details on the axis2.xml configuration and on the proper way of adding and registering elements in axis2.xml:
In Axis 2, there are two kinds of axis2.xml configuration files - one for the configuration of the web service (server-side config file) and another one for configuration of the client of the web service (client-side config file).
Following is a screenshot of the locations of the occurrences of the axis2.xml file.
Note:
The installation folders of Web Services Stack are under
\SoftwareAG\<Web Services Stack> folder.
The first location is in the conf folder of the Web Services Stack tree. This is the file that is used for configuring a stand-alone server (server-side configuration).
The second location is the conf folder of the <Web Services Stack> folder\repository folder. This is the file for configurations of the client side of web services (client-side configuration).
The third location is the conf folder of the \<Web Services Stack> folder\webapp\META-INF folder. This is the file for configurations of the server side of web services (server-side configuration).
axis2.xml files for the server-side configuration;
Two different versions of the axis2.xml file are used for configuration of the web service (server-side config file)
The files for the web service (server-side config file) are placed into two different locations:
in \<Web Services Stack> folder\webapp\WEB-INF\conf after the Web Services Stack installation (see the preceding screen capture);
in \<Web Services Stack> folder\conf\ for the configuration of a stand-alone server.
The file for the client of the web service (client-side config file) is usually stored in the so-called client repository - \<Web Services Stack> folder\repository\conf.
 |
Warning: The axis2.xml file contains important information such as the user name and password for the administration console logon: |
Systems administrators must change these default credentials and protect access to the axis2.xml configuration file because the administration console is the key to many functional operations including activating and deactivating of web services.
Following are details on the HTTPS Deployment configurations performed at server side. These are the configurations for secured access to the Admin and Deploy Servlets.
If you run the Web Services Stack runtime under both HTTP and HTTPS you may also want to disable unsecured HTTP access to the Admin and Deploy Servlets. This can be done by uncommenting the two security constraints in the WEB-INF/web.xml.
The functionality of the Deploy Servlet is used in the Eclipse plug-in. For details, see Deploying and Undeploying a Web Service Package.
For details on the Admin Servlet, see Admin Servlet.
To allow access over HTTPS only
Modify the WEB-INF/web.xml file by uncommenting the following two security constraints:
<security-constraint>
<web-resource-collection>
<web-resource-name>DeployServlet</web-resource-name>
<url-pattern>/sagdeployer/*</url-pattern>
</web-resource-collection>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>
<security-constraint>
<web-resource-collection>
<web-resource-name>AxisAdminServlet</web-resource-name>
<url-pattern>/axis2-admin/*</url-pattern>
</web-resource-collection>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>
There is only one Web Services Stack-specific configuration at client side.
Following are details on how to take advantage of WS-Security by giving
a value to the parameter securityConfigFile:
<parameter name="securityConfigFile">wsclientsec.properties</parameter>
The value of the parameter in the preceding example is the relative (or absolute) path to the properties file that contains security-related information.
This file must be part of the client’s CLASSPATH.
For more information about the configuration of wsclientsec.properties file, see the heading "Client-side Configuration" from Message-Level Security.
Apache Axis 2 supports Base64 encoding, SOAP with Attachments & MTOM (SOAP Message Transmission Optimization Mechanism).
MTOM is a W3C specification that focuses on solving the "Attachments" problem.
Binary content often has to be re-encoded to be sent as text data with SOAP messages. MTOM allows you to selectively encode portions of the message. In that case, you can send base64 encoded data as well as externally attached raw binary data.
For details of MTOM, see the specification at http://www.w3.org/TR/2004/PR-soap12-mtom-20041116/.
Following are some useful configurations that you need to get use of MTOM in Web Services Stack.
The parameter <parameter
name="enableMTOM">…</parameter> can be set at all permitted
levels (global level in axis2.xml, service level in
services.xml, operation level in
services.xml, etc.). It is up to the user to decide where
to apply MTOM and to set that parameter in axis2.xml or
service.xml).
<parameter name="enableMTOM">…</parameter> can
have three different values:
"true"
If this value is set, then the engine always responds with MTOM-ized
messages in cases of included binary data of schema type "xmime:base64Binary".
For example, <xsd:element minOccurs="0" name="binaryData"
type="xmime:base64Binary"/>.
"false"
If this value is set, then the response is always non-MTOM-ized, no
matter whether the request is MOTM-ized or not.
"optional"
If this value is set, then 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.