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}