Skip navigation links

oracle.wsm.policy.model
Interface IAssertion

All Superinterfaces:

Serializable

public interface IAssertion

extends Serializable

What is an Assertion?
An Assertion is any XML element that is a child of <wsp:Policy>, <wsp:All> or <wsp:ExactlyOne>
How does an Assertion differ from an XML element?

1. Not all XML elements in a XML document are assertions.
2. An Assertion has special semantics in that it participates in the intersection algorithm defined by WS-Policy.
3. The default intersection is based on the QName of the Assertion

IAssertion is the base interface which all constructs of WS-Policy must implement. It defines few policy operations that all policy constructs must support. If certain operations are not supported then they must throw an UnSupportedOperationException.
The Policy Object Model defines various types of Assertions - the following types of Assertions are the most important ones.

1. Simple Assertions oracle.wsm.policy.model.ISimpleAssertion
2. MultiElement Simple Assertions oracle.wsm.policy.model.IMultiElementSimpleAssertion
3. Nested Assertions oracle.wsm.policy.model.INestedAssertion
4. Composite Assertions oracle.wsm.policy.model.ICompositeAssertion
5. Scenario Assertions oracle.wsm.policy.model.IScenarioAssertion
6. Step Scenario Assertions com.cfluent.policymanager.sdk.policy.IStepScenarioAssertion
7. Policy oracle.wsm.policy.model.IPolicy
8. PolicyReference oracle.wsm.policy.model.IPolicyReference

Simple Assertion
A SimpleAssertion cannot contain other assertions. A Simple Assertion maps to an org.w3c.dom.Element which does not have any nested elements except for extensions defined by Oracle. ISimpleOracleAssertion for extensions defined by Oracle.
Contraint:

1. Cannot contain nested elements other than Oracle Extension element <orawsp:bindings>
2. Cannot contain other assertions

The pseudo-schema for Simple Assertions is as follows:
<Assertion>
[ wsp:Optional="xsd:boolean" ]?
[ orawsp:Silent="xsd:boolean" ]?
[ orawsp:Enforced="xsd:boolean" ]?
[ orawsp:description="xsd:string" ]?
[ orawsp:category="xsd:string" ]?...>
<orawsp:bindings>?
</Assertion>
Examples of Simple Assertions:
Example #1:
<mya:myAssertion orawsp:Silent="true".../>
Example #2:
<oralgp:Logging orawsp:Silent="true" orawsp:Enforced="true"...>
<orawsp:bindings>
<orawsp:Implementation>...</orawsp:Implementation>
<orawsp:Config orawsp:name="LogConfig" orawsp:type="logging">
<orawsp:PropertySet orawsp:name="log_properties" type="string">
<orawsp:Property orawsp:name="level" type="string">
<orawsp:Description>...</orawsp:Description>
<orawsp:Value>...</orawsp:Value>
</orawsp:Property>
...
<orawsp:PropertySet>
</orawsp:bindings>
</oralgp:Logging>

Multi-Element Simple Assertion
A Multi-Element SimpleAssertion cannot contain other assertions. A Muli-Element Simple Assertion maps to an org.w3c.dom.Element which has nested XML elements and extension elements defined by Oracle. See ISimpleOracleAssertion for extensions defined by Oracle.
Contraint:

1. Can contain nested XML elements other than Oracle Extension element <orawsp:bindings>
2. Cannot contain other assertions. Unless domain specific intersection semantics are defined, the nested XML elements do not participate in the intersection.

The pseudo-schema for Mulit-Element Assertion is as follows:
<Assertion>
[ wsp:Optional="xsd:boolean" ]?
[ orawsp:Silent="xsd:boolean" ]?
[ orawsp:Enforced="xsd:boolean" ]?
[ orawsp:description="xsd:string" ]?
[ orawsp:category="xsd:string" ]?...>
<other-xml-elements>+
<orawsp:bindings>?
</Assertion>
Examples of Multi-Element Assertions:
Example #1:
<sp:SignedParts ...> <sp:Body/> </sp:SignedParts>
Example #2 with bindings:
<sp:SignedParts ...> <sp:Body/>
<orawsp:bindings>
<orawsp:Implementation>...</orawsp:Implementation>
<orawsp:Config orawsp:name="some_configuration" orawsp:type="security">
<orawsp:PropertySet orawsp:name="msg_protection" type="string">
<orawsp:Property orawsp:>
<orawsp:Description>...</orawsp:Description>
<orawsp:Value>...</orawsp:Value>
</orawsp:Property>
...
</orawsp:PropertySet>
</orawsp:bindings>
</sp:SignedParts>

Nested Assertion
A NestedAssertion can contain other assertions, but in order to do so it must follow the rules defined by WS-Policy in defining nested assertions. Many assertions defined in the WS-SecurityPolicy spec fall into this category.
Contraint:

1. Can contain one child Policy XML element.
2. Can contains other assertions. In order for a Nested Assertion to contain other assertions they must be wrapped within a <wsp:Policy> element.
3. Can contain other child elements including the Oracle Extension element <orawsp:bindings> .
4. Non-assertion child elements do not participate in intersection.
5. All assertion that are contained by a Nested Assertion will participate in the intersection - unless domain dependent intersection semantics are defined.

Example:
<sp:RecipientToken> <!-- Nested Assertion -->
<wsp:Policy> <!-- Composite Assertion -->
<sp:X509Token sp:IncludeToken='http://schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/Never'> <!-- Nested Assertion -->
<wsp:Policy> <!-- Composite Assertion -->
<sp:WssX509V3Token10 /> <!-- Nested Assertion -->
</wsp:Policy>
</sp:X509Token>
</wsp:Policy>
</sp:RecipientToken>
Constraint:

1. In order for a Nested Assertion to contain other assertions they must be wrapped within a wsp:Policy element.

The pseudo-schema for Nested Assertions is as follows:
<Assertion ...>
<other-xml-elements>*
<wsp:Policy>
...
</wsp:Policy>
<other-xml-elements>*
</Assertion>

Composite Assertion
A Composite Assertion represents operators defined by WS-Policy like wsp:ExactlyOne, wsp:All, etc and extensions defined by Oracle.
Scenario Assertion
A Scenario Assertion represents a particular use-case the developer is trying to address. A Scenario Assertion is similar to a Multi-Element Simple Assertion. Scenario Assertions capture use-cases where these can be converted to assertions that may be defined and standardized as part of standardization efforts.
The pseudo-schema for a Scenario Assertion is as follows:
<Assertion...>
<other-xml-elements>*
<orawsp:bindings>?
</Assertion>
Step Scenario Assertion
This is a deprecated Assertion and is provided mainly for backward compatibility.
A Step Scenario Assertion is similar to Scenario Assertions in that these assertions can be converted to assertions that may be defined as part of standards.
The main difference b/w a Step Scenario Assertion and a Scenario Asssertion is that the schema is fixed for a Step Scenario Assertion.
The pseudo-schema for a Step Scenario Assertion is as follows:
<Assertion...>
<Property>*
<orawsp:bindings>?
</Assertion>

Introducing a Custom Assertion in the Policy Object Model?
The Policy Object Model and the Policy Framework places the following constraints!

• You cannot introduce new Composite Assertion!
• Most Custom Assertions should fall into the following 3 categories
  • Simple Assertion
  • Nested Assertion
  • Scenario Assertion

Introducing Custom Simple Assertions
In most cases you won't need a Class for Custom Simple Assertions! A good example of this is the Logging Assertion shown in the example above. In this case the Policy Framework will use the "Default" Serializer/De-Serializer and will use the default Implementation class for all Simple Assertions.
If you decide to introduce a new Class then it must extend the base class SimpleAssertion and <method>getAssertionType()</method> must return the appropriate value.
Even if you introduce a new Class - you do not have to write Serializer/De-Serializer for it.
You just need to add the following entry into the policy configuration file.
<entry>
<key
namespace="http://schemas.oracle.com/ws/2006/01/loggingpolicy"
elementname="Logging">
</key>
<assertionClass>fully qualified class name</assertionClass>
</entry>
Introducing Custom Scenario Assertions
The majority of the Custom Assertions fall into this category.
To define a Custom Scenario Assertion you need to introduce a Class that extends oracle.wsm.policy.model.impl.ScenarioAssertion
You also need to define Serializers/De-Serializers for Custom Scenario Assertions.
Example: TODO
Introducing Custom Nested Assertions
The Policy Object Model places a few constraints on developers introducing Custom Nested Assertions.
You will want to introduce a Class to represent the Nested Assertion and provide some domain specific methods on this class.
Custom Nested Assertions must extend the oracle.wsm.policy.model.impl.NestedAssertion class.
Example:
The oracle.wsm.policy.model.impl.security.RecipientTokenAssertion class defines additional methods like <method>getRecipientToken()</method>
WARNING: A Custom Nested Assertion will contain other assertions but the Custom Nested Assertion Class must not maintain the Assertion list in an instance variable; instead it must call the appropriate super methods defined on the class oracle.wsm.policy.model.impl.NestedAssertion
This constraint is required as the base class provides the default implementation of normalization, intersection, merge requirements on Nested Assertions specified by the WS-Policy family of specifications.
Note: It is the responsibility of the Custom Nested Assertion developer to ensure the pseudo-schema for Nested Assertions is followed.
Serialization/DeSerialization to/from XML:<b/>
The "Default" Serializer/DeSerializer can address serialization/de-serialization for Nested Assertions, Simple Assertions, Multi-Element assertions.
Scenario Assertions<b/>
Scenario Assertion developers are required provide serialization/de-serialization implementation.
Scenario Assertion developers can use JAXB and other tools for serialization/de-serialization purposes.

Nested Class Summary

static interface

IAssertion.AssertionTypes

Method Summary

void	addAttribute(QName qname, String value)
IAssertion	createInstance(QName qname) Creates the appropriate assertion instance NOTE: The base implementation must be overriden by the subclasses!
int	getAssertionType() Returns the type of the assertion.
String	getAttribute(QName qname)
Map<QName,String>	getAttributes()
String	getDigest() Create a unique string representation that identifies this policy uniquely independent of the order of the assertions to enable a fast path intersection with another policy
String	getDigest(List<String> namespaces, List<QName> qnames, boolean inclusionOrExclusionCriteria) Create a unique string representation that identifies this policy uniquely independent of the order of the assertions to enable a fast path intersection with another policy.
IAssertion	getParent() Returns the parent of self or null if a parent non-exists
QName	getQName()
String	getStringForMatching() The String to be used in the matching algorithim (used for intersection, merge, etc).
boolean	hasParent() Returns ture if the assertion has a parent
IAssertion	intersect(IAssertion assertion, IIntersectionContext context) Returns an assertion which is the equivalent of intersect of self and argument.
IAssertion	intersect(IAssertion assertion, IPolicyRegistry reg, IIntersectionContext context) Returns an assertion which is equivalent of intersect of self and argument.
boolean	isIdentical(Object obj)
boolean	isNormalized() Returns true if the Assertion has been normalized.
boolean	isOptional() Returns true if the Assertion is optional.
IAssertion	merge(IAssertion assertion) Returns the equivalent of merge of self and argument.
IAssertion	merge(IAssertion assertion, IPolicyRegistry reg) Returns the equivalent of merge of self and argument.
IAssertion	normalize() Normalizes the assertion and returns the normalized Assertion
IAssertion	normalize(IPolicyRegistry reg)
void	removeAttribute(QName qname)
void	setAttributes(Map<QName,String> attributeMap)
void	setNormalized(boolean flag) WARNING: Do not call this method.
void	setOptional(boolean isOptional) Specifies if the Assertion is optional.
void	setParent(IAssertion parent) Set the parent to argument
void	validate(IValidationContext context) Validate this assertion If any errors are found, they are added to the passed Validation Context object

Method Detail

hasParent

boolean hasParent()

Returns ture if the assertion has a parent

Returns:

true if a parent exists , false otherwise

getParent

IAssertion getParent()

Returns the parent of self or null if a parent non-exists

Returns:

the parent of self

setParent

void setParent(IAssertion parent)

Set the parent to argument

Parameters:

parent - the parent that should be parent of self

getQName

QName getQName()

getAssertionType

int getAssertionType()

Returns the type of the assertion.

setAttributes

void setAttributes(Map<QName,String> attributeMap)

getAttribute

String getAttribute(QName qname)

addAttribute

void addAttribute(QName qname,
                  String value)

removeAttribute

void removeAttribute(QName qname)

getAttributes

Map<QName,String> getAttributes()

normalize

IAssertion normalize()
                     throws UnsupportedOperationException

Normalizes the assertion and returns the normalized Assertion

Returns:

Throws:

UnsupportedOperationException

normalize

IAssertion normalize(IPolicyRegistry reg)
                     throws UnsupportedOperationException

Parameters:

reg -

Returns:

Throws:

UnsupportedOperationException

intersect

IAssertion intersect(IAssertion assertion,
                     IIntersectionContext context)
                     throws UnsupportedOperationException

Returns an assertion which is the equivalent of intersect of self and argument. The rules to construct the equivalent assertion are specified in WS Policy 1.0 specification.

Parameters:

assertion - the assertion to intersect with

context - - The intersection context is passed to capture the running context of the intersection and to accumulate intersection failures

Returns:

the equivalent of intersect of self and the argument

Throws:

UnsupportedOperationException

intersect

IAssertion intersect(IAssertion assertion,
                     IPolicyRegistry reg,
                     IIntersectionContext context)
                     throws UnsupportedOperationException

Returns an assertion which is equivalent of intersect of self and argument. Here the external policy are resolved via a policy registry that is supplied as an argument.

Parameters:

assertion - the assertion to intersect with

cache - the policy registry which is used to resolve external policy references

context - - The intersection context is passed to capture the running context of the intersection and to accumulate intersection failures

Returns:

the equivalent of intersection of self and argument

Throws:

UnsupportedOperationException - if the operation is not meaningful

merge

IAssertion merge(IAssertion assertion)
                 throws UnsupportedOperationException

Returns the equivalent of merge of self and argument. The rules to construct the equivalent of merge are defined in WS Policy specification.

Parameters:

assertion - the argument to merge with

Returns:

the equivalent of the merge of self and argument

Throws:

UnsupportedOperationException

merge

IAssertion merge(IAssertion assertion,
                 IPolicyRegistry reg)
                 throws UnsupportedOperationException

Returns the equivalent of merge of self and argument. The rules to construct argument are specified in WS Policy specification 1.0 Here the external policy references are resolved via a policy registry that is supplied as an argument

Parameters:

assertion - the assertion to merge with

reg - the policy registry that should be used to resolve external policy references

Returns:

the equivalent of merge of self and argument

Throws:

UnsupportedOperationException - if the merge is not meaningful

isNormalized

boolean isNormalized()

Returns true if the Assertion has been normalized.

Returns:

setNormalized

void setNormalized(boolean flag)

WARNING: Do not call this method. Instead call the various normalize() methods - which in turn use this method.

Parameters:

flag -

getStringForMatching

String getStringForMatching()

The String to be used in the matching algorithim (used for intersection, merge, etc). By default the string representation of QName is returned!

Returns:

setOptional

void setOptional(boolean isOptional)

Specifies if the Assertion is optional. Maps to the wsp:Optional attribute defined in WS-Policy.

Parameters:

isOptional -

isOptional

boolean isOptional()

Returns true if the Assertion is optional.

Parameters:

isOptional -

isIdentical

boolean isIdentical(Object obj)

createInstance

IAssertion createInstance(QName qname)

Creates the appropriate assertion instance NOTE: The base implementation must be overriden by the subclasses!

Parameters:

qname -

Returns:

validate

void validate(IValidationContext context)

Validate this assertion If any errors are found, they are added to the passed Validation Context object

Parameters:

context -

getDigest

String getDigest()

Create a unique string representation that identifies this policy uniquely independent of the order of the assertions to enable a fast path intersection with another policy

Returns:

- String - the digest

getDigest

String getDigest(List<String> namespaces,
                 List<QName> qnames,
                 boolean inclusionOrExclusionCriteria)

Create a unique string representation that identifies this policy uniquely independent of the order of the assertions to enable a fast path intersection with another policy. if inclusionOrExclusionCriteria is true then:
Only assertions that are either in the namespace in the namespace list or the assertion qname mentioned in the qnames list are included in digest calculation. Basically this projects out the assertions belonging to the namespace or qname if namespaces is empty and qnames is empty then it is equivalent to calling getDigest() if inclusionOrExclusionCriteria is false then:
The assertions that are in the namespace list or assertion qname are no included in the digest calculation.

Parameters:

namespaces - - list of strings that define the namespaces to be include or excluded in digest calculation

qnames - - list of qnames that define the qnames to be included or excluded in digest calculation

inclusionOrExclusionCriteria - - whether the list of namespaces or qnames should be included or excluded in the digest calculation

Skip navigation links