8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * Copyright (c) 2006 Sun Microsystems Inc. All Rights Reserved
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * The contents of this file are subject to the terms
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * of the Common Development and Distribution License
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * (the License). You may not use this file except in
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * compliance with the License.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * You can obtain a copy of the License at
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * https://opensso.dev.java.net/public/CDDLv1.0.html or
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * See the License for the specific language governing
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * permission and limitations under the License.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * When distributing Covered Code, include this CDDL
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * Header Notice in each file and include the License file
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * If applicable, add the following below the CDDL Header,
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * with the fields enclosed by brackets [] replaced by
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * your own identifying information:
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * "Portions Copyrighted [year] [name of copyright owner]"
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * $Id: ResponseProvider.java,v 1.5 2008/08/19 19:09:16 veiming Exp $
a4544a5a0e622ef69e38641f87ab1b5685e05911Phill Cunnington * Portions Copyrighted 2014-2015 ForgeRock AS.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * The class <code>ResponseProvider</code> defines an interface to allow
8d3140b524c0e28c0a49dc7c7d481123ef3cfe11Chris Lee * pluggable response providers into the OpenAM framework. These
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * are used to provide policy response attributes. Policy response attributes
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * are different from <code>ActionDecision</code>. Policy response attributes
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * typically provide attribute values of user profile. User profile could
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * exist in any data store managed by Identity repository. However, reponse
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * attributes are not restricted to attributes from user profile.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * Source of the attribute values is completely at the discretion of the
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * specific implementation of the <code>ResponseProvider</code>.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * The response provider is initialized by calling its <code>initialize()
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * </code> method.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * Its also configured by setting its properites by a call to
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * <code>setProperties()</code> method.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * Response attribute names are not checked against schema of the service
8d3140b524c0e28c0a49dc7c7d481123ef3cfe11Chris Lee * registered with OpenAM. (<code>ActionDecision</code> attributes
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * are checked against the schema of the service registered with
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * A Response Provider computes a <code>Map</code> of response attributes
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * and their values based on the <code>SSOToken</code>, resource name and
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * environment <code>Map</code> passed in the method call
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * <code>getResponseDecision()</code>.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * Policy framework would make a call <code>getResponseDecision</code> from the
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * <code>ResponseProvider</code>(s) associated with a policy only if the
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * policy is applicable to a request as determined by <code>SSOToken</code>,
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * <code>resource name</code>, <code>Subjects</code> and
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * <code>Conditions</code>.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * The only out-of-the-box <code>ResponseProvider</code> implementation
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * provided with the Policy framework would be
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * <code>IDRepoResponseProvider</code>.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * All <code>ResponseProvider</code> implementations should have a public no
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * argument constructor.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * @supported.all.api
0c9594d96d580b0cba488fa7d01802fbb49d8a3eCraig McDonnell * @deprecated since 12.0.0, use {@link com.sun.identity.entitlement.ResourceAttribute}
8af80418ba1ec431c8027fa9668e5678658d3611Allan Fosterpublic interface ResponseProvider extends Cloneable {
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * Initialize the <code>ResponseProvider</code>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * @param configParams <code>Map</code> of the configurational information
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * @exception PolicyException if an error occured during
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * initialization of the instance
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster public void initialize(Map configParams) throws PolicyException;
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * Returns a list of property names for the Response provider.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * @return list of property names
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * Returns the syntax for a property name
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * @see com.sun.identity.policy.Syntax
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * @param property property name
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * @return <code>Syntax<code> for the property name
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster public Syntax getPropertySyntax(String property);
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * Gets the display name for the property name.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * The <code>locale</code> variable could be used by the plugin to
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * customize the display name for the given locale.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * The <code>locale</code> variable could be <code>null</code>, in which
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * case the plugin must use the default locale.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * @param property property name
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * @param locale locale for which the property name must be customized
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * @return display name for the property name.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * @throws PolicyException
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster public String getDisplayName(String property, Locale locale)
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * Returns a set of valid values given the property name. This method
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * is called if the property <code>Syntax</code> is either the
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * <code>SINGLE_CHOICE</code> or <code>MULTIPLE_CHOICE</code>.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * @param property <code>String</code> representing property name
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * @return Set of valid values for the property.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * @exception PolicyException if unable to get the <code>Syntax</code>.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster public Set getValidValues(String property) throws
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster /** Sets the properties of the responseProvider plugin.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * This influences the response attribute-value Map that would be
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * computed by a call to method <code>getResponseDecision(Map)</code>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * These attribute-value pairs are encapsulated in
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * <code>ResponseAttribute</code> element tag which is a child of the
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * <code>PolicyDecision</code> element in the PolicyResponse xml
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * if the policy is applicable to the user for the resource, subject and
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * conditions defined.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * @param properties the properties of the <code>ResponseProvider</code>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * Keys of the properties have to be String.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * Value corresponding to each key have to be a <code>Set</code>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * of String elements. Each implementation of ResponseProvider
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * could add further restrictions on the keys and values of this
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * @throws PolicyException for any abnormal condition
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster public void setProperties(Map properties) throws PolicyException;
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster /** Gets the properties of the response provider.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * @return properties of the response provider.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * @see #setProperties
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * Gets the response attributes computed by this ResponseProvider object,
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * based on the <code>SSOToken</code> and <code>Map</code> of
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * environment parameters.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * @param token single-sign-on token of the user
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * @param env request specific environment map of key/value pairs
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * @return a <code>Map</code> of response attributes.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * Keys of the Map are attribute names of type <code>static</code>
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * and <code>dynamic</code>.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * Value is a <code>Set</code> of response attribute values
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * (<code>String</code>).
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * @throws PolicyException if the decision could not be computed
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * @throws SSOException <code>token is not valid
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * Returns a copy of this object.
8af80418ba1ec431c8027fa9668e5678658d3611Allan Foster * @return an <code>Object</code> which is a copy of this object