Class Realm

  • All Implemented Interfaces:
    Comparable
    Direct Known Subclasses:
    BaseRealm

    @Contract
    public abstract class Realm
    extends Object
    implements Comparable
    javadoc
    Author:
    Harish Prabandham, Harpreet Singh, Jyri Virkki, Shing Wai Chan
    See Also:
    Principal
    • Constructor Detail

      • Realm

        protected Realm()
        The default constructor creates a realm which will later be initialized, either from properties or by deserializing.
    • Method Detail

      • getName

        public final String getName()
        Returns the name of this realm.
        Returns:
        realm name.
      • getDefaultDigestAlgorithm

        protected String getDefaultDigestAlgorithm()
      • setName

        protected final void setName​(String name)
        Assigns the name of this realm, and stores it in the cache of realms. Used when initializing a newly created in-memory realm object; if the realm already has a name, there is no effect.
        Parameters:
        name - name to be assigned to this realm.
      • toString

        public String toString()
        Returns the name of this realm.
        Overrides:
        toString in class Object
        Returns:
        name of realm.
      • compareTo

        public int compareTo​(Object realm)
        Compares a realm to another. The comparison first considers the authentication type, so that realms supporting the same kind of user authentication are grouped together. Then it compares realm realm names. Realms compare "before" other kinds of objects (i.e. there's only a partial order defined, in the case that those other objects compare themselves "before" a realm object).
        Specified by:
        compareTo in interface Comparable
      • instantiate

        public static Realm instantiate​(String name,
                                        String className,
                                        Properties props)
                                 throws BadRealmException
        Instantiate a Realm with the given name and properties using the Class name given. This method is used by iAS and not RI.
        Parameters:
        name - Name of the new realm.
        className - Java Class name of the realm to create.
        props - Properties containing values of the Property element from server.xml
        Throws:
        BadRealmException - If the requested realm cannot be instantiated.
      • instantiate

        public static Realm instantiate​(String name,
                                        String className,
                                        Properties props,
                                        String configName)
                                 throws BadRealmException
        Instantiate a Realm with the given name and properties using the Class name given. This method is used by iAS and not RI.
        Parameters:
        name - Name of the new realm.
        className - Java Class name of the realm to create.
        props - Properties containing values of the Property element from server.xml
        configName - the config to which this realm belongs
        Throws:
        BadRealmException - If the requested realm cannot be instantiated.
      • getRealmStatsProvier

        public static void getRealmStatsProvier()
      • updateInstance

        protected static void updateInstance​(Realm realm,
                                             String name)
        Replace a Realm instance. Can be used by a Realm subclass to replace a previously initialized instance of itself. Future getInstance requests will then obtain the new instance.

        Minimal error checking is done. The realm being replaced must already exist (instantiate() was previously called), the new instance must be fully initialized properly and it must of course be of the same class as the previous instance.

        Parameters:
        realm - The new realm instance.
        name - The (previously instantiated) name for this realm.
      • updateInstance

        protected static void updateInstance​(String configName,
                                             Realm realm,
                                             String name)
        Replace a Realm instance. Can be used by a Realm subclass to replace a previously initialized instance of itself. Future getInstance requests will then obtain the new instance.

        Minimal error checking is done. The realm being replaced must already exist (instantiate() was previously called), the new instance must be fully initialized properly and it must of course be of the same class as the previous instance.

        Parameters:
        realm - The new realm instance.
        name - The (previously instantiated) name for this realm.
      • getDefaultInstance

        public static Realm getDefaultInstance()
                                        throws NoSuchRealmException
        Convenience method which returns the Realm object representing the current default realm. Equivalent to getInstance(getDefaultRealm()).
        Returns:
        Realm representing default realm.
        Throws:
        NoSuchRealmException - if default realm does not exist
      • getDefaultRealm

        public static String getDefaultRealm()
        Returns the name of the default realm.
        Returns:
        Default realm name.
      • setDefaultRealm

        public static void setDefaultRealm​(String realmName)
        Sets the name of the default realm.
        Parameters:
        realmName - Name of realm to set as default.
      • setProperty

        public void setProperty​(String name,
                                String value)
        Set a realm property.
        Parameters:
        name - property name.
        value - property value.
      • getProperty

        public String getProperty​(String name)
        Get a realm property.
        Parameters:
        name - property name.
      • getProperties

        protected Properties getProperties()
        Return properties of the realm.
      • getJAASContext

        public String getJAASContext()
        Returns name of JAAS context used by this realm.

        The JAAS context is defined in server.xml auth-realm element associated with this realm.

        Returns:
        String containing JAAS context name.
      • getInstance

        public static Realm getInstance​(String name)
                                 throws NoSuchRealmException
        Returns the realm identified by the name which is passed as a parameter. This function knows about all the realms which exist; it is not possible to store (or create) one which is not accessible through this routine.
        Parameters:
        name - identifies the realm
        Returns:
        the requested realm
        Throws:
        NoSuchRealmException - if the realm is invalid
        BadRealmException - if realm data structures are bad
      • getInstance

        public static Realm getInstance​(String configName,
                                        String name)
                                 throws NoSuchRealmException
        Returns the realm identified by the name which is passed as a parameter. This function knows about all the realms which exist; it is not possible to store (or create) one which is not accessible through this routine.
        Parameters:
        name - identifies the realm
        Returns:
        the requested realm
        Throws:
        NoSuchRealmException - if the realm is invalid
        BadRealmException - if realm data structures are bad
      • getRealmNames

        public static Enumeration getRealmNames()
        Returns the names of accessible realms.
        Returns:
        set of realm names
      • init

        protected void init​(Properties props)
                     throws BadRealmException,
                            NoSuchRealmException
        Initialize a realm with some properties. This can be used when instantiating realms from their descriptions. This method may only be called a single time.
        Parameters:
        props - initialization parameters used by this realm.
        Throws:
        BadRealmException - if the configuration parameters identify a corrupt realm
        NoSuchRealmException - if the configuration parameters specify a realm which doesn't exist
      • isValidRealm

        public static boolean isValidRealm​(String name)
        Checks if the given realm name is loaded/valid.
        Parameters:
        String - name of the realm to check.
        Returns:
        true if realm present, false otherwise.
      • isValidRealm

        public static boolean isValidRealm​(String configName,
                                           String name)
        Checks if the given realm name is loaded/valid.
        Parameters:
        String - name of the realm to check.
        Returns:
        true if realm present, false otherwise.
      • addAssignGroups

        protected String[] addAssignGroups​(String[] grps)
        Add assign groups to given Vector of groups. To be used by getGroupNames.
        Parameters:
        grps -
      • getAuthType

        public abstract String getAuthType()
        Returns a short (preferably less than fifteen characters) description of the kind of authentication which is supported by this realm.
        Returns:
        description of the kind of authentication that is directly supported by this realm.
      • getAuthenticationHandler

        public abstract AuthenticationHandler getAuthenticationHandler()
        Returns an AuthenticationHandler object which can be used to authenticate within this realm.
        Returns:
        An AuthenticationHandler object for this realm.
      • getUserNames

        public abstract Enumeration getUserNames()
                                          throws BadRealmException
        Returns names of all the users in this particular realm.
        Returns:
        enumeration of user names (strings)
        Throws:
        BadRealmException - if realm data structures are bad
      • getGroupNames

        public abstract Enumeration getGroupNames()
                                           throws BadRealmException
        Returns names of all the groups in this particular realm.
        Returns:
        enumeration of group names (strings)
        Throws:
        BadRealmException - if realm data structures are bad
      • refresh

        public abstract void refresh()
                              throws BadRealmException
        Refreshes the realm data so that new users/groups are visible.
        Throws:
        BadRealmException - if realm data structures are bad
      • refresh

        public void refresh​(String configName)
                     throws BadRealmException
        Refreshes the realm data so that new users/groups are visible.
        Throws:
        BadRealmException - if realm data structures are bad
      • updateUser

        public abstract void updateUser​(String name,
                                        String newName,
                                        char[] password,
                                        String[] groups)
                                 throws NoSuchUserException,
                                        BadRealmException,
                                        IASSecurityException
        Update data for an existing user. User must exist.
        Parameters:
        name - Current name of the user to update.
        newName - New name to give this user. It can be the same as the original name. Otherwise it must be a new user name which does not already exist as a user.
        password - Cleartext password for the user. If non-null the user password is changed to this value. If null, the original password is retained.
        groupList - List of groups to which user belongs.
        Throws:
        BadRealmException - If there are problems adding user.
        NoSuchUserException - If user does not exist.
        IASSecurityException
      • supportsUserManagement

        public abstract boolean supportsUserManagement()
        Returns:
        true if the realm implementation support User Management (add,remove,update user)