001/**
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2006 Sun Microsystems Inc. All Rights Reserved
005 *
006 * The contents of this file are subject to the terms
007 * of the Common Development and Distribution License
008 * (the License). You may not use this file except in
009 * compliance with the License.
010 *
011 * You can obtain a copy of the License at
012 * https://opensso.dev.java.net/public/CDDLv1.0.html or
013 * opensso/legal/CDDLv1.0.txt
014 * See the License for the specific language governing
015 * permission and limitations under the License.
016 *
017 * When distributing Covered Code, include this CDDL
018 * Header Notice in each file and include the License file
019 * at opensso/legal/CDDLv1.0.txt.
020 * If applicable, add the following below the CDDL Header,
021 * with the fields enclosed by brackets [] replaced by
022 * your own identifying information:
023 * "Portions Copyrighted [year] [name of copyright owner]"
024 *
025 * $Id: Referral.java,v 1.2 2008/06/25 05:43:47 qcheng Exp $
026 *
027 */
028
029
030
031package com.sun.identity.policy.interfaces;
032
033import com.sun.identity.policy.*;
034import com.iplanet.sso.SSOToken;
035import com.iplanet.sso.SSOException;
036import java.util.*;
037
038/**
039 * Interface to facilitate delegating policy evaluation 
040 * There would be many implementations with different policy delegation 
041 * mechanisms such as delegating to peer organizations only 
042 * or delegating to sub organizations only. 
043 * @supported.all.api
044 */
045public interface Referral {
046    /**
047     * Initializes the Referral with a <code>Map</code>
048     * @param configurationMap a <code>Map</code> containing configuration 
049     *        information. Each key of the <code>Map</code> is a configuration
050     *        parameter. Each value of the key would be a <code>Set</code> of 
051     *        values for the parameter. The <code>Map</code> is cloned and a 
052     *        reference to the clone is stored in the referral
053     */
054    void initialize(Map configurationMap);
055
056    /**
057     * Sets the values of this referral 
058     * @param values <code>Set</code> of values for this referral.
059     *               Each element of the <code>Set</code> has to be a 
060     *               <code>String</code>
061     * @throws InvalidNameException if any value passed in values is 
062     *         not valid
063     */
064    void setValues(Set values) throws InvalidNameException;
065
066    /**
067     * Gets the values of this referral 
068     * @return the values of this referral
069     *     Each element of the returned <code>Set</code> is a 
070     *     <code>String</code>.
071     */
072    Set getValues();
073
074    /**
075     * 
076     * Returns the display name for the value for the given locale.
077     * For all the valid values obtained through the methods
078     * <code>getValidValues</code> this method must be called
079     * by web and command line interfaces to get the corresponding display name.
080     * The <code>locale</code> variable could be used by the
081     * plugin to customize
082     * the display name for the given locale.
083     * The <code>locale</code> variable
084     * could be <code>null</code>, in which case the plugin must
085     * use the default locale (most probably <code>en_US</code>).
086     * This method returns only the display name and should not
087     * be used for the method <code>setValues</code>.
088     * Alternatively, if the plugin does not have to localize
089     * the value, it can just return the <code>value</code> as is.
090     *
091     * @param value one of the valid value for the plugin
092     * @param locale locale for which the display name must be customized
093     * @return the display name for the value for the given locale.
094     * @exception NameNotFoundException if the given <code>value</code>
095     * is not one of the valid values for the plugin
096     */
097    public String getDisplayNameForValue(String value, Locale locale)
098        throws NameNotFoundException;
099
100    /**
101     * Gets the valid values for this referral 
102     * @param token <code>SSOToken</code>
103     * @return <code>ValidValues</code> object
104     * @throws SSOException, PolicyException
105     */
106    ValidValues getValidValues(SSOToken token) 
107        throws SSOException, PolicyException;
108
109    /**
110     * Gets the valid values for this referral 
111     * matching a pattern
112     * @param token <code>SSOToken</code>
113     * @param pattern a pattern to match against the value
114     * @return <code>ValidValues</code> object
115     * @throws SSOException, PolicyException
116     */
117    ValidValues getValidValues(SSOToken token, String pattern)
118        throws SSOException, PolicyException;
119
120    /**
121     * Gets the syntax for the value 
122     * @param token <code>SSOToken</code>
123     * @see com.sun.identity.policy.Syntax
124     */
125    Syntax getValueSyntax(SSOToken token)
126            throws SSOException, PolicyException;
127
128    /**
129     * Gets the name of the Referral Type 
130     * @return name of the Referral Type representing this referral
131     */
132    String getReferralTypeName();
133
134    /**
135     * Gets policy results 
136     * @param token SSOToken
137     * @param resourceType resource Type
138     * @param resourceName name of the resource
139     * @param actionNames a set of action names
140     * @param envParameters a map of enivronment parameters.
141     *        Each key is an environment parameter name.
142     *        Each value is a set of values for the parameter.
143     * @return policy decision
144     *
145     * @throws PolicyException
146     * @throws SSOException
147     */
148    PolicyDecision getPolicyDecision(SSOToken token, String resourceType,
149        String resourceName, Set actionNames, Map envParameters
150    ) throws SSOException, PolicyException;
151
152    /**
153     * Gets resource names that are exact matches, sub resources or 
154     * wild card matches of argument resource name.
155     * To determine whether to include a
156     * resource name of a resource,  argument resource name and  policy 
157     * resource name are compared treating wild characters in the policy 
158     * resource name as wild. If the comparsion resulted in EXACT_MATCH,
159     * WILD_CARD_MACTH or SUB_RESOURCE_MACTH, the resource result would be
160     * included.
161     *
162     * @param token sso token
163     * @param serviceTypeName service type name
164     * @param resourceName resource name
165     * @return names of sub resources for the given resourceName.
166     *         The return value also includes the resourceName.
167     *
168     * @throws PolicyException
169     * @throws SSOException
170     *
171     * @see com.sun.identity.policy.ResourceMatch#EXACT_MATCH
172     * @see com.sun.identity.policy.ResourceMatch#SUB_RESOURCE_MATCH
173     * @see com.sun.identity.policy.ResourceMatch#WILDCARD_MATCH
174     *
175     */
176    Set getResourceNames(SSOToken token, String serviceTypeName, 
177        String resourceName) throws PolicyException, SSOException;
178}