|
Oracle Fusion Middleware Java API Reference for Oracle Web Services Manager 11g (11.1.1.4) E10689-03 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface IAssertion
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?
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.
ISimpleAssertion
IMultiElementSimpleAssertion
INestedAssertion
ICompositeAssertion
IScenarioAssertion
com.cfluent.policymanager.sdk.policy.IStepScenarioAssertion
IPolicy
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:
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:
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:
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:
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!
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 oracle.wsm.policy.model.impl.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
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.
ICloneable.clone()
Nested Class Summary | |
---|---|
static interface |
IAssertion.AssertionTypes |
Method Summary | |
---|---|
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 |
---|
void addAttribute(javax.xml.namespace.QName qname, java.lang.String value)
IAssertion createInstance(javax.xml.namespace.QName qname)
qname
-int getAssertionType()
java.lang.String getAttribute(javax.xml.namespace.QName qname)
java.util.Map<javax.xml.namespace.QName,java.lang.String> getAttributes()
java.lang.String getDigest()
java.lang.String getDigest(java.util.List<java.lang.String> namespaces, java.util.List<javax.xml.namespace.QName> qnames, boolean inclusionOrExclusionCriteria)
inclusionOrExclusionCriteria
is true then:namespaces
is empty and qnames
is empty then it is equivalent to calling getDigest()
if inclusionOrExclusionCriteria
is false then:namespaces
- - list of strings that define the namespaces to be include or excluded in digest calculationqnames
- - list of qnames that define the qnames to be included or excluded in digest calculationinclusionOrExclusionCriteria
- - whether the list of namespaces or qnames should be included or excluded in the digest calculationIAssertion getParent()
javax.xml.namespace.QName getQName()
java.lang.String getStringForMatching()
boolean hasParent()
IAssertion intersect(IAssertion assertion, oracle.wsm.policy.model.IIntersectionContext context) throws java.lang.UnsupportedOperationException
assertion
- the assertion to intersect withcontext
- - The intersection context is passed to capture the running context of the intersection and to accumulate intersection failuresjava.lang.UnsupportedOperationException
IAssertion intersect(IAssertion assertion, oracle.wsm.policy.util.IPolicyRegistry reg, oracle.wsm.policy.model.IIntersectionContext context) throws java.lang.UnsupportedOperationException
assertion
- the assertion to intersect withcache
- the policy registry which is used to resolve external policy referencescontext
- - The intersection context is passed to capture the running context of the intersection and to accumulate intersection failuresjava.lang.UnsupportedOperationException
- if the operation is not meaningfulboolean isIdentical(java.lang.Object obj)
boolean isNormalized()
boolean isOptional()
isOptional
-IAssertion merge(IAssertion assertion) throws java.lang.UnsupportedOperationException
assertion
- the argument to merge withjava.lang.UnsupportedOperationException
IAssertion merge(IAssertion assertion, oracle.wsm.policy.util.IPolicyRegistry reg) throws java.lang.UnsupportedOperationException
assertion
- the assertion to merge withreg
- the policy registry that should be used to resolve external policy referencesjava.lang.UnsupportedOperationException
- if the merge is not meaningfulIAssertion normalize() throws java.lang.UnsupportedOperationException
java.lang.UnsupportedOperationException
IAssertion normalize(oracle.wsm.policy.util.IPolicyRegistry reg) throws java.lang.UnsupportedOperationException
reg
-java.lang.UnsupportedOperationException
void removeAttribute(javax.xml.namespace.QName qname)
void setAttributes(java.util.Map<javax.xml.namespace.QName,java.lang.String> attributeMap)
void setNormalized(boolean flag)
flag
-void setOptional(boolean isOptional)
isOptional
-void setParent(IAssertion parent)
parent
- the parent that should be parent of selfvoid validate(oracle.wsm.policy.validation.IValidationContext context)
context
-
|
Oracle Fusion Middleware Java API Reference for Oracle Web Services Manager 11g (11.1.1.4) E10689-03 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |