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




























































Copyright © 2010-2017, ForgeRock All Rights Reserved.