xdocs/0_95/WS_policy.html - axis-axis2-java-core - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
       "http://www.w3.org/TR/html4/loose.dtd">
 <html>
 <head>
   <meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
   <title>WS Policy Support in Axis2</title>
   <meta name="generator" content="amaya 9.2.1, see http://www.w3.org/Amaya/">
 </head>

 <body lang="en">
 <h1 align="center">Web Services Policy Support In Axis2</h1>

 <h2 align="center"><em>-Experimental Feature</em></h2>

 <p><em>Axis2 version 0.95</em></p>
 <i>E-mail comments/ suggestions to: <a
 href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i>

 <h2>What is Web Services (WS) Policy?</h2>

 <p>To consume non trivial web services one must fully understand its xml
 contract (WSDL) along with any other additional requirements, capabilities or
 preferences which translates to the configuration of the service, and
 essentially becomes the policies of the service.</p>

 <p>WS Policy framework provides a way to express the policies of a service in
 a machine-readable way. Web services infrastructure can be enhanced to
 understand and enforce policies at runtime. For instance, a service author
 might write a policy requiring digital signature and encryption, while
 service consumers could use the policy information to reason out whether they
 can adhere to this policy information to use the service or not.</p>

 <p>Further more, web service infrastructure could be enhanced to enforce
 those requirements without requiring the service author to write even single
 line of code.</p>

 <h2>Client Side WS-Policy Support</h2>

 <p>This release <strong>fully supports WS Policy at client-side</strong>. It
 means that when you codegen a stub against a WSLD which contains policies,
 the stub will contain the capability to engage the required modules with the
 appropriate configurations. For instance, if there is a security policy
 attached to an operation in the WSDL, the generated stub will engage the
 security module for that operation with the appropriate security
 configurations.</p>

 <h3>How it works:</h3>

 <h4>Phase 1: At PolicyEvaluator</h4>

 <p>Codegen engine runs few of its registered extensions before it generates
 the stub. When PolicyEvalutor (which is a registered Codegen extension) is
 initialized, it populates a registry of namespaces of supported policies to
 PolicyExtensions.</p>

 <p>For instance, module foo might have a mapping of namespace
 http://test.com/foo which means any primitive assertion which has this
 namespace will be processed by this module. Foo module might implement the
 ModulePolicyExtension interface through which PolicyExtension object can be
 obtained.</p>

 <p>A <strong>PolicyExtension</strong> is the access point for a module to add
 any other methods to the stub. For instance Reliable Messaging module can add
 createSequence() and endSequence() methods to the stub, that the user must
 call to start and end an RM sequence.</p>

 <p>Then at the engagement of PolicyEvaluator, effective policy of each
 operation is calculated based on policy information declared in the WSDL
 document. Here we assume that effective policy of an operation contains a
 single alternative (<strong>Multiple policy alternatives are not
 supported</strong>). Then we split that policy as follows into few other
 policies such that, each policy will contain primitive assertions belonging
 to only one namespace.</p>
 <pre>  &lt;wsp:Policy&gt;         &lt;wsp:Policy&gt;       &lt;wsp:Policy&gt;           &lt;wsp:Policy&gt;
     &lt;a:Foo/&gt;             &lt;a:Foo/&gt;           &lt;b:Foo/&gt;               &lt;c:Bar/&gt;
     &lt;a:Bar/&gt;      =&gt;     &lt;a:Bar/&gt;         &lt;/wsp:Policy&gt;          &lt;/wsp:Policy&gt;
     &lt;b:Foo/&gt;           &lt;/wsp:Policy&gt;
     &lt;c:Bar/&gt;
   &lt;/wsp:Policy&gt;</pre>

 <p>Then each policy is given to the appropriate PolicyExtension with an
 org.w3c.Element type object to which the module can append any other
 elements/attributes it wishes. Those attributes/elements should resolve to
 meaningful stub functions via PolicyExtensionTemplate.xsl at latter point of
 time.</p>

 <p>For instance depending on the policy, Security module can append
 &lt;username&gt;, &lt;passwd&gt; elements to the given element as children,
 which are later resolved into setUsername(..), setPasswd(..), functions of
 the stub. This way a module can include additional methods to the stub which
 can be used to get specific parameters to the module. These methods store any
 user input in the ServiceClient properties
 (ServiceClient.getOptions().putProperty(...)) which can later be accessed by
 the module.</p>

 <h4>Phase 2: At MultiLanguageClientEmitter</h4>

 <p>Further, effective policies (based on the WSDL) at appropriate levels
 (service level, operation level) are stored as policy strings in the stub.
 Few more generic methods are also added to the stub which are used to
 evaluate/process policies at runtime.</p>

 <h4>Phase 3: Runtime</h4>

 <p>When a new stub object is created, the policy strings in the stub are
 converted into policy objects and merged together to get the effective
 policies of each operation. These effective policies are stored in
 appropriate AxisOperation objects which a module can access at later point of
 time.</p>

 <p>Then based on its policy each AxisOperation is engaged to a set of
 modules.</p>

 <p>When the stub method is invoked, those modules which are engaged to that
 AxisOperation, access the effective policy for that operation via
 AxisOperation object. It can get other information needed from the
 MessageContext which get stored by stub methods which the module has added to
 the stub earlier. The modules are required to loads their configurations
 according to the effective policy which is set in AxisOperation and
 properties they get via MessageContext.</p>

 <h2>Server Side WS-Policy Support</h2>

 <p>In this current release Axis2 framework uses ws-commons/policy as an
 object model to manipulate policy documents. All its description builders
 store any policy information included in description documents (services.xml,
 axis2.xml, .. etc) in the appropriate description classes. This information
 is available at both deployment and run time via these description
 classes.</p>

 <p>When generating WSDL dynamically for each service, policy information in
 the description classes is included. For instance, if you declare a policy in
 axis2.xml then that policy is reflected in service elements of WSDL of every
 service. If a policy is declared in a services.xml, it is shown in the
 service element of WSDL for that particular service.</p>

 <p>Next step is to use that information to engage and configure required
 modules and allow the module to make use of this policy information.</p>

 <p>It is evident that a great deal of work is required to make axis2 a fully
 fledged ws-policy supported web service infrastructure. But it is encouraging
 to note that we've taken the first steps towards this goal. We appreciate any
 suggestions, patches etc you send us in this regard. Keep on
 contributing...!</p>
 <h2>Resources</h2>
 <ul>
 <li>Apache WS-Commons Policy Implementaion official site- <a href="http://ws.apache.org/commons/policy/index.html" target="_blank">Home Page</a></li>
 <li>Sanka Samaranayake, March 2006. <a href="" target="_blank">Web services Policy - Why, What & How</a></li>
 <li><a href="http://svn.apache.org/viewcvs.cgi/webservices/commons/modules/policy/" target="_blank">WS-commons/policy SVN</a></li>
 <li><a href="http://specs.xmlsoap.org/ws/2004/09/policy/ws-policy.pdf" target="_blank">Web
     Services Policy Framework (WS-Policy)</a></li>

 </ul>
 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
	"http://www.w3.org/TR/html4/loose.dtd">
	<html>
	<head>
	<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
	<title>WS Policy Support in Axis2</title>
	<meta name="generator" content="amaya 9.2.1, see http://www.w3.org/Amaya/">
	</head>

	<body lang="en">
	<h1 align="center">Web Services Policy Support In Axis2</h1>

	<h2 align="center"><em>-Experimental Feature</em></h2>

	<p><em>Axis2 version 0.95</em></p>
	<i>E-mail comments/ suggestions to: <a
	href="mailto:axis-dev@ws.apache.org">axis-dev@ws.apache.org</a></i>

	<h2>What is Web Services (WS) Policy?</h2>

	<p>To consume non trivial web services one must fully understand its xml
	contract (WSDL) along with any other additional requirements, capabilities or
	preferences which translates to the configuration of the service, and
	essentially becomes the policies of the service.</p>

	<p>WS Policy framework provides a way to express the policies of a service in
	a machine-readable way. Web services infrastructure can be enhanced to
	understand and enforce policies at runtime. For instance, a service author
	might write a policy requiring digital signature and encryption, while
	service consumers could use the policy information to reason out whether they
	can adhere to this policy information to use the service or not.</p>

	<p>Further more, web service infrastructure could be enhanced to enforce
	those requirements without requiring the service author to write even single
	line of code.</p>

	<h2>Client Side WS-Policy Support</h2>

	<p>This release <strong>fully supports WS Policy at client-side</strong>. It
	means that when you codegen a stub against a WSLD which contains policies,
	the stub will contain the capability to engage the required modules with the
	appropriate configurations. For instance, if there is a security policy
	attached to an operation in the WSDL, the generated stub will engage the
	security module for that operation with the appropriate security
	configurations.</p>

	<h3>How it works:</h3>

	<h4>Phase 1: At PolicyEvaluator</h4>

	<p>Codegen engine runs few of its registered extensions before it generates
	the stub. When PolicyEvalutor (which is a registered Codegen extension) is
	initialized, it populates a registry of namespaces of supported policies to
	PolicyExtensions.</p>

	<p>For instance, module foo might have a mapping of namespace
	http://test.com/foo which means any primitive assertion which has this
	namespace will be processed by this module. Foo module might implement the
	ModulePolicyExtension interface through which PolicyExtension object can be
	obtained.</p>

	<p>A <strong>PolicyExtension</strong> is the access point for a module to add
	any other methods to the stub. For instance Reliable Messaging module can add
	createSequence() and endSequence() methods to the stub, that the user must
	call to start and end an RM sequence.</p>

	<p>Then at the engagement of PolicyEvaluator, effective policy of each
	operation is calculated based on policy information declared in the WSDL
	document. Here we assume that effective policy of an operation contains a
	single alternative (<strong>Multiple policy alternatives are not
	supported</strong>). Then we split that policy as follows into few other
	policies such that, each policy will contain primitive assertions belonging
	to only one namespace.</p>
	<pre> <wsp:Policy> <wsp:Policy> <wsp:Policy> <wsp:Policy>
	<a:Foo/> <a:Foo/> <b:Foo/> <c:Bar/>
	<a:Bar/> => <a:Bar/> </wsp:Policy> </wsp:Policy>
	<b:Foo/> </wsp:Policy>
	<c:Bar/>
	</wsp:Policy></pre>

	<p>Then each policy is given to the appropriate PolicyExtension with an
	org.w3c.Element type object to which the module can append any other
	elements/attributes it wishes. Those attributes/elements should resolve to
	meaningful stub functions via PolicyExtensionTemplate.xsl at latter point of
	time.</p>

	<p>For instance depending on the policy, Security module can append
	<username>, <passwd> elements to the given element as children,
	which are later resolved into setUsername(..), setPasswd(..), functions of
	the stub. This way a module can include additional methods to the stub which
	can be used to get specific parameters to the module. These methods store any
	user input in the ServiceClient properties
	(ServiceClient.getOptions().putProperty(...)) which can later be accessed by
	the module.</p>

	<h4>Phase 2: At MultiLanguageClientEmitter</h4>

	<p>Further, effective policies (based on the WSDL) at appropriate levels
	(service level, operation level) are stored as policy strings in the stub.
	Few more generic methods are also added to the stub which are used to
	evaluate/process policies at runtime.</p>

	<h4>Phase 3: Runtime</h4>

	<p>When a new stub object is created, the policy strings in the stub are
	converted into policy objects and merged together to get the effective
	policies of each operation. These effective policies are stored in
	appropriate AxisOperation objects which a module can access at later point of
	time.</p>

	<p>Then based on its policy each AxisOperation is engaged to a set of
	modules.</p>

	<p>When the stub method is invoked, those modules which are engaged to that
	AxisOperation, access the effective policy for that operation via
	AxisOperation object. It can get other information needed from the
	MessageContext which get stored by stub methods which the module has added to
	the stub earlier. The modules are required to loads their configurations
	according to the effective policy which is set in AxisOperation and
	properties they get via MessageContext.</p>

	<h2>Server Side WS-Policy Support</h2>

	<p>In this current release Axis2 framework uses ws-commons/policy as an
	object model to manipulate policy documents. All its description builders
	store any policy information included in description documents (services.xml,
	axis2.xml, .. etc) in the appropriate description classes. This information
	is available at both deployment and run time via these description
	classes.</p>

	<p>When generating WSDL dynamically for each service, policy information in
	the description classes is included. For instance, if you declare a policy in
	axis2.xml then that policy is reflected in service elements of WSDL of every
	service. If a policy is declared in a services.xml, it is shown in the
	service element of WSDL for that particular service.</p>

	<p>Next step is to use that information to engage and configure required
	modules and allow the module to make use of this policy information.</p>

	<p>It is evident that a great deal of work is required to make axis2 a fully
	fledged ws-policy supported web service infrastructure. But it is encouraging
	to note that we've taken the first steps towards this goal. We appreciate any
	suggestions, patches etc you send us in this regard. Keep on
	contributing...!</p>
	<h2>Resources</h2>
	<ul>
	<li>Apache WS-Commons Policy Implementaion official site- <a href="http://ws.apache.org/commons/policy/index.html" target="_blank">Home Page</a></li>
	<li>Sanka Samaranayake, March 2006. <a href="" target="_blank">Web services Policy - Why, What & How</a></li>
	<li><a href="http://svn.apache.org/viewcvs.cgi/webservices/commons/modules/policy/" target="_blank">WS-commons/policy SVN</a></li>
	<li><a href="http://specs.xmlsoap.org/ws/2004/09/policy/ws-policy.pdf" target="_blank">Web
	Services Policy Framework (WS-Policy)</a></li>

	</ul>
	</body>
	</html>