理解axis2的addressing

Apache Axis supports the two widely used versions of WS-AddressingSpecifications, namely: WS-Addressing Final and Submission.

Applies ToApache Axis2/Java1.2Introduction

The Axis2 release comes with an implementation of the WS-AddressingFinal and Submission versions [1]. These implementations have been tested in numerousinteroperability sessions in the past, and have been part of Axis2 since theinception of Axis2.

Axis2 uses a similar addressing model internally as proposed in theWS-Addressing final specification. The model is meant to capture addressinginformation, in general, to a "bag" within its engine. These properties canalso be populated by transport processors, service authors, etc. This makesAxis2 work smoothly even if the WS-Addressing implementation is disabled atruntime for legacy reasons.

First let's look at how addressing processing works inside Axis2.

How Axis2 Processes WS-Addressing Headers

The main task of the Axis2 engine is to process incoming and outgoing SOAPmessages. When it receives or sends SOAP messages, it creates an instance ofMessageContext to keep track of all the information related to that message.This MessageContext includes the SOAP message just received or about to besent, and might also reference the other SOAP messages related to thismessage exchange pattern [2].

The message context also encapsulates various meta-data about the messageand also some information relevant to the processing of the message. TheMessageContext object also has properties that capture addressing relatedproperties like where this message came from, the destination URL, etc., Thisinformation is independent from WS-Addressing specification details. Thisinformation is mostly captured from the specific transport receivers. Forexample, if the transport used is HTTP, then the HTTP transport listener(either AxisServlet or SimpleHTTPServer) copies the URL, SOAP action (ifavailable), content type header, etc., If you look at this addressing modelcarefully, you will see that it is almost similar to the WS-Addressing modeldefined in the specification; yet the model can capture information from thesource other than WS-Addressing headers.

All the handlers, control logic and message receivers, (message receiversare responsible for taking care of the respective message exchange pattern inuse and to hand over the message to the Web service implementation) extractaddressing properties from the message context, irrespective of whether theycome from transport, WS-Addressing implementation or any other means. So thisbag of properties can be regarded as a WS-Addressing neutral set ofproperties.

The WS-Addressing implementation comes with every Axis2 release bundledwithin the Axis2 release itself. This WS-Addressing implementation is amodule in Axis2. So you should be able to see addressing-<version>.marinside the release. If you need to use WS-Addressing, you need to engage theWS-Addressing module. (Please refer to the Axis2 user guide for moreinformation on engaging modules.)

When we engage WS-Addressing to the message path, the WS-Addressing moduleadds a couple of handlers to the IN path and also to the OUT path of themessage processing. The addressing handlers deployed in the IN path,Addressing "IN" Handlers, read WS-Addressing information from the incomingmessage and populate the above discussed addressing properties. (If there arevalues already inside some of these properties, WS-Addressing simplyoverrides them). Addressing "IN" handlers have the capability to detect theWS-Addressing version used inside the SOAP message and process themaccordingly.

Likewise, Addressing handlers in the OUT path, take out the addressingproperties from the message context and populate the out going SOAP messagewith them.

This is how the Axis2 engine understands WS-Addressing information withinSOAP messages. However, WS-Addressing integration does not end at this point.The Axis2 engine has all the rules defined by WS-Addressing implementedinternally. For example, the rules defined to handle SOAP faults, are handledwithin the proper locations of the Axis2 engine according to theWS-Addressing rules. So you might argue that WS-Addressing is already builtinto it. What WS-Addressing module provides is just the option ofunderstanding the WS-Addressing header in SOAP messages.

Let's see how you can access WS-Addressing properties. You do not have toworry about accessing the SOAP message to get or set addressing information.The already mentioned property bag within the MessageContext object will haveconvenient methods that will provide the required functionality. For example,if you need to retrieve the value of the WS-Addressing To header, simply callmessageContext.getTo(). Likewise, if you want to change the value of the Toheader, use messageContext.setTo(EndpointReference). This EndpointReferenceclass resembles the EndpointReference defined within the WS-Addressingspecification. You can set the address, set reference parameters, etc., usingthe EndpointReference class.

Once you engage the WS-Addressing module, the engine will useWS-Addressing within the engine. You are not required to configure anythingto make it run. However, there are some configuration options available ifyou want more control over how it works. Having understood how theWS-Addressing implementation works within Axis2, let's see how we can tweaksome of the processing of addressing handlers within Axis2.

Tweaking Addressing Processing

There are some properties you can set, using the API you are dealing with,to change the behavior of addressing handlers. If you are writing a client,use either ServiceClient API or your stub API. If you are a service author,then you need to set these properties to the message context. The followingitems use examples to demonstrate how these properties can be set usingOptions API. Let's see what these properties are and what they change.

DISABLE_ADDRESSING_FOR_OUT_MESSAGES

When you send out SOAP messages and if WS-Addressing is engaged, then italways sends out WS-Addressing headers inside the SOAP messages. There can betimes you might not wish to include WS-Addressing headers only for a selectedset of outgoing messages. For example, if you have a legacy Web serviceimplementation, you can use Axis2 to process WS-Addressing headers andforward the message without those headers. In that case, what you have to dois to set DISABLE_ADDRESSING_FOR_OUT_MESSAGES to the message context or tothe Options object that you have.

 options.setProperty(DISABLE_ADDRESSING_FOR_OUT_MESSAGES, Boolean.TRUE);

WS_ADDRESSING_VERSION

As mentioned earlier, Axis2 supports two addressing versions. Namely:Final and Submission versions [1] . You can use any ofthese versions within Axis2. The WS_ADDRESSING_VERSION property can be usedto inform the Axis2 engine about the addressing version that you areinterested in using. For example, if you want to use the WS-Addressingsubmission version, set WS_ADDRESSING_VERSION toorg.apache.axis2.addressing.AddressingConstants.Submission.WSA_NAMESPACE.

If you want to use WS-Addressing final version then set it toorg.apache.axis2.addressing.AddressingConstants.Final.WSA_NAMESPACE

 options.setProperty(WS_ADDRESSING_VERSION, org.apache.axis2.addressing.AddressingConstants.Final.WSA_NAMESPACE);

INCLUDE_OPTIONAL_HEADERS

The WS-Addressing specification defines a set of EPRs to be includedinside the SOAP message if WS-Addressing is enabled. Some of these headersare optional. For example, the destination URL (To address) and the actionparameters are required while the others are optional. The Axis2WS-Addressing implementation adds only the required headers by default, ifWS-Addressing is engaged. If you want to include the optional headers aswell, then you need to set the INCLUDE_OPTIONAL_HEADERS property to ask Axis2to include those headers also.

 options.setProperty(INCLUDE_OPTIONAL_HEADERS, Boolean.TRUE);

REPLACE_ADDRESSING_HEADERS

As I mentioned earlier, WS-Addressing Out Handlers are responsible fortaking out addressing information from the message context and putting theminto the outgoing SOAP message. There can be situations where the outgoingmessage might already have addressing headers. For example, if the currentAxis2 node is just an intermediary or a message mediation node, then it willbe passing the same message to the outgoing path as well. Therefore, theoutgoing message has addressing headers in it by the time it comes to theaddressing out handler. The nodes tend to remove any existing headers, andthen add the new headers. If we add the same headers twice then it might notbe correct. If the REPLACE_ADDRESSING_HEADERS property is set to True, thenthe addressing handlers will remove any existing headers if present, beforeadding the new ones.

 options.setProperty(REPLACE_ADDRESSING_HEADERS, Boolean.TRUE);

ADDR_VALIDATE_ACTION

Axis2 finds the service and the operation a SOAP message is destined towithin the dispatch phase. (Refer to the article How Apache Axis2 Finds theOperation and Service a Message is Destined to [3] to knowmore about how dispatching works.) If Axis2 cannot find the operation amessage is destined to, then the user should be notified about this. IfWS-Addressing is engaged, then the WS-Addressing specification is defined tothrow an ActionNotSupported Fault to the user. However, sometimes, usersmight need to suppress this behaviour (there are scenarios for this in theApache Synapse project). Setting ADDR_VALIDATE_ACTION to False will suppressAddressing handlers from sending the ActionNotSupported fault to the user.

 options.setProperty(ADDR_VALIDATE_ACTION, Boolean.TRUE);

Summary

WS-Addressing is a key specification in today's Web services stacks. Withthe popularity and wide spread adoption of asynchronous invocations, theimportance of WS-Addressing has increased. This article illustrated how thisimportant specification is implemented within the pioneering open source Webservices engine in Apache Axis2. The parameter configuration section alsodescribed how you can gain control to some extent over this process.

References

WS-Addressing Specifications : Final SubmissionUnderstanding Message ExchangePatternsHow Apache Axis2 Finds theOperation and Service a Message is Destined To