com.sun.identity.policy

Class Subjects

java.lang.Object

com.sun.identity.policy.Subjects

public class Subjects
extends Object

The class Subjects provides methods to maintain a collection of Subject objects that can be applied to a policy. This class provides methods to add, replace and remove Subject objects from this users collection. The Policy object provides methods to set Subjects, which identifies users to whom the the policy applies.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Subjects() Constructor used by the Policy object to get a default instance of the Subjects
protected	Subjects(PolicyManager pm, Node usersNode) Constructor used by Policy to obtain an instance of Subjects from the XML document
	Subjects(String name, String description) Constructor to obtain an instance of Subjects to hold collection of users represented as Subject

Method Summary

Modifier and Type	Method and Description
void	addSubject(String subjectName, Subject subject) Adds a Subject object to the this instance of user collection.
void	addSubject(String subjectName, Subject subject, boolean exclusive) Adds a Subject object to the this instance of user collection.
void	addSubject(Subject subject) Adds a Subject object to the this instance of user collection.
Object	clone() Returns a new copy of this object with the identical set of user collections (subjects).
boolean	equals(Object o) Checks if two Subjects are identical.
String	getDescription() Returns the description for the collection of users represented as Subject
String	getName() Returns the name for the collection of users represented as Subject
Subject	getSubject(String subjectName) Returns the Subject object associated with the given subject name.
String	getSubjectName(Subject subject) Returns the name associated with the given subject object.
Set	getSubjectNames() Returns the names of Subject objects contained in this object.
boolean	isMember(SSOToken token) Checks if the given user (using SSOToken) belongs to any of the subjects contained in this user collection (subjects).
boolean	isRealmSubject(String subjectName) Checks if the subject is a reference to a Subject defined at the realm.
boolean	isSubjectExclusive(String subjectName) Checks if the subject is exclusive.
Subject	removeSubject(String subjectName) Removes the Subject object identified by the subject name.
Subject	removeSubject(Subject subject) Removes the Subject object identified by object's equals method.
void	replaceSubject(String subjectName, Subject subject) Replaces an existing subject object having the same name with the new one.
void	replaceSubject(String subjectName, Subject subject, boolean exclusive) Replaces an existing subject object having the same name with the new one.
void	setDescription(String description) Sets the description for this instance of the Subjects which contains a collection of users respresented as Subject.
void	setName(String name) Sets the name for this instance of the Subjects which contains a collection of users respresented as Subject.
String	toString() Returns XML string representation of the subject (user collection) object.
protected String	toXML() Returns XML string representation of the subject (user collection) object.

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Subjects

protected Subjects()

Constructor used by the Policy object to get a default instance of the Subjects

Subjects

protected Subjects(PolicyManager pm,
                   Node usersNode)
            throws InvalidFormatException,
                   InvalidNameException,
                   NameNotFoundException,
                   PolicyException

Constructor used by Policy to obtain an instance of Subjects from the XML document

Parameters:

usersNode - node that repersents the Subjects

Throws:

InvalidFormatException - if the node passed in does not conform to expected format

InvalidNameException

NameNotFoundException

PolicyException - if can not construct Subjects

Subjects

public Subjects(String name,
                String description)

Constructor to obtain an instance of Subjects to hold collection of users represented as Subject

Parameters:

name - name for the collection of Subject

description - user friendly description for the collection of Subject

Method Detail

getName

public String getName()

Returns the name for the collection of users represented as Subject

Returns:

name of the collection of subjects

getDescription

public String getDescription()

Returns the description for the collection of users represented as Subject

Returns:

description for the collection of subjects

setName

public void setName(String name)

Sets the name for this instance of the Subjects which contains a collection of users respresented as Subject.

Parameters:

name - for the collection of subjects

setDescription

public void setDescription(String description)

Sets the description for this instance of the Subjects which contains a collection of users respresented as Subject.

Parameters:

description - description for the collection subjects

getSubjectNames

public Set getSubjectNames()

Returns the names of Subject objects contained in this object.

Returns:

names of Subject contained in this object

getSubject

public Subject getSubject(String subjectName)
                   throws NameNotFoundException

Returns the Subject object associated with the given subject name.

Parameters:

subjectName - name of the subject object

Returns:

subject object corresponding to subject name

Throws:

NameNotFoundException - if a subject with the given name is not present

addSubject

public void addSubject(Subject subject)
                throws NameAlreadyExistsException

Adds a Subject object to the this instance of user collection. Since the name is not provided it will be dynamically assigned such that it is unique within this instance of the user collection. However if a subject entry with the same name already exists in the user collection NameAlreadyExistsException will be thrown. The subject is added as a normal (non exclusive) subject. So, policy will apply to members of the subject.

Parameters:

subject - instance of the subject object added to this collection

Throws:

NameAlreadyExistsException - throw if a subject object is present with the same name

addSubject

public void addSubject(String subjectName,
                       Subject subject)
                throws NameAlreadyExistsException

Adds a Subject object to the this instance of user collection. If another subject with the same name already exists in the user collection NameAlreadyExistsException will be thrown. The subject is added as a normal (non exclusive) subject. So, policy will apply to members of the subject.

Parameters:

subjectName - name for the subject instance

subject - instance of the subject object added to this collection

Throws:

NameAlreadyExistsException - if a subject object is present with the same name

addSubject

public void addSubject(String subjectName,
                       Subject subject,
                       boolean exclusive)
                throws NameAlreadyExistsException

Adds a Subject object to the this instance of user collection. If another subject with the same name already exists in the user collection NameAlreadyExistsException will be thrown.

Parameters:

subjectName - name for the subject instance

subject - instance of the subject object added to this collection

exclusive - boolean flag indicating whether the subject is to be exclusive subject. If subject is exclusive, policy applies to users who are not members of the subject. Otherwise, policy applies to members of the subject.

Throws:

NameAlreadyExistsException - if a subject object is present with the same name

replaceSubject

public void replaceSubject(String subjectName,
                           Subject subject)
                    throws NameNotFoundException

Replaces an existing subject object having the same name with the new one. If a Subject with the given name does not exist, NameNotFoundException will be thrown. The subject is replaced as a normal (non exclusive) subject. So, policy will apply to members of the subject.

Parameters:

subjectName - name for the subject instance

subject - instance of the subject object that will replace another subject object having the given name

Throws:

NameNotFoundException - if a subject instance with the given name is not present

replaceSubject

public void replaceSubject(String subjectName,
                           Subject subject,
                           boolean exclusive)
                    throws NameNotFoundException

Replaces an existing subject object having the same name with the new one. If a Subject with the given name does not exist, NameNotFoundException will be thrown.

Parameters:

subjectName - name for the subject instance

subject - instance of the subject object that will replace another subject object having the given name

exclusive - boolean flag indicating whether the subject is to be exclusive subject. If subject is exclusive, policy applies to users who are not members of the subject. Otherwise, policy applies to members of the subject.

Throws:

NameNotFoundException - if a subject instance with the given name is not present

removeSubject

public Subject removeSubject(String subjectName)

Removes the Subject object identified by the subject name. If a subject instance with the given name does not exist, the method will return silently.

Parameters:

subjectName - name of the subject instance that will be removed from the user collection

Returns:

the subject that was just removed

removeSubject

public Subject removeSubject(Subject subject)

Removes the Subject object identified by object's equals method. If a subject instance does not exist, the method will return silently.

Parameters:

subject - subject object that will be removed from the user collection

Returns:

the subject that was just removed

isSubjectExclusive

public boolean isSubjectExclusive(String subjectName)
                           throws NameNotFoundException

Checks if the subject is exclusive. If subject is exclusive, policy applies to users who are not members of the subject. Otherwise, policy applies to members of the subject.

Parameters:

subjectName - name of the subject

Returns:

true if the subject is exclusive, false otherwise

Throws:

NameNotFoundException - if the subject with the given subjectName does not exist in the policy

isRealmSubject

public boolean isRealmSubject(String subjectName)
                       throws NameNotFoundException

Checks if the subject is a reference to a Subject defined at the realm.

Parameters:

subjectName - name of the subject

Returns:

true if the subject is a reference to a Subject definet at the realm, false otherwise

Throws:

NameNotFoundException - if the subject with the given subjectName does not exist in the policy

getSubjectName

public String getSubjectName(Subject subject)

Returns the name associated with the given subject object. It uses the equals method on the subject to determine equality. If a subject instance that matches the given subject object is not present, the method returns null.

Parameters:

subject - subject object for which this method will return its associated name

Returns:

user friendly name given to the subject object; null if not present

equals

public boolean equals(Object o)

Checks if two Subjects are identical. Two subjects (or user collections) are identical only if both have the same set of Subject objects.

Overrides:

equals in class Object

Parameters:

o - object againt which this subjects object will be checked for equality

Returns:

true if all the subjects match; false otherwise

clone

public Object clone()

Returns a new copy of this object with the identical set of user collections (subjects).

Overrides:

clone in class Object

Returns:

a copy of this object with identical values

isMember

public boolean isMember(SSOToken token)
                 throws SSOException,
                        PolicyException

Checks if the given user (using SSOToken) belongs to any of the subjects contained in this user collection (subjects). In the current implementation it is sufficient if the user belongs to one of the subject objects, however in the future it can be extended to have complex logical operations.

Parameters:

token - single-sign-on token of the user

Returns:

true if the user is memeber of one of the subjects; false otherwise.

Throws:

SSOException - if SSO token is not valid

PolicyException - if an error occured while checking if the user is a member of one of subjects

toString

public String toString()

Returns XML string representation of the subject (user collection) object.

Overrides:

toString in class Object

Returns:

xml string representation of this object

toXML

protected String toXML()

Returns XML string representation of the subject (user collection) object.

Returns:

xml string representation of this object