Package com.iplanet.ums

Class PersistentObject

    • Constructor Detail

      • PersistentObject

        protected PersistentObject()
        Default Constructor

      • PersistentObject

        public PersistentObject​(CreationTemplate template,
                        AttrSet attrSet)
                 throws UMSException
        Constructor for in memory object to be added to the system. You can make the object persistent two ways:

        1) call add on parent object (recommended)

        2) call save(...) method after all attributes for in memory object are set up properly.

        Parameters:
        template - Object creation template. The template holds all the default values such as objectclass and requirted attributes to be supplied
        attrSet - Attribute set to construct the object in memory
        Throws:
        UMSException - for failure to construct the object. The given attrSet needs to provide the required attribute(s) defined in template

    • Method Detail

      • getAttribute

        public Attr getAttribute​(String attrName)
        Gets an attribute of the object. If the attribute is not in memory, the object is refreshed from persistent storage.
        Parameters:
        attrName - Name of the attribute to be queried
        Returns:
        Attribute value

      • getAttribute

        public Attr getAttribute​(String attrName,
                         Locale locale)
                  throws UMSException
        Gets an attribute value with a given locale
        Parameters:
        attrName - Name of the attribute
        locale - Locale of attribute to be retrieved
        Returns:
        Attribute value with the specified locale. May return null if the attribute with locale not found. No fallback mechanism is provided
        Throws:
        UMSException
        See Also:
        getAttribute(String)

      • getAttributes

        public AttrSet getAttributes​(String[] attrs,
                             boolean cacheOnly)
                      throws UMSException
        Gets attribute values
        Parameters:
        attrs - Array of strings representing attribute names
        cacheOnly - if true, read attributes from cache only without contacting data stroe
        Returns:
        attribute value set for the return values
        Throws:
        UMSException
        See Also:
        getAttribute(String)

      • getAttributes

        public AttrSet getAttributes​(String[] attrNames,
                             Locale locale)
                      throws UMSException
        Returns attribute values with a specified locale.
        Parameters:
        attrNames - Attribute names
        locale - Locale of the attributes to be queried
        Returns:
        Attribute value set. May return null value for attribute(s) with unfound locale. No fallback mechanism is provided.
        Throws:
        UMSException
        See Also:
        getAttribute(String)

      • setAttribute

        public void setAttribute​(Attr attr)
        Set an attribute value for the entity.

        IMPORTANT: To make the changes persistent, you need to call the save method to save the changes.

        Parameters:
        attr - Attribute and value

      • setAttribute

        public void setAttribute​(Attr attr,
                         Locale locale)
        Sets an attribute value with a given locale for the entity.

        IMPORTANT: To make the changes persistent, you need to call the save method to save the changes.

        Parameters:
        attr - Attribute and value
        locale - Intended locale of the attribute to be set

      • changePassword

        public void changePassword​(String entryDN,
                           String attrName,
                           String oldPassword,
                           String newPassword)
                    throws UMSException
        Changes user password.
        Parameters:
        entryDN - DN of the profile whose template is to be set
        attrName - password attribute name
        oldPassword - old password
        newPassword - new password
        Throws:
        AMException - if an error occurs when changing user password
        SSOException - If user's single sign on token is invalid.
        UMSException

      • removeAttribute

        public void removeAttribute​(Attr attr)
        Removes attribute value for the entity.

        IMPORTANT: To make the changes persistent, you need to call the save method to save the changes.

        Parameters:
        attr - Attribute to be removed

      • getAttributeNames

        public String[] getAttributeNames()
        Gets names for all available attributes for this entity
        Returns:
        Array of strings representing attribute names

      • modify

        public void modify​(Collection<org.forgerock.opendj.ldap.Modification> modSet)
        Modifies attribute values for the entity.

        IMPORTANT: To make the changes persistent, you need to call the save method to save the changes.

        Parameters:
        modSet - Set of modification of attributes
        See Also:
        ModSet

      • modify

        public void modify​(Attr attr,
                   org.forgerock.opendj.ldap.ModificationType modificationType)
        Modifies the values of a single attribute for the entity.

        IMPORTANT: To make the changes persistent, you need to call the save method to save the changes.

        Parameters:
        attr - Attribute value to be modified
        modificationType - Operation type in the modification. Input values include 
                       ModificationType.ADD,
               ModificationType.DELETE,
               ModificationType.REPLACE,
               ModificationType.INCREMENT
        See Also:
        ModSet

      • modify

        public void modify​(String attrName,
                   String value,
                   org.forgerock.opendj.ldap.ModificationType modificationType)
        Modify a single attribute for the entity.

        IMPORTANT: To make the changes persistent, you need to call the save method to save the changes.

        Parameters:
        attrName - Attribute name of the attribute to be modified
        value - String value of the attribute
        modificationType - Operation type in the modification. Input values include 
                           ModificationType.ADD,
                   ModificationType.DELETE,
                   ModificationType.REPLACE,
                   ModificationType.INCREMENT

      • getGuid

        public Guid getGuid()
        Get GUID of the given entity
        Returns:
        the GUID.

      • save

        public void save()
          throws AccessRightsException,
                 EntryNotFoundException,
                 UMSException
        Save the modification(s) to the object. Save the changes made so far for the persistent object. In other words, make the changes persistent for the object.

        This save method takes no parameter. You use this save method when the object is already instantiated. For example, 

         User user = (User) UMSObject.getObject(principal, id);
 user.modify("telephonenumber", 
      "650.937.4444", ModificationType.REPLACE);
 user.save();

        Throws:
        AccessRightsException - if an access rights exception occurs.
        EntryNotFoundException - if the entry is not found
        UMSException - on failure to save to persistent storage

      • getNamingAttribute

        public String getNamingAttribute()
        Gets the attribute name that specifies the ID (or RDN in terms of DN in ldap) component in an object. Subclasses may choose to override this function. For instance, User takes either "uid" or "cn" for its identification

        Returns:
        Attribute name for identification

      • getParentObject

        public PersistentObject getParentObject()
                                 throws UMSException
        Gets the parent object
        Returns:
        PersistentObject representing the parent object
        Throws:
        UMSException - on failure instantiating the parent object

      • addChild

        public void addChild​(PersistentObject object)
              throws AccessRightsException,
                     EntryAlreadyExistsException,
                     UMSException
        Adds a child object to the persistent object container. All persistent objects can add objects as a container. To override this behavior or impose restrictions override the add method in a subclass so that e.g. User.add( object ) is restricted or disallowed in certain ways.
        Parameters:
        object - Child object to be added to this persistent container.
        Throws:
        AccessRightsException - if an access rights exception occurs.
        EntryAlreadyExistsException - if the entry already exists.
        UMSException - if fail to add the given child object to the container. Possible causes include EntryAlreadyExists, AccessRights violation.

      • removeChild

        public void removeChild​(PersistentObject object)
                 throws AccessRightsException,
                        EntryNotFoundException,
                        UMSException
        Removes a child object from a persistent object container. It is important for constraints to be applied in overriding this method in subclasses of PersistentObject. For example, Organization may choose not to allow remove( object ) when object is an organization.
        Parameters:
        object - Child object to be removed.
        Throws:
        AccessRightsException - if an access rights exception occurs.
        EntryNotFoundException - if the entry is not found.
        UMSException - if fail to remove the child object. Possible causes includes EntryNotFount, AccessRights violation etc.

      • removeChild

        public void removeChild​(Guid childGuid)
                 throws AccessRightsException,
                        EntryNotFoundException,
                        UMSException
        Removes an object given its unique ID. This method expects the given child ID is a descendant (something being contained) in "this" object
        Parameters:
        childGuid - Unique entry identification for the child to be removed.
        Throws:
        AccessRights - if an access rights exception occurs.
        EntryNotFoundException - if the entry is not found.
        UMSException - if failure to remove the entry from the persistent store. Possible causes include AccessRights violation, EntryNotFound etc.
        AccessRightsException

      • toString

        public String toString()
        Gets a string representation of the object
        Overrides:
        toString in class Object
        Returns:
        String representation of the object

      • getParentGuid

        public Guid getParentGuid()
        Gets the parent guid
        Specified by:
        getParentGuid in interface ISearch
        Returns:
        String representation of the parent guid

      • getChildren

        public SearchResults getChildren​(SearchTemplate template,
                                 SearchControl searchControl)
                          throws UMSException
        Gets all immediate children under current node based on search criteria specified in template, and returns attributes specified there. Search behavior is controlled by searchControl.

        Returning attributes are determined by the search template

        Specified by:
        getChildren in interface ISearch
        Parameters:
        template - Search template
        searchControl - Search control, use default setting if searchControl == null
        Throws:
        UMSException - on failure with searching

      • search

        public SearchResults search​(SearchTemplate template,
                            SearchControl searchControl)
                     throws UMSException
        Gets the attributes specified in the template for all objects at the current level and below which match the search filter in the template. Search behavior is controlled by searchControl.

        Specified by:
        search in interface ISearch
        Parameters:
        template - Search template
        searchControl - Search control, use default setting if searchControl == null
        Throws:
        UMSException - on failure to search

      • getDN

        public String getDN()
        Gets the DN of the entity
        Returns:
        String representing the distinguished name of the entry

      • setGuid

        protected void setGuid​(Guid guid)
        Sets the GUID of the entity; used within the package
        Parameters:
        guid - String representation of guid

      • setAttrSet

        protected void setAttrSet​(AttrSet attrSet)
        Sets the attribute set
        Parameters:
        attrSet - The attribute set to be assigned as a reference (not a deep copy)

      • getAttrSet

        protected AttrSet getAttrSet()
        Gets the attribute set as a reference, not a deep copy
        Returns:
        The in-memory attribute set

      • idToDN

        public static String idToDN​(String namingAttribute,
                            String name,
                            String[] parentID)
        Maps to a DN from naming attribute value of a persistent object.
        Parameters:
        namingAttribute - Naming attribute of the object.
        name - Naming attribute value of the object.
        parentID - Array of its parent names, all assumed to take o as the naming attributes.

      • isMemberOf

        public boolean isMemberOf​(IMembership im)
                   throws UMSException
        Checks if this object is a member of an IMembership. Roles and Groups implement IMembership
        Parameters:
        im - Role or Group against which the membership is to be checked
        Returns:
        true if this object is a member of the IMembership, false otherwise
        Throws:
        UMSException - propagates any exception from the datalayer

      • getRoles

        public Collection getRoles()
                    throws UMSException
        Gets the list of GUIDS roles assosciated with this object
        Returns:
        list that lets iterating over role GUIDs
        Throws:
        UMSException - propagates any exception from the datalayer

      • addAttributeValue

        public static void addAttributeValue​(SSOToken token,
                                     Guid guid,
                                     String name,
                                     String value)
                              throws UMSException
        Adds value for an attribute and saves the change in the database.
        Parameters:
        token - Authenticated prinicpal's single sign on token.
        guid - Identifiation of the entry to which to add the attribute value.
        name - Name of the attribute to which value is being added.
        value - Value to be added to the attribute.
        Throws:
        UMSException - if any exception from the data layer.

      • removeAttributeValue

        public static void removeAttributeValue​(SSOToken token,
                                        Guid guid,
                                        String name,
                                        String value)
                                 throws UMSException
        Removes value for an attribute and saves the change in the database.
        Parameters:
        token - Authenticated prinicpal's single sign on token.
        guid - Identification of the entry from which to remove the attribute value.
        name - Name of the attribute from which value is being removed.
        value - Value to be removed from the attribute.
        Throws:
        UMSException - if any exception from the data layer.

      • isPersistent

        protected boolean isPersistent()
        Check if the object is persistent in the system
        Returns:
        true if the object is persistent in the system and false otherwise