18.1. Managing Policies

18.1.1. Introduction

The section WSIT Configuration and WS-Policy Assertions explained how WSIT functionality is configured using policies. If you are deploying a web service bundled with WSDL then all these policies are contained in the WSDL document. A web service that has no WSDL bundled will read the policies from a configuration file and then generate WSDL that contains these policies. This model works fine if you develop a few web services and do not want to share policies. NetBeans will generate the configuration with the policies for you and you do not need to be concerned with the details. Sometimes however, particularly in larger scale deployments, you will want to use the same policies for all web services or you might want to use an enterprise-wide policy. The following sections explain how to use externally defined policies.

18.1.2. Policy References

Policies are referenced using the XML element PolicyReference. Here is an example of a WSDL fragment that contains a policy and its reference:

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
             xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
             xmlns:tns="http://service.test.policy.ws.xml.sun.com/"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema"
             xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
             xmlns="http://schemas.xmlsoap.org/wsdl/"
             targetNamespace="http://service.test.policy.ws.xml.sun.com/"
             name="TestServiceService">
    ...
    <wsp:Policy wsu:Id="TestServicePortBindingPolicy"
                xmlns:wsaws="http://www.w3.org/2005/08/addressing"
                xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy">
        <wsp:ExactlyOne>
            <wsp:All>
                <wsaws:UsingAddressing xmlns:wsaws="http://www.w3.org/2006/05/addressing/wsdl"/>
                <wsrm:RMAssertion/>
            </wsp:All>
        </wsp:ExactlyOne>
    </wsp:Policy>
    ...
    <binding name="TestServicePortBinding" type="tns:TestService">
        <wsp:PolicyReference URI="#TestServicePortBindingPolicy"/>
        <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
        <operation name="echo">
            <soap:operation soapAction=""/>
            <input>
                <soap:body use="literal"/>
            </input>
            <output>
                <soap:body use="literal"/>
            </output>
        </operation>
    </binding>
    ...
</definitions>

Above you see one policy defined with the id TestServicePortBindingPolicy. This policy is referenced by the PolicyReference element in the WSDL binding section. You can see here that the policy reference #TestServicePortBindingPolicy is relative as signified by the leading # character. This is telling the policy processor that it is to look for this policy only in the enclosing document.

The mechanism of using a PolicyReference element to reference a policy is defined in WS-Policy Attachment. The PolicyReference element is a direct child element of the WSDL binding element. That effectively means that we attached the policy with id TestServicePortBindingPolicy to this particular WSDL binding element. In theory, policies could be attached to any WSDL element using that technique. In practice however, policies may only be attached to a few select elements, depending on the policy assertions that the policy contains. In the example above we have one addressing and one reliable messaging assertion. Both may only be attached to WSDL port and WSDL binding elements.

18.1.3. External Policy References

Since the PolicyReference is a URI, it comes natural to use an absolute URI instead of a relative URI. This is exactly how you would attach an external policy, i.e. a policy that is not contained in the same document as the PolicyReference. You still need to reference the policy ID by attaching it to the URI of the document. Here is an example of a file that contains the same policy as the one that was inside the WSDL document previously:

<wsp:Policy wsu:Id="TestServicePortBindingPolicy"
            xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
            xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
            xmlns:wsaws="http://www.w3.org/2005/08/addressing"
            xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy">
    <wsp:ExactlyOne>
        <wsp:All>
            <wsaws:UsingAddressing xmlns:wsaws="http://www.w3.org/2006/05/addressing/wsdl"/>
            <wsrm:RMAssertion/>
        </wsp:All>
    </wsp:ExactlyOne>
</wsp:Policy>

Let's assume the document above can be retrieved from the URI http://example.test/policy. You could now write a WSDL document like this:

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
             xmlns:tns="http://service.test.policy.ws.xml.sun.com/"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema"
             xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
             xmlns="http://schemas.xmlsoap.org/wsdl/"
             targetNamespace="http://service.test.policy.ws.xml.sun.com/"
             name="TestServiceService">
    ...
    <binding name="TestServicePortBinding" type="tns:TestService">
        <wsp:PolicyReference URI="http://example.test/policy#TestServicePortBindingPolicy"/>
        <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
        <operation name="echo">
            <soap:operation soapAction=""/>
            <input>
                <soap:body use="literal"/>
            </input>
            <output>
                <soap:body use="literal"/>
            </output>
        </operation>
    </binding>
    ...
</definitions>

Note that the PolicyReference above uses an absolute URI. It references the document URI appended with the # character and the ID of the policy. The fact that you need to state the particular ID allows to contain multiple policies inside one document and reference single policies out of that document. Here is an example of a document with more than one policy:

<?xml version="1.0" encoding="UTF-8"?>
<policies xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" 
          xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" 
          xmlns:wsoma="http://schemas.xmlsoap.org/ws/2004/09/policy/optimizedmimeserialization"
          xmlns:wsaws="http://www.w3.org/2006/05/addressing/wsdl" 
          xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy">

    <wsp:Policy wsu:Id="GlobalRMPolicy">
        <wsp:ExactlyOne>
            <wsp:All>
                <wsaws:UsingAddressing xmlns:wsaws="http://www.w3.org/2006/05/addressing/wsdl"/>
                <wsrm:RMAssertion/>
            </wsp:All>
        </wsp:ExactlyOne>
    </wsp:Policy>

    <wsp:Policy wsu:Id="GlobalMtomPolicy">
        <wsp:ExactlyOne>
            <wsp:All>
                <wsoma:OptimizedMimeSerialization/>
            </wsp:All>
        </wsp:ExactlyOne>
    </wsp:Policy>

</policies>

The policies are contained by a policies element so that this document is valid XML. This root element may actually have any name. Assuming that this document has the absolute URI http://example.test/policies, you can now create references for both policies: <PolicyReference URI="http://example.test/policies#GlobalRMPolicy"/> and <PolicyReference URI="http://example.test/policies#GlobalMtomPolicy"/>.


Terms of Use; Privacy Policy; Copyright ©2013-2014 (revision 20131025.e7cbc9d)
 
 
Close
loading
Please Confirm
Close