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}