JBossWS policy support rely on the Apache CXF WS-Policy framework, which is compliant with the Web Services Policy 1.5 - Framework and Web Services Policy 1.5 - Attachment specifications.
Users can work with policies in different ways:
- by adding policy assertions to wsdl contracts and letting the runtime consume them and behave accordingly;
- by specifying endpoint policy attachments using either CXF annotations or features.
Of course users can also make direct use of the Apache CXF policy framework, defining custom assertions, etc.
Finally, JBossWS provides some additional annotations for simplified policy attachment.
WS-Policies can be attached and referenced in wsdl elements (the specifications describe all possible alternatives). Apache CXF automatically recognizes, reads and uses policies defined in the wsdl.
Users should hence develop endpoints using the contract-first approach, that is explicitly providing the contract for their services. Here is a excerpt taken from a wsdl including a WS-Addressing policy:
Of course, CXF also acts upon policies specified in wsdl documents consumed on client side.
For those preferring code-first (java-first) endpoint development, Apache CXF comes with org.apache.cxf.annotations.Policy and org.apache.cxf.annotations.Policies annotations to be used for attaching policy fragments to the wsdl generated at deploy time.
Here is an example of a code-first endpoint including @Policy annotation:
The referenced descriptor is to be added to the deployment and will include the policy to be attached; the attachment position in the contracts is defined through the placement attribute. Here is a descriptor example:
Both approaches above require users to actually write their policies' assertions; while this offer great flexibility and control of the actual contract, providing the assertions might end up being quite a challenging task for complex policies. For this reason, the JBossWS integration provides policy sets, which are basically pre-defined groups of policy assertions corresponding to well known / common needs. Each set has a label allowing users to specify it in the @org.jboss.ws.api.annotation.PolicySets annotation to have the policy assertions for that set attached to the annotated endpoint. Multiple labels can also be specified. Here is an example of the @PolicySets annotation on a service endpoint interface:
The three sets specified in @PolicySets will cause the wsdl generated for the endpoint having this interface to be enriched with some policy assertions for WS-RM, WS-Security and WS-Addressing.
The labels' list of known sets is stored in the META-INF/policies/org.jboss.wsf.stack.cxf.extensions.policy.PolicyAttachmentStore file within the jbossws-cxf-client.jar (org.jboss.ws.cxf:jbossws-cxf-client maven artifact). Actual policy fragments for each set are also stored in the same artifact at META-INF/policies/<set-label>-<attachment-position>.xml.
Here is a list of the available policy sets:
|WS-Addressing||Basic WS-Addressing policy|
||The basic WS-RM policy example in the WS-RM specification|
|WS-SP-EX2121_SSL_UT_Supporting_Token|| The group of policy assertions used in the section 188.8.131.52 example of the WS-Security Policy Examples 1.0 specification
|| The group of policy assertions used in the section 2.1.3 example of the WS-Security Policy Examples 1.0 specification
|| The group of policy assertions used in the section 2.1.4 example of the WS-Security Policy Examples 1.0 specification
||The group of policy assertions used in the section 2.2.1 example of the WS-Security Policy Examples 1.0 specification|
|| The group of policy assertions used in the section 2.2.2 example of the WS-Security Policy Examples 1.0 specification
|| The group of policy assertions used in the section 2.2.3 example of the WS-Security Policy Examples 1.0 specification
|| The group of policy assertions used in the section 2.2.4 example of the WS-Security Policy Examples 1.0 specification
||A WS-Security policy for asymmetric binding (encrypt before signing) using X.509v1 tokens, 3DES + RSA 1.5 algorithms and with token protections enabled|
||The same as before, but using custom Apache CXF algorithm suite including GCM 256 + RSA OAEP algorithms|
|Always verify the contents of the generated wsdl contract, as policy sets are potentially subject to updates between JBossWS releases. This is especially important when dealing with security related policies; the provided sets are to be considered as convenient configuration options only; users remain responsible for the policies in their contracts.|
|The org.jboss.wsf.stack.cxf.extensions.policy.Constants interface has convenient String constants for the available policy set labels.|
|If you feel a new set should be added, just propose it by writing the user forum!|