You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commons-dev@ws.apache.org by sa...@apache.org on 2006/03/03 10:27:40 UTC
svn commit: r382734 - in /webservices/commons/modules/policy/doc: index.html
userguide.html
Author: sanka
Date: Fri Mar 3 01:27:38 2006
New Revision: 382734
URL: http://svn.apache.org/viewcvs?rev=382734&view=rev
Log:
Adding the introduction and the userguide documents
Added:
webservices/commons/modules/policy/doc/index.html (with props)
webservices/commons/modules/policy/doc/userguide.html (with props)
Added: webservices/commons/modules/policy/doc/index.html
URL: http://svn.apache.org/viewcvs/webservices/commons/modules/policy/doc/index.html?rev=382734&view=auto
==============================================================================
--- webservices/commons/modules/policy/doc/index.html (added)
+++ webservices/commons/modules/policy/doc/index.html Fri Mar 3 01:27:38 2006
@@ -0,0 +1,117 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
+ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+ <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
+ <meta content="text/html; charset=iso-8859-1" />
+ <title>Welcome to WS Policy</title>
+ <meta name="generator" content="amaya 9.2.1, see http://www.w3.org/Amaya/"
+ />
+</head>
+
+<body>
+<h1>Welcome to Apache Web Services (WS) Policy</h1>
+
+<h4>- Version 0.90 Release</h4>
+
+<h2>Introduction</h2>
+
+<p>WS-Commons/Policy provides an implementation of WS-Policy specification.
+It provides a convenient model to process any policy information at runtime.
+In other words, it allows you to convert any policy to an object (which is
+its runtime representation) and play with it as you like. You could normalize
+it and then print it if you want to convert your original policy into a
+standard format. Else you could merge or intersect that policy object with
+another policy object and print it to see how the merge / or intersect looks
+like.</p>
+
+<p><strong>WS-Policy specification</strong> define <a
+href="#operations">policy operations</a> to manipulate policies.
+WS-Commons/Policy framework support all these operations which are extremely
+useful when trying to do complex policy manipulations</p>
+
+<h3>What is WS-Policy?</h3>
+
+<p>A <strong>WS-policy</strong> is a set of requirements that have to be met
+in order to consume a web service.</p>
+
+<p>A requirement can be domain specific. For instance, if your policy demands
+that you need security token type, then its a primitive requirement.
+<strong>PrimtiveAssertion</strong> class represents such requirements in
+<strong>Commons/Policy framework</strong>.</p>
+
+<p>Another requirement would be to meet several assertions in a certain way.
+For instance, an assertion would require all its child assertions be met
+while another assertion may require exactly one of its child assertions be
+met. Such assertions are known as <strong>CompositeAssertions</strong>. If
+assertion implements CompositeAssertion marker-interface, it's an indication
+that this assertion is of CompositeAssertion type. For instance
+AndCompositeAssertion, XorCompositeAssertion and Policy are of
+CompositeAssertion type.</p>
+
+<p>If you consider the <strong>AndCompositeAssertion</strong> it requires all
+its child terms be met. If its <strong>XorCompositeAssertion</strong> type,
+it requires that exactly one of its child terms be met. Both Policy and
+AndCompositeAssertion requires same behavior except that in
+<strong>Policy</strong>, policy object is the outer most element.</p>
+<a name="operations"></a>
+<h3>Policy Operations</h3>
+
+<p>The object model in WS-Commons/Policy becomes very handy when it comes to
+<strong>policy operation</strong>s. For instance you could invoke normalize()
+method on a policy object which will return a new policy object which has the
+same implication, but in a standard format.</p>
+
+<p>If you merge a policy object with another policy object it will return a
+new policy object which represents the merged policies of those two objects.
+If you could satisfy any policy alternative available in the resultant
+object, it is guaranteed that at least one policy alternative of both policy
+objects could be met.</p>
+
+<p>One interesting application of policies would be to identify which policy
+alternatives that both parties can agree upon. The simple solution is to
+intersect the two policy objects and get the resultant policy object. It
+would contain all possible policy alternatives that both parties agree
+upon.</p>
+
+<p>Commons/Policy framework is now reaching its maturity. It is used in other
+web services projects like Axis2, Sandehsa2 and WSS4J to process any policy
+information they require. Recently it passed all the WS Policy Interop Round1
+which is aimed to test the correctness of object model. And it seems safe to
+say that bright future is ahead.</p>
+
+<p>You can learn how to use Apache WS-Policy by checking out our <a href="userguide.html" target="_blank">User's Guide</a>
+</p>
+
+<h2>Key Features</h2>
+<ol>
+ <li>Fully compliant with latest WS-Policy Specification</li>
+ <li>Passes WS-Policy Interop ROUND1 Test Suite</li>
+</ol>
+
+<h2>Resources</h2>
+<ul>
+ <li><a
+ href="https://svn.apache.org/repos/asf/webservices/commons/modules/policy/" target="_blank">ws-commons/policy</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>
+ <li>Samaranayake, Sanka. January 2006. <a
+ href="http://www.wso2.net/2006/01/web_services_policy_why_what_how" target="_blank">Web
+ services Policy - Why, What & How.</a></li>
+</ul>
+<!--Remove when docs are published on site-->
+<a name="mailing"></a>
+<h2>Mailing List</h2>
+
+<p>Developer List- <a
+href="mailto:commons-dev-subscribe@ws.apache.org?subject=subscribe">Subscribe</a>
+| <a
+href="mailto:commons-dev-unsubscribe@ws.apache.org?subject=unsubscribe">Unsubscribe</a></p>
+
+<p>Once subscribed to the developer mailing list you can send your feedback
+to : <a href="mailto:commons-dev@ws.apache.org?subject=[WS-Policy]">commons-dev@ws.apache.org</a>
+(Prefix the subject with [Policy])</p>
+<!--<p>User List- Subscribe | Unsubscribe | Archive</p>-->
+</body>
+</html>
Propchange: webservices/commons/modules/policy/doc/index.html
------------------------------------------------------------------------------
svn:executable = *
Added: webservices/commons/modules/policy/doc/userguide.html
URL: http://svn.apache.org/viewcvs/webservices/commons/modules/policy/doc/userguide.html?rev=382734&view=auto
==============================================================================
--- webservices/commons/modules/policy/doc/userguide.html (added)
+++ webservices/commons/modules/policy/doc/userguide.html Fri Mar 3 01:27:38 2006
@@ -0,0 +1,157 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
+ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+ <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
+ <title>WS Policy User's Guide</title>
+ <meta name="generator" content="amaya 9.2.1, see http://www.w3.org/Amaya/"
+ />
+</head>
+
+<body xml:lang="en">
+<h1>Apache Web Services Policy User's Guide:</h1>
+
+<h4>- Version 0.90 Release</h4>
+
+<p>This document will instruct you how to use WS-Policy model, taking you
+step by step through the process using a simple sample.</p>
+
+<p>Send your feedback to: <a
+href="mailto:commons-dev@ws.apache.org">commons-dev@ws.apache.org</a> (Prefix
+the subject with [Policy])</p>
+<p>To subscribe to developer mailing list see <a href="index.html#mailing">here</a></p>
+
+<h2>Content</h2>
+<ol>
+ <li><a href="#create">Create a policy object</a>
+ <ul>
+ <li><a href="#policydoc">Create a policy object by reading a policy document</a>
+ <ul>
+ <li><a href="#policyreader">How to create a PolicyReader</a></li>
+ <li><a href="#feedpolicydoc">Feed the policy document to PolicyReader as an
+ inputStream</a></li>
+ </ul>
+ </li>
+ <li><a href="#program">Create a policy object programmatically.</a></li>
+ </ul>
+ </li>
+ <li><a href="#write">Write a policy object</a></li>
+ <li><a href="#normalize">Normalization</a></li>
+ <li><a href="#merge">Merge policy objects</a></li>
+ <li><a href="#intersect">Intersect policy objects</a></li>
+</ol>
+<a name="create"></a>
+<h2>Create a policy object</h2>
+
+<p>You can create a policy obejct using one of the following two methods</p>
+<ol>
+ <li><a href="#policydoc">Create a policy object by redaing a policy document</a></li>
+ <li><a href="#program">Create a policy object programmatically</a></li>
+</ol>
+<a name="policydoc"></a>
+<h3>Create a policy object by reading a policy document</h3>
+
+<p>The following steps need to be taken to create a policy object from a
+policy document</p>
+<ol>
+ <li><a href="#policyreader">Create a PolicyReader</a> - This is the class that creates a policy object
+ using an InputStream.</li>
+ <li><a href="#feedpolicydoc">Feed the policy document to PolicyReader as an InputStream</a>-This will
+ return a policy object</li>
+</ol>
+<a name="policyreader"></a>
+<h4>1. How to create a PolicyReader</h4>
+<p>PolicyReader is the class that creates a policy object using an
+InputStream.</p>
+<pre>PolicyReader reader =
+PolicyFactory.getPolicyReader(PolicyFactory.OM_POLICY_READER);
+
+// or
+
+PolicyReader reader =
+PolicyFactory.getPolicyReader(PolicyFactory.DOM_POLICY_READER);</pre>
+<a name="feedpolicydoc"></a>
+<h4>2. Feed the policy document to PolicyReader as an InputStream.</h4>
+
+<p>This step will return a policy object.</p>
+<pre>String pathToPolicyFile = " /home/ ../Policy1.xml";
+
+FileInputStream fis = new FileInputStream(pathToPolicyFile);
+
+Policy policy = reader.readPolicy(fis);</pre>
+<a name="program"></a>
+<h3>Create a policy object programmatically.</h3>
+<a name="policy"></a>
+<p>Lets consider the sample policy below.</p>
+<pre><wsp:Policy>
+ <wsp:ExactlyOne> // Corresponds to XorCompositeAssertion
+ <wsp:All> // Corresponds to AndCompositeAssertion
+ <ns1:TestAssertion>
+ TestAssertion1
+ </ns:TestAssertion>
+ </wsp:All>
+ </wsp:ExactlyOne>
+</wsp:Policy></pre>
+
+<p>Now lets create programmatically the policy object which represents the
+above policy</p>
+<pre>Policy p = new Policy(); // will give you the following element
+
+<wsp:Policy> </wsp:Policy>
+
+XorCompositeAssertion x1 = new XorCompositeAssertion();
+p.addTerm(x1); //will give you XorCompositeAssertion as seen below
+
+<wsp:Policy>
+<wsp:ExactlyOne>....</wsp:ExactlyOne>
+</wsp:Policy>
+
+AndCompositeAssertion a1 = new AndCompositeAssertion();
+x1.addTerm(a1);// will give you AndCompositeAssertion as seen below
+
+<wsp:Policy>
+<wsp:ExactlyOne>
+<wsp:All>...</wsp:All>
+</wsp:ExactlyOne>
+</wsp:Policy>
+
+QName name = new QName("Test", "http://tests.org/tests", "ns1");
+PrimitiveAssertion prim1 = new PrimitiveAssertion(name);
+prim1.setStrValue("MyTestAssertion");
+a1.addTerm(prim1); //will give you the <a href="#policy">complete policy</a></pre>
+<a name="write"></a>
+<h2>Write a policy object</h2>
+<p>The following code will achieve this task</p>
+<pre>String pathToOutFile = "/home/... /Policy2.xml";
+
+FileOutputStream fos = new FileOutputStream(pathToOutFile);
+
+PolicyWriter writer =
+PolicyFactory.getPolicyWriter(PolicyFactory.StAX_POLICY_WRITER);
+
+writer.writePolicy(policy, fos );</pre>
+<a name="normalize"></a>
+<h2>Normalization</h2>
+<p>The following code will achieve policy normalization</p>
+<pre>Policy policy1 = reader.readPolicy(...);
+
+Policy normalized = (Policy) policy1.normalize();</pre>
+<a name="merge"></a>
+<h2>Merge policy objects</h2>
+<p>The following code will merge two policy objects</p>
+<pre>Policy policy1 = reader.readPolicy(...);
+
+Policy policy2 = reader.readPolicy(...);
+
+Policy merged = (Policy) policy1.merge(policy2);</pre>
+<a name="intersect"></a>
+<h2>Intersect policy objects</h2>
+<p>The following code will intersect two policy objects</p>
+<pre>Policy policy1 = reader.readPolicy(..)
+
+Policy policy2 = reader.readPolicy(..)
+
+Policy intersected = (Policy) policy1.intersect(policy2);</pre>
+</body>
+</html>
Propchange: webservices/commons/modules/policy/doc/userguide.html
------------------------------------------------------------------------------
svn:executable = *