org.openliberty.arisid.policy
Class PolicyHandler

java.lang.Object
  org.openliberty.arisid.policy.PolicyHandler

public class PolicyHandler
extends java.lang.Object

WS-Policy Handler for managing and manipulating WS-Policy objects. This handler supports the ability to use different WS-Policy implementations. To switch WS-Policy libraries, a wrapper module (provider) must be written that implements the IArisWSPolicy interface, along with implementations of other interfaces in the org.openliberty.arisid.policy package. To switch policy providers, set the system property "org.openliberty.policy.wspolicy.class" WS_POLICY_CLASS to the name of the class implementing IArisWSPolicy. The policy implementation will be instantiated on the first class to PolicyHandler.getInstance() and will invoke the IArisWSPolicy.initialize() method.

Field Summary

static java.lang.String	DEF_WSPOLICY_CLASS
static java.lang.String	WS_POLICY_CLASS

Method Summary

boolean	addConstraintOrAssertionToPolicy(IAssertion[] assertions, IPolicy targetPolicy, boolean isAll) Adds a array of WS Policy IAssertion to an existing IPolicy object
boolean	addConstraintOrAssertionToPolicy(IAssertion assertion, IPolicy targetPolicy, boolean isAll) Adds a WS Policy IAssertion to an existing IPolicy object
void	addLocalityConstraint(java.lang.String language, IAttributeValue value) Adds a localization constraint to a specified IAttributeValue.
java.util.Map<java.lang.String,IPolicy>	addLocalityConstraint(java.lang.String language, java.lang.String name, java.util.Map<java.lang.String,IPolicy> constraintMap) Adds a localization constraint to a policy map for a specified attribute name.
java.util.Map<java.lang.String,IPolicy>	applyValueConstraints(IAttributeValue attrValue, java.lang.String language, java.util.Map<java.lang.String,IPolicy> constraintMap) When used as part of an interaction using an IAttributeValue (add, modify, compare), a preferred locality, or policies can be applied.
IAddValuesConstraint	createAddValuesConstraint() Create a constraint that changes a modify to indicate values should add too, rather than replace, current values.
IContractOrLegalConstraint	createContractOrLegalConstraint(java.net.URI contractUri, java.net.URI issuer) Create a constraint that defines the legal or contractual context under which information is being exchanged.
IDataDisplayMaskConstraint	createDataDisplayMaskConstraint(java.lang.String maskPattern, java.net.URI issuer) Describes components of string data which should be masked when data is displayed or logged.
IDataLossOrBreachConstraint	createDataLossOrBreachConstraint(java.net.URI breachReportUri, java.net.URI issuer) Describes the entities (e.g.
IDeleteValuesConstraint	createDeleteValuesConstraint() Generates a constraint used to change a modify operation to cause specific values provided to be deleted.
ILifetimeConstraint	createLifetimeConstraint(java.util.Date startDate, java.util.Date endDate) Generates a Lifetime constraint that specifies for how long an assertion is valid.
ILifetimeConstraint	createLifetimeConstraint(int hours, int mins) Generates a Lifetime constraint that specifies for how long an assertion is valid specified in hours and minutes from receipt.
ILocalizationConstraint	createLocalizationConstraint(java.lang.String languageCode) Creates a localization constraint request.
IPolicy	createNewPolicy() Creates a new empty IPolicy object.
IPropagateConstraint	createPropagateConstraint(java.net.URI propagateUri, java.net.URI issuer) Creates a constrint on the services or end-points to which the data may be propagated or forwarded.
IPurposeConstraint	createPurposeConstraint(java.net.URI purposeUri, java.net.URI issuer) Describes the usage context in which data is sought or the context in which data is being provided.
IRetentionConstraint	createRetentionConstraint(java.net.URI retentionUri, java.net.URI issuer) Indicates whether the data value can be retained by the requestor, in memory or otherwise.
IRetentionConstraint	createRetentionConstraint(java.net.URI retentionUri, java.net.URI issuer, ILifetimeConstraint lifetime) Indicates whether the data value can be retained by the requestor, in memory or otherwise, and the time period for which it can be retained.
IAssertion	getConstraint(IPolicy policy, javax.xml.namespace.QName assertionName) Returns the first instance of a constraint located within a policy.
static PolicyHandler	getInstance() Obtains a handle to the WS-Policy service.
IPolicy	getInteractionPolicy(IInteraction ixn) Return any policy associated with an Interaction definition.
java.util.List<java.lang.String>	getLocalityConstraints(IAttributeValue value) Returns a list of localization languages for a particular IAttributeValue object.
java.util.List<java.lang.String>	getLocalityConstraints(IPolicy policy) Return any constraints related to locality in the specified policy
IPolicy	getSchemaRefPolicy(IInteraction ixn, schemaRef attrPredOrRoleRef) Returns the WS-Policy as referenced in any AttributeRef, PredicateRef, or RoleRef object.
boolean	isAddValuesOnModify(IAttributeValue value, IModifyInteraction ixn) Used to check weather a set of values being used in a modify transaction are intended to add specific values rather than replace all values (the default).
boolean	isAssertionPresent(IPolicy policy, javax.xml.namespace.QName assertionName) A utility to test for the presence of a particular constraint or assertion class present in a Policy.
boolean	isDeleteValuesOnModify(IAttributeValue value, IModifyInteraction ixn) Used to check weather a set of values being used in a modify transaction are intended to delete specific values rather than replace all values (the default).
IPolicy	loadPolicyByReference(java.net.URI policyRef) Loads a Policy by URI reference.
IPolicy	parseDomPolicy(org.w3c.dom.Node policyNode) Takes a DOM parsed Node object and uses the WS-Policy implementation provider to generate an IPolicy object containing a native policy object.
IPolicy	parseStringPolicy(java.lang.String policyString) Invokes the selected DOM parser and WS-Policy implementation to parse an XML String into an IPolicy object.
org.w3c.dom.Element	parseStringToElement(java.lang.String pol) Converts a String representation of WS-Policy into a DOM Element.
org.w3c.dom.Element	policyToElement(java.lang.Object policy) Deprecated. Use of this method will tie calling code to a specific implementation of WS-Policy and may impact flexibility.
java.lang.String	policyToString(java.lang.Object policy) Converts a policy object (from the policy provider) to a String representation.
void	setAddValuesOnModifyConstraint(IAttributeValue value) Used to change the way a modify request works so that specific values listed can be added without having to replace all existing values.
void	setDeleteValuesOnModifyConstraint(IAttributeValue value) Used to change the way a modify request works so that specific values listed can be deleted.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

WS_POLICY_CLASS

public static final java.lang.String WS_POLICY_CLASS

See Also:

Constant Field Values

DEF_WSPOLICY_CLASS

public static final java.lang.String DEF_WSPOLICY_CLASS

See Also:

Constant Field Values

Method Detail

getInstance

public static PolicyHandler getInstance()

Obtains a handle to the WS-Policy service. The first time this method is called, the declared WS-Policy provider (implementing IArisWSPolicy) will be instantiated. The default is: org.openliberty.arisid.policy.neethi.PolicyImpl To override the default, set the system property "org.openliberty.policy.wspolicy.class" to the name of the class implementing IArisWSPolicy interface.

Returns:

a handler to the PolicyHandler system

Throws:

java.lang.ClassCastException - If the specified class does not implement IArisWSPolicy

java.lang.ClassNotFoundException - If the specified class cannot be loaded.

addLocalityConstraint

public void addLocalityConstraint(java.lang.String language,
                                  IAttributeValue value)
                           throws PolicyException

Adds a localization constraint to a specified IAttributeValue. Note that the localization applies to all values in IAttributeValue. When localization is applied to a value, the intent is usually to tag or indicate that a particular value is of a particular locality.

Parameters:

language - Language token as defined by RFC3066 http://www.w3.org/TR/xmlschema-2/#RFC3066

value - The IAttributeValue for which the constraint is to be applied.

Throws:

PolicyException - LanguageCode must not be null or empty string.

addLocalityConstraint

public java.util.Map<java.lang.String,IPolicy> addLocalityConstraint(java.lang.String language,
                                                                     java.lang.String name,
                                                                     java.util.Map<java.lang.String,IPolicy> constraintMap)
                                                              throws PolicyException

Adds a localization constraint to a policy map for a specified attribute name. Typically used in read/search requests. Note that the localization applies to all values in IAttributeValue. When localization is applied to a value, the intent is usually to tag or indicate that a particular value is of a particular locality.

Parameters:

language - Language token as defined by RFC3066 http://www.w3.org/TR/xmlschema-2/#RFC3066

name - Name identifier of the attribute the constraint is to be associated with.

constraintMap - A Map containing existing existing constraints for which the language constraint is to be added. To create a new map, pass a null.

Returns:

Map The modified map containing the requested constraint.

Throws:

PolicyException

applyValueConstraints

public java.util.Map<java.lang.String,IPolicy> applyValueConstraints(IAttributeValue attrValue,
                                                                     java.lang.String language,
                                                                     java.util.Map<java.lang.String,IPolicy> constraintMap)
                                                              throws PolicyException

When used as part of an interaction using an IAttributeValue (add, modify, compare), a preferred locality, or policies can be applied. Note: If a language parameter is specified, it will be added to existing policy specified in constraintMap (which may also have locality constraints). If a policy for the attribute is defined in constraintMap, it will override any existing policy in the passed attributeValue - otherwise, existing policy in attributeValue is used if none if found in constraintMap for the attribute. Note: At least one of language or constraintMap must be specified.

Parameters:

attrValue - An IAttributeValue for which the locality constraint is to be set. An IAttributeValue object for whom the localization request constraint is to be added. To set the constraint for all data in the interaction, specify the interaction name instead of the data element name.

language - Language token as defined by RFC3066 http://www.w3.org/TR/xmlschema-2/#RFC3066 (may be null)

constraintMap - A Map containing existing existing constraints for which the language constraint is to be added. To create a new map, pass a null. Existing values will overwrite policy already set in attrValue.

Returns:

Map The modified map containing the requested constraint.

Throws:

PolicyException - If attrValue is null, or if both language and constraintMap is null.

getConstraint

public IAssertion getConstraint(IPolicy policy,
                                javax.xml.namespace.QName assertionName)

Returns the first instance of a constraint located within a policy.

Parameters:

policy - The IPolicy object within which to search for the constraint or assertion.

assertionName - An String representing a IAssertion in QName form to search for.

Returns:

Returns the first IAssertion located or null

getInteractionPolicy

public IPolicy getInteractionPolicy(IInteraction ixn)

Return any policy associated with an Interaction definition.

Parameters:

ixn - A handle to a IInteraction object for which associated policy is to be returned.

Returns:

The policy associated or null if none defined

getLocalityConstraints

public java.util.List<java.lang.String> getLocalityConstraints(IPolicy policy)

Return any constraints related to locality in the specified policy

Parameters:

policy - A WS-Policy object that may contain a locality constraint

Returns:

A list containing locality constraints if present, or NULL.

getLocalityConstraints

public java.util.List<java.lang.String> getLocalityConstraints(IAttributeValue value)

Returns a list of localization languages for a particular IAttributeValue object. For a returned valued, the order should reflect the languages of the returned values.

Parameters:

value - The value object that may contain localized values.

Returns:

An List of String language values contained or null if no localization present.

getSchemaRefPolicy

public IPolicy getSchemaRefPolicy(IInteraction ixn,
                                  schemaRef attrPredOrRoleRef)

Returns the WS-Policy as referenced in any AttributeRef, PredicateRef, or RoleRef object.

Parameters:

ixn - The interaction that contains the schemaRef object.

attrPredOrRoleRef - The particular AttributeRef, PredicateRef, or RoleRef whose policy needs to be returned.

Returns:

The IPolicy declared for this particular use of schema for this Interaction.

isAddValuesOnModify

public boolean isAddValuesOnModify(IAttributeValue value,
                                   IModifyInteraction ixn)

Used to check weather a set of values being used in a modify transaction are intended to add specific values rather than replace all values (the default).

Parameters:

value - The IAttributeValue to be tested.

ixn - The modify interaction definition for the transaction.

Returns:

true if IAddValuesConstraint is present.

isAssertionPresent

public boolean isAssertionPresent(IPolicy policy,
                                  javax.xml.namespace.QName assertionName)

A utility to test for the presence of a particular constraint or assertion class present in a Policy. Note: this does not test whether the policy is required. Use the "intersect" method of your selected WS-Policy implementation for this purpose.

Parameters:

policy - The policy object to be tested for the presence of assertionName.

assertionName - The assertion name to look for within the policy.

Returns:

boolean value indicating whether the assertionName type is present in the specified policy.

isDeleteValuesOnModify

public boolean isDeleteValuesOnModify(IAttributeValue value,
                                      IModifyInteraction ixn)

Used to check weather a set of values being used in a modify transaction are intended to delete specific values rather than replace all values (the default).

Parameters:

value - The IAttributeValue to be tested.

ixn - The modify interaction definition for the transaction.

Returns:

true if IDeleteValuesConstraint is present.

parseStringPolicy

public IPolicy parseStringPolicy(java.lang.String policyString)
                          throws java.lang.Exception

Invokes the selected DOM parser and WS-Policy implementation to parse an XML String into an IPolicy object.

Parameters:

policyString - An XML String representing a WS-Policy or WS-PolicyReference object

Returns:

An IPolicy containing the parsed policy. Use IPolicy.getPolicy() to obtain the actual native policy built by the selected WS-Policy implementation.

Throws:

java.lang.Exception

parseStringToElement

public org.w3c.dom.Element parseStringToElement(java.lang.String pol)

Converts a String representation of WS-Policy into a DOM Element. Using DOM parsing only.

Parameters:

pol - An XML String representation of WS-Policy

Returns:

A DOM Element containing the WS-Policy

policyToElement

public org.w3c.dom.Element policyToElement(java.lang.Object policy)

Deprecated. Use of this method will tie calling code to a specific implementation of WS-Policy and may impact flexibility.

Converts a native policy object (from the policy provider) to a DOM Element

Parameters:

policy - A Java object representing the WS-Provider native implementation of a WS Policy object. Typically obtained from IPolicy.getPolicy().

Returns:

A DOM Element representation of the WS-Policy

policyToString

public java.lang.String policyToString(java.lang.Object policy)

Converts a policy object (from the policy provider) to a String representation. The method accepts IPolicy or native policy objects. WARNING: Use of native policy objects is discouraged as this causes binding to specific WS-Policy implementations and may impact deployability.

Parameters:

policy - An IPolicy object or native ws-policy object to be converted. Typically obtained from IPolicy.getPolicy().

Returns:

A String representation of the ws-policy object

parseDomPolicy

public IPolicy parseDomPolicy(org.w3c.dom.Node policyNode)

Takes a DOM parsed Node object and uses the WS-Policy implementation provider to generate an IPolicy object containing a native policy object.

Parameters:

policyNode - A DOM Node containing a Policy or PolicyReference node.

Returns:

An IPolicy object holding the WS-Policy object.

setAddValuesOnModifyConstraint

public void setAddValuesOnModifyConstraint(IAttributeValue value)
                                    throws PolicyException

Used to change the way a modify request works so that specific values listed can be added without having to replace all existing values.

Parameters:

value - The IAttributeValue object that is to be used in a modify request.

Throws:

PolicyException

setDeleteValuesOnModifyConstraint

public void setDeleteValuesOnModifyConstraint(IAttributeValue value)
                                       throws PolicyException

Used to change the way a modify request works so that specific values listed can be deleted.

Parameters:

value - The IAttributeValue object that is to be used in a modify request.

Throws:

PolicyException

loadPolicyByReference

public IPolicy loadPolicyByReference(java.net.URI policyRef)

Loads a Policy by URI reference. The reference may be within the CARML Doc or may be an external reference.

Parameters:

policyRef - A URI referencing a WS-Policy document.

Returns:

An IPolicy object containing the obtained and parsed policy.

createAddValuesConstraint

public IAddValuesConstraint createAddValuesConstraint()

Create a constraint that changes a modify to indicate values should add too, rather than replace, current values.

Returns:

IAddValuesConstraint constraint object

createContractOrLegalConstraint

public IContractOrLegalConstraint createContractOrLegalConstraint(java.net.URI contractUri,
                                                                  java.net.URI issuer)

Create a constraint that defines the legal or contractual context under which information is being exchanged. See IContractOrLegalConstraint for more information.

Parameters:

contractUri - A URI that defines the legal context under which information is being exchanged.

issuer - A URI indicatig the party asserting the constraint (user, relying party, provider service).

Returns:

IContractOrLegalConstraint constraint object.

createDataDisplayMaskConstraint

public IDataDisplayMaskConstraint createDataDisplayMaskConstraint(java.lang.String maskPattern,
                                                                  java.net.URI issuer)

Describes components of string data which should be masked when data is displayed or logged.

Parameters:

maskPattern - A masking pattern (depending on industry convention) indicating how value is to be masked.

issuer - A URI indicatig the party asserting the constraint (user, relying party, provider service).

Returns:

IDataDisplayMaskConstraint constraint object.

createDataLossOrBreachConstraint

public IDataLossOrBreachConstraint createDataLossOrBreachConstraint(java.net.URI breachReportUri,
                                                                    java.net.URI issuer)

Describes the entities (e.g. business or government authority, the user, etc) to be informed if the data is lost or compromised. Example values: urn:liberty:names:1.0:igf:pri:breachreport:end-user Indicates that the breach MUST be reported to the relevant end-user. urn:liberty:names:1.0:igf:pri:breachreport:source Indicates that the breach MUST be reported to the original source.

Parameters:

breachReportUri - URI breach notification URI value. A URI indicatig the party asserting the constraint (user, relying party, provider service).

issuer - A URI indicatig the party asserting the constraint (user, relying party, provider service).

Returns:

IDataLossOrBreachConstraint constraint object

createDeleteValuesConstraint

public IDeleteValuesConstraint createDeleteValuesConstraint()

Generates a constraint used to change a modify operation to cause specific values provided to be deleted.

Returns:

IDeleteValuesConstraint constraint object

createLifetimeConstraint

public ILifetimeConstraint createLifetimeConstraint(int hours,
                                                    int mins)

Generates a Lifetime constraint that specifies for how long an assertion is valid specified in hours and minutes from receipt.

Parameters:

hours - the number of hours from receipt the values are valid.

mins - the number of minutes from receipt the values are valid.

Returns:

ILifetimeConstraint constraint object

createLifetimeConstraint

public ILifetimeConstraint createLifetimeConstraint(java.util.Date startDate,
                                                    java.util.Date endDate)

Generates a Lifetime constraint that specifies for how long an assertion is valid. Specified in terms of start and end dates.

Parameters:

startDate - the date from which values are valid.

endDate - the date until which values are valid.

Returns:

ILifetimeConstraint constraint object

createLocalizationConstraint

public ILocalizationConstraint createLocalizationConstraint(java.lang.String languageCode)
                                                     throws PolicyException

Creates a localization constraint request.

Parameters:

languageCode - Language token as defined by RFC3066 http://www.w3.org/TR/xmlschema-2/#RFC3066

Throws:

PolicyException - LanguageCode must not be null or empty string.

createPropagateConstraint

public IPropagateConstraint createPropagateConstraint(java.net.URI propagateUri,
                                                      java.net.URI issuer)

Creates a constrint on the services or end-points to which the data may be propagated or forwarded. This specification defines a single standard URI for constraining propagation. urn:liberty:names:1.0:igf:pri:propagate:requestor Indicates that the data value MUST NOT be propagated beyond the requestor. Other entities for which it might be relevant to constrain propagation might include service, server, department, end-point, etc. The expectation is that such constraints would be defined in other profiles.

Parameters:

propagateUri - The URI describing propagate restrictions.

issuer - A URI indicatig the party asserting the constraint (user, relying party, provider service).

Returns:

An IPropagateConstraint constraint object

createPurposeConstraint

public IPurposeConstraint createPurposeConstraint(java.net.URI purposeUri,
                                                  java.net.URI issuer)

Describes the usage context in which data is sought or the context in which data is being provided. This specification defines a single standard URI for constraining purpose. urn:liberty:names:1.0:igf:pri:purpose:context Indicates that the purpose for which the data value is sought SHOULD be determined from application context. The application context may be determined in many different ways, including for example, by examining the message carrying the constraint. Our expectation is that communities will define additional URIs based on rules for industry verticals and national jurisdictions.

Parameters:

purposeUri - A URI describing the designated transaction purpose.

issuer - A URI indicatig the party asserting the constraint (user, relying party, provider service).

Returns:

An IPurposeConstraint constraint object.

createRetentionConstraint

public IRetentionConstraint createRetentionConstraint(java.net.URI retentionUri,
                                                      java.net.URI issuer)

Indicates whether the data value can be retained by the requestor, in memory or otherwise. This specification defines five standard URIs for constraining retention. urn:liberty:names:1.0:igf:pri:retention:nocache Indicates that the data value MUST NOT be cached or persisted and should be overwritten after a single use. urn:liberty:names:1.0:igf:pri:retention:transient Indicates that the data value MAY be held in memory cache but MUST NOT be persisted. urn:liberty:names:1.0:igf:pri:retention:persist Indicates that the data value MAY be persisted. urn:liberty:names:1.0:igf:pri:retention:persist:encrypt Indicates that the data value MUST be encrypted when copied to persistent store. urn:liberty:names:1.0:igf:pri:retention:nolog Indicates that the data value MUST NOT be written to log.

Parameters:

retentionUri - The URI indicating permitted type of retention.

issuer - A URI indicatig the party asserting the constraint (user, relying party, provider service).

Returns:

An IRetentionConstraint constraint object.

createRetentionConstraint

public IRetentionConstraint createRetentionConstraint(java.net.URI retentionUri,
                                                      java.net.URI issuer,
                                                      ILifetimeConstraint lifetime)

Indicates whether the data value can be retained by the requestor, in memory or otherwise, and the time period for which it can be retained. This specification defines five standard URIs for constraining retention. urn:liberty:names:1.0:igf:pri:retention:nocache Indicates that the data value MUST NOT be cached or persisted and should be overwritten after a single use. urn:liberty:names:1.0:igf:pri:retention:transient Indicates that the data value MAY be held in memory cache but MUST NOT be persisted. urn:liberty:names:1.0:igf:pri:retention:persist Indicates that the data value MAY be persisted. urn:liberty:names:1.0:igf:pri:retention:persist:encrypt Indicates that the data value MUST be encrypted when copied to persistent store. urn:liberty:names:1.0:igf:pri:retention:nolog Indicates that the data value MUST NOT be written to log.

Parameters:

retentionUri - The URI indicating permitted type of retention.

issuer - A URI indicatig the party asserting the constraint (user, relying party, provider service).

lifetime - An ILifetimeConstraint indicating the period of retention.

Returns:

An IRetentionConstraint constraint object.

createNewPolicy

public IPolicy createNewPolicy()

Creates a new empty IPolicy object. Used for building policies in Java. Use IPolicy.getPolicy() to obtain the actual policy object created by the WS-Policy provider.

Returns:

an IPolicy object

addConstraintOrAssertionToPolicy

public boolean addConstraintOrAssertionToPolicy(IAssertion assertion,
                                                IPolicy targetPolicy,
                                                boolean isAll)

Adds a WS Policy IAssertion to an existing IPolicy object

Parameters:

assertion - An assertion implementing the IAssertion interface

targetPolicy - A policy object implementing IPolicy

isAll - If true, policy will be added using a WS-Policy ALL structure, or ExactlyOne if false.

Returns:

true if the policy was succesfully updated.

addConstraintOrAssertionToPolicy

public boolean addConstraintOrAssertionToPolicy(IAssertion[] assertions,
                                                IPolicy targetPolicy,
                                                boolean isAll)

Adds a array of WS Policy IAssertion to an existing IPolicy object

Parameters:

assertions - An assertion implementing the IAssertion interface

targetPolicy - A policy object implementing IPolicy

isAll - If true, policy will be added using a WS-Policy ALL structure, or ExactlyOne if false.

Returns:

true if the policy was succesfully updated.