Subject.java revision 0c9594d96d580b0cba488fa7d01802fbb49d8a3e
/**
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2006 Sun Microsystems Inc. All Rights Reserved
*
* The contents of this file are subject to the terms
* of the Common Development and Distribution License
* (the License). You may not use this file except in
* compliance with the License.
*
* You can obtain a copy of the License at
* See the License for the specific language governing
* permission and limitations under the License.
*
* When distributing Covered Code, include this CDDL
* Header Notice in each file and include the License file
* at opensso/legal/CDDLv1.0.txt.
* If applicable, add the following below the CDDL Header,
* with the fields enclosed by brackets [] replaced by
* your own identifying information:
* "Portions Copyrighted [year] [name of copyright owner]"
*
* $Id: Subject.java,v 1.3 2009/05/05 18:27:47 mrudul_uchil Exp $
*
* Portions Copyrighted 2014 ForgeRock AS.
*/
/**
* The class <code>Subject</code> defines a collection
* of users (or subject) to whom the specified <code>Policy</code> is applied.
* A complete implementation of this interface can have complex
* boolean operations to determine if the given user identified
* by the <code>SSOToken</code> belongs to this collection.
* <p>
* The interfaces are separated into administrative
* interfaces and evaluation interfaces. The administrative interfaces
* <code>Subject</code> object and the evaluation interfaces will be used by the
* {@link com.sun.identity.policy.PolicyEvaluator PolicyEvaluator}.
*
* @supported.all.api
* @deprecated since 12.0.0, use {@link com.sun.identity.entitlement.EntitlementSubject}
*/
/**
* Returns the syntax of the values the
* <code>Subject</code> implementation can have.
* @see com.sun.identity.policy.Syntax
*
* @param token the <code>SSOToken</code> that will be used
* to determine the syntax
*
* @return <code>Set</code> of valid names for the user collection.
*
* @exception SSOException if <code>SSOToken</code> is not valid
* @exception <code>PolicyException</code> if unable to get the list of
* valid names.
*
* @return <code>Syntax</code> of the values for the <code>Subject</code>
*/
throws SSOException, PolicyException;
/**
* Returns a list of possible values for the <code>Subject
* </code>. The implementation must use the <code>SSOToken
* </code> <i>token</i> provided to determine the possible
* values. For example, in a Role implementation
* this method will return all the roles defined
* in the organization.
*
* @param token the <code>SSOToken</code> that will be used
* to determine the possible values
*
* @return <code>ValidValues</code> object
*
* @exception SSOException if <code>SSOToken</code> is not valid
* @exception PolicyException if unable to get the list of valid
* names.
*/
throws SSOException, PolicyException;
/**
* Returns a list of possible values for the <code>Subject
* </code> that satisfy the given <code>pattern</code>.
* The implementation must use the <code>SSOToken
* </code> <i>token</i> provided to determine the possible
* values. For example, in a Role implementation with the
* search filter <code>*admin</code> this method will return all
* the roles defined in the organization that end with <code>admin</code>
*
* @param token the <code>SSOToken</code> that will be used
* to determine the possible values
* @param pattern search pattern that will be used to narrow
* the list of valid names.
*
* @return <code>ValidValues</code> object
*
* @exception SSOException if <code>SSOToken</code> is not valid
* @exception PolicyException if unable to get the list of valid
* names.
*/
throws SSOException, PolicyException;
/**
* Returns the display name for the value for the given locale.
* For all the valid values obtained through the methods
* <code>getValidValues</code> this method must be called
* by web and command line interface to get the corresponding display name.
* The <code>locale</code> variable could be used by the
* plugin to customize the display name for the given locale.
* The <code>locale</code> variable
* could be <code>null</code>, in which case the plugin must
* use the default locale (most probably <code>en_US</code>).
* This method returns only the display name and should not
* be used for the method <code>setValues</code>.
* Alternatively, if the plugin does not have to localize
* the value, it can just return the <code>value</code> as is.
*
* @param value one of the valid value for the plugin
* @param locale locale for which the display name must be customized
* @return the display name for the value for the given locale.
* @exception NameNotFoundException if the given <code>value</code>
* is not one of the valid values for the plugin
*/
throws NameNotFoundException;
/**
* Returns the values that was set using the
* method <code>setValues</code>.
*
* @return <code>Set</code> of values that have been set for the
* user collection.
*/
/**
* Initialize (or configure) the <code>Subject</code>
* object. Usually it will be initialized with the environment
* parameters set by the system administrator via admin console.
* For example in a Role implementation, the configuration
* parameters could specify the directory server name, port, etc.
*
* @param configParams configuration parameters as a <code>Map</code>.
* The values in the map is <code>java.util.Set</code>,
* which contains one or more configuration parameters.
*
* @exception PolicyException if an error occurred during
* initialization of <code>Subject</code> instance
*/
/**
* Sets the names for the instance of the <code>Subject</code>
* object. The names are obtained from the <code>Policy</code> object,
* usually configured when a policy is created. For example
* in a Role implementation, this would be name of the role.
*
* @param names names selected for the instance of
* the user collection object.
*
* @exception InvalidNameException if the given names are not valid
*/
/**
* Determines if the user belongs to this instance
* of the <code>Subject</code> object.
* For example, a Role implementation
* would return <code>true</code> if the user belongs
* the specified role; <code>false</code> otherwise.
*
* @param token single-sign-on token of the user
*
* @return <code>true</code> if the user is member of the
* given subject; <code>false</code> otherwise.
*
* @exception SSOException if SSO token is not valid
* @exception PolicyException if an error occurred while
* checking if the user is a member of this subject
*/
throws SSOException, PolicyException;
/**
* Creates and returns a copy of this object.
*
* @return a copy of this object
*/
}