Package com.sun.identity.policy

Class 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 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

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addSubject​(Subject subject)
      Adds a Subject object to the this instance of user collection.
      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.
      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​(Subject subject)
      Removes the Subject object identified by object's equals method.
      Subject removeSubject​(String subjectName)
      Removes the Subject object identified by the subject name.
      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.

    • 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