IAssertion (Oracle® Fusion Middleware Java API Reference for Oracle Web Services Manager for JRF)

All Superinterfaces:

java.io.Serializable
```
public interface IAssertion
extends java.io.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 ISimpleAssertion
2. MultiElement Simple Assertions IMultiElementSimpleAssertion
3. Nested Assertions INestedAssertion
4. Composite Assertions ICompositeAssertion
5. Scenario Assertions IScenarioAssertion
6. Step Scenario Assertions com.cfluent.policymanager.sdk.policy.IStepScenarioAssertion
7. Policy IPolicy
8. PolicyReference 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:

Cannot contain nested elements other than Oracle Extension element <orawsp:bindings>

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:

Can contain nested XML elements other than Oracle Extension element <orawsp:bindings>

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:name="level" type="string">
<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:

Can contain one child Policy XML element.

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

Can contain other child elements including the Oracle Extension element <orawsp:bindings> .

Non-assertion child elements do not participate in intersection.

All assertion that are contained by a Nested Assertion will participate in the intersection - unless domain dependent intersection semantics are defined.

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

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 getAssertionType() 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 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 NestedAssertion class.
Example:
The oracle.wsm.policy.model.impl.security.RecipientTokenAssertion class defines additional methods like getRecipientToken()
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 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
The "Default" Serializer/DeSerializer can address serialization/de-serialization for Nested Assertions, Simple Assertions, Multi-Element assertions.

Scenario Assertions
Scenario Assertion developers are required provide serialization/de-serialization implementation.
Scenario Assertion developers can use JAXB and other tools for serialization/de-serialization purposes.

Cloning
All implementations of IAssertion are expected to implement the ICloneable interface and implement the ICloneable.clone() method to clone its state.
Since:

11.1.1.1

Author:

pyamuna

See Also:

ICloneable.clone()

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static interface IAssertion.AssertionTypes
AssertionTypes Definition

Nested Classes
Modifier and Type	Interface and Description
`static interface`	`IAssertion.AssertionTypes` AssertionTypes Definition

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`addAttribute(javax.xml.namespace.QName qname, java.lang.String value)`
`IAssertion`	`createInstance(javax.xml.namespace.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.
`java.lang.String`	`getAttribute(javax.xml.namespace.QName qname)`
`java.util.Map<javax.xml.namespace.QName,java.lang.String>`	`getAttributes()`
`java.lang.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
`java.lang.String`	`getDigest(java.util.List<java.lang.String> namespaces, java.util.List<javax.xml.namespace.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
`javax.xml.namespace.QName`	`getQName()`
`java.lang.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, oracle.wsm.policy.model.IIntersectionContext context)` Returns an assertion which is the equivalent of intersect of self and argument.
`IAssertion`	`intersect(IAssertion assertion, oracle.wsm.policy.util.IPolicyRegistry reg, oracle.wsm.policy.model.IIntersectionContext context)` Returns an assertion which is equivalent of intersect of self and argument.
`boolean`	`isIdentical(java.lang.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, oracle.wsm.policy.util.IPolicyRegistry reg)` Returns the equivalent of merge of self and argument.
`IAssertion`	`normalize()` Normalizes the assertion and returns the normalized Assertion
`IAssertion`	`normalize(oracle.wsm.policy.util.IPolicyRegistry reg)`
`void`	`removeAttribute(javax.xml.namespace.QName qname)`
`void`	`setAttributes(java.util.Map<javax.xml.namespace.QName,java.lang.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(oracle.wsm.policy.validation.IValidationContext context)` Validate this assertion If any errors are found, they are added to the passed Validation Context object

- Method Detail
  - addAttribute
```
void addAttribute(javax.xml.namespace.QName qname,
                  java.lang.String value)
```
  - createInstance
```
IAssertion createInstance(javax.xml.namespace.QName qname)
```
    Creates the appropriate assertion instance NOTE: The base implementation must be overriden by the subclasses!
    
    Parameters:
    
    qname -
    
    Returns:
  - getAssertionType
```
int getAssertionType()
```
    Returns the type of the assertion.
  - getAttribute
```
java.lang.String getAttribute(javax.xml.namespace.QName qname)
```
  - getAttributes
```
java.util.Map<javax.xml.namespace.QName,java.lang.String> getAttributes()
```
  - getDigest
```
java.lang.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
```
java.lang.String getDigest(java.util.List<java.lang.String> namespaces,
                           java.util.List<javax.xml.namespace.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
  - getParent
```
IAssertion getParent()
```
    Returns the parent of self or null if a parent non-exists
    
    Returns:
    
    the parent of self
  - getQName
```
javax.xml.namespace.QName getQName()
```
  - getStringForMatching
```
java.lang.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:
  - hasParent
```
boolean hasParent()
```
    Returns ture if the assertion has a parent
    
    Returns:
    
    true if a parent exists , false otherwise
  - intersect
```
IAssertion intersect(IAssertion assertion,
                     oracle.wsm.policy.model.IIntersectionContext context)
              throws java.lang.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:
    
    java.lang.UnsupportedOperationException
  - intersect
```
IAssertion intersect(IAssertion assertion,
                     oracle.wsm.policy.util.IPolicyRegistry reg,
                     oracle.wsm.policy.model.IIntersectionContext context)
              throws java.lang.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:
    
    java.lang.UnsupportedOperationException - if the operation is not meaningful
  - isIdentical
```
boolean isIdentical(java.lang.Object obj)
```
  - isNormalized
```
boolean isNormalized()
```
    Returns true if the Assertion has been normalized.
    
    Returns:
  - isOptional
```
boolean isOptional()
```
    Returns true if the Assertion is optional.
    
    Parameters:
    
    isOptional -
  - merge
```
IAssertion merge(IAssertion assertion)
          throws java.lang.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:
    
    java.lang.UnsupportedOperationException
  - merge
```
IAssertion merge(IAssertion assertion,
                 oracle.wsm.policy.util.IPolicyRegistry reg)
          throws java.lang.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:
    
    java.lang.UnsupportedOperationException - if the merge is not meaningful
  - normalize
```
IAssertion normalize()
              throws java.lang.UnsupportedOperationException
```
    Normalizes the assertion and returns the normalized Assertion
    
    Returns:
    
    Throws:
    
    java.lang.UnsupportedOperationException
  - normalize
```
IAssertion normalize(oracle.wsm.policy.util.IPolicyRegistry reg)
              throws java.lang.UnsupportedOperationException
```
    Parameters:
    
    reg -
    
    Returns:
    
    Throws:
    
    java.lang.UnsupportedOperationException
  - removeAttribute
```
void removeAttribute(javax.xml.namespace.QName qname)
```
  - setAttributes
```
void setAttributes(java.util.Map<javax.xml.namespace.QName,java.lang.String> attributeMap)
```
  - 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 -
  - setOptional
```
void setOptional(boolean isOptional)
```
    Specifies if the Assertion is optional. Maps to the wsp:Optional attribute defined in WS-Policy.
    
    Parameters:
    
    isOptional -
  - setParent
```
void setParent(IAssertion parent)
```
    Set the parent to argument
    
    Parameters:
    
    parent - the parent that should be parent of self
  - validate
```
void validate(oracle.wsm.policy.validation.IValidationContext context)
```
    Validate this assertion If any errors are found, they are added to the passed Validation Context object
    
    Parameters:
    
    context -

Interface IAssertion

Nested Class Summary

Method Summary

Method Detail

addAttribute

createInstance

getAssertionType

getAttribute

getAttributes

getDigest

getDigest

getParent

getQName

getStringForMatching

hasParent

intersect

intersect

isIdentical

isNormalized

isOptional

merge

merge

normalize

normalize

removeAttribute

setAttributes

setNormalized

setOptional

setParent

validate