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: Subject.java,v 1.3 2009/05/05 18:27:47 mrudul_uchil Exp $ 026 * 027 */ 028 029 030 031 032package com.sun.identity.policy.interfaces; 033 034import java.util.Set; 035import java.util.Map; 036import java.util.Locale; 037import com.iplanet.sso.SSOToken; 038import com.iplanet.sso.SSOException; 039import com.sun.identity.policy.Syntax; 040import com.sun.identity.policy.PolicyException; 041import com.sun.identity.policy.InvalidNameException; 042import com.sun.identity.policy.NameNotFoundException; 043import com.sun.identity.policy.ValidValues; 044 045/** 046 * The class <code>Subject</code> defines a collection 047 * of users (or subject) to whom the specified <code>Policy</code> is applied. 048 * A complete implementation of this interface can have complex 049 * boolean operations to determine if the given user identified 050 * by the <code>SSOToken</code> belongs to this collection. 051 * <p> 052 * The interfaces are separated into administrative 053 * interfaces and evaluation interfaces. The administrative interfaces 054 * will be used by web interface/command line interface component to create a 055 * <code>Subject</code> object and the evaluation interfaces will be used by the 056 * {@link com.sun.identity.policy.PolicyEvaluator PolicyEvaluator}. 057 * 058 * @supported.all.api 059 */ 060public interface Subject extends Cloneable { 061 062 /** 063 * Returns the syntax of the values the 064 * <code>Subject</code> implementation can have. 065 * @see com.sun.identity.policy.Syntax 066 * 067 * @param token the <code>SSOToken</code> that will be used 068 * to determine the syntax 069 * 070 * @return <code>Set</code> of valid names for the user collection. 071 * 072 * @exception SSOException if <code>SSOToken</code> is not valid 073 * @exception <code>PolicyException</code> if unable to get the list of 074 * valid names. 075 * 076 * @return <code>Syntax</code> of the values for the <code>Subject</code> 077 */ 078 public Syntax getValueSyntax(SSOToken token) 079 throws SSOException, PolicyException; 080 081 /** 082 * Returns a list of possible values for the <code>Subject 083 * </code>. The implementation must use the <code>SSOToken 084 * </code> <i>token</i> provided to determine the possible 085 * values. For example, in a Role implementation 086 * this method will return all the roles defined 087 * in the organization. 088 * 089 * @param token the <code>SSOToken</code> that will be used 090 * to determine the possible values 091 * 092 * @return <code>ValidValues</code> object 093 * 094 * @exception SSOException if <code>SSOToken</code> is not valid 095 * @exception PolicyException if unable to get the list of valid 096 * names. 097 */ 098 public ValidValues getValidValues(SSOToken token) 099 throws SSOException, PolicyException; 100 101 /** 102 * Returns a list of possible values for the <code>Subject 103 * </code> that satisfy the given <code>pattern</code>. 104 * The implementation must use the <code>SSOToken 105 * </code> <i>token</i> provided to determine the possible 106 * values. For example, in a Role implementation with the 107 * search filter <code>*admin</code> this method will return all 108 * the roles defined in the organization that end with <code>admin</code> 109 * 110 * @param token the <code>SSOToken</code> that will be used 111 * to determine the possible values 112 * @param pattern search pattern that will be used to narrow 113 * the list of valid names. 114 * 115 * @return <code>ValidValues</code> object 116 * 117 * @exception SSOException if <code>SSOToken</code> is not valid 118 * @exception PolicyException if unable to get the list of valid 119 * names. 120 */ 121 public ValidValues getValidValues(SSOToken token, String pattern) 122 throws SSOException, PolicyException; 123 124 /** 125 * Returns the display name for the value for the given locale. 126 * For all the valid values obtained through the methods 127 * <code>getValidValues</code> this method must be called 128 * by web and command line interface to get the corresponding display name. 129 * The <code>locale</code> variable could be used by the 130 * plugin to customize the display name for the given locale. 131 * The <code>locale</code> variable 132 * could be <code>null</code>, in which case the plugin must 133 * use the default locale (most probably <code>en_US</code>). 134 * This method returns only the display name and should not 135 * be used for the method <code>setValues</code>. 136 * Alternatively, if the plugin does not have to localize 137 * the value, it can just return the <code>value</code> as is. 138 * 139 * @param value one of the valid value for the plugin 140 * @param locale locale for which the display name must be customized 141 * @return the display name for the value for the given locale. 142 * @exception NameNotFoundException if the given <code>value</code> 143 * is not one of the valid values for the plugin 144 */ 145 public String getDisplayNameForValue(String value, Locale locale) 146 throws NameNotFoundException; 147 148 /** 149 * Returns the values that was set using the 150 * method <code>setValues</code>. 151 * 152 * @return <code>Set</code> of values that have been set for the 153 * user collection. 154 */ 155 public Set getValues(); 156 157 /** 158 * Initialize (or configure) the <code>Subject</code> 159 * object. Usually it will be initialized with the environment 160 * parameters set by the system administrator via admin console. 161 * For example in a Role implementation, the configuration 162 * parameters could specify the directory server name, port, etc. 163 * 164 * @param configParams configuration parameters as a <code>Map</code>. 165 * The values in the map is <code>java.util.Set</code>, 166 * which contains one or more configuration parameters. 167 * 168 * @exception PolicyException if an error occurred during 169 * initialization of <code>Subject</code> instance 170 */ 171 public void initialize(Map configParams) throws PolicyException; 172 173 /** 174 * Sets the names for the instance of the <code>Subject</code> 175 * object. The names are obtained from the <code>Policy</code> object, 176 * usually configured when a policy is created. For example 177 * in a Role implementation, this would be name of the role. 178 * 179 * @param names names selected for the instance of 180 * the user collection object. 181 * 182 * @exception InvalidNameException if the given names are not valid 183 */ 184 public void setValues(Set names) throws InvalidNameException; 185 186 /** 187 * Determines if the user belongs to this instance 188 * of the <code>Subject</code> object. 189 * For example, a Role implementation 190 * would return <code>true</code> if the user belongs 191 * the specified role; <code>false</code> otherwise. 192 * 193 * @param token single-sign-on token of the user 194 * 195 * @return <code>true</code> if the user is member of the 196 * given subject; <code>false</code> otherwise. 197 * 198 * @exception SSOException if SSO token is not valid 199 * @exception PolicyException if an error occurred while 200 * checking if the user is a member of this subject 201 */ 202 public boolean isMember(SSOToken token) 203 throws SSOException, PolicyException; 204 205 /** 206 * Creates and returns a copy of this object. 207 * 208 * @return a copy of this object 209 */ 210 public Object clone(); 211}