Class Realm
java.lang.Object
com.sun.enterprise.security.auth.realm.Realm
- All Implemented Interfaces:
Comparable
- Direct Known Subclasses:
BaseRealm
javadoc
- Author:
- Harish Prabandham, Harpreet Singh, Jyri Virkki, Shing Wai Chan
- See Also:
-
Field Summary
Modifier and TypeFieldDescriptionprotected static final Logger
protected GroupMapper
static final String
-
Constructor Summary
ModifierConstructorDescriptionprotected
Realm()
The default constructor creates a realm which will later be initialized, either from properties or by deserializing. -
Method Summary
Modifier and TypeMethodDescriptionprotected String[]
addAssignGroups
(String[] grps) Add assign groups to given Vector of groups.abstract void
Adds new user to file realm.int
Compares a realm to another.abstract AuthenticationHandler
Returns an AuthenticationHandler object which can be used to authenticate within this realm.abstract String
Returns a short (preferably less than fifteen characters) description of the kind of authentication which is supported by this realm.protected String
static Realm
Convenience method which returns the Realm object representing the current default realm.static String
Returns the name of the default realm.abstract Enumeration<String>
Returns names of all the groups in this particular realm.abstract Enumeration<String>
getGroupNames
(String username) Returns the name of all the groups that this user belongs tostatic Realm
getInstance
(String name) Returns the realm identified by the name which is passed as a parameter.static Realm
getInstance
(String configName, String name) Returns the realm identified by the name which is passed as a parameter.Returns name of JAAS context used by this realm.getMappedGroupNames
(String group) final String
getName()
Returns the name of this realm.protected Properties
Return properties of the realm.getProperty
(String name) Get a realm property.static Enumeration
Returns the names of accessible realms.static void
abstract User
Returns the information recorded about a particular named user.abstract Enumeration
Returns names of all the users in this particular realm.protected void
init
(Properties props) Initialize a realm with some properties.static Realm
instantiate
(String realmName, File f) Deprecated.static Realm
instantiate
(String name, String className, Properties props) Instantiate a Realm with the given name and properties using the Class name given.static Realm
instantiate
(String name, String className, Properties props, String configName) Instantiate a Realm with the given name and properties using the Class name given.static boolean
isValidRealm
(String name) Checks if the given realm name is loaded/valid.static boolean
isValidRealm
(String configName, String name) Checks if the given realm name is loaded/valid.abstract void
persist()
Persist the realm data to permanent storageabstract void
refresh()
Refreshes the realm data so that new users/groups are visible.void
Refreshes the realm data so that new users/groups are visible.abstract void
removeUser
(String name) Remove user from file realm.static void
setDefaultRealm
(String realmName) Sets the name of the default realm.protected final void
Assigns the name of this realm, and stores it in the cache of realms.void
setProperty
(String name, String value) Set a realm property.abstract boolean
toString()
Returns the name of this realm.static void
unloadInstance
(String realmName) Remove realm with given name from cache.static void
unloadInstance
(String configName, String realmName) Remove realm with given name from cache.protected static void
updateInstance
(Realm realm, String name) Replace a Realm instance.protected static void
updateInstance
(String configName, Realm realm, String name) Replace a Realm instance.abstract void
updateUser
(String name, String newName, char[] password, String[] groups) Update data for an existing user.
-
Field Details
-
PARAM_GROUP_MAPPING
- See Also:
-
groupMapper
-
_logger
-
-
Constructor Details
-
Realm
protected Realm()The default constructor creates a realm which will later be initialized, either from properties or by deserializing.
-
-
Method Details
-
getName
Returns the name of this realm.- Returns:
- realm name.
-
getDefaultDigestAlgorithm
-
setName
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
Returns the name of this realm. -
compareTo
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 interfaceComparable
-
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.xmlconfigName
- the config to which this realm belongs- Throws:
BadRealmException
- If the requested realm cannot be instantiated.
-
getRealmStatsProvier
public static void getRealmStatsProvier() -
instantiate
@Deprecated public static Realm instantiate(String realmName, File f) throws NoSuchRealmException, BadRealmException, FileNotFoundException Deprecated.Instantiate a Realm with the given name, loading properties from the given file. This method is only used by RI and is not called anywhere in iAS. Note : this method stands unused in V3.1 but keeping it since it is a public method.- Parameters:
realmName
- Name of the new realm.f
- File containing Properties for the new realm.- Throws:
NoSuchRealmException
BadRealmException
FileNotFoundException
-
updateInstance
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
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
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
Returns the name of the default realm.- Returns:
- Default realm name.
-
setDefaultRealm
Sets the name of the default realm.- Parameters:
realmName
- Name of realm to set as default.
-
unloadInstance
Remove realm with given name from cache.- Parameters:
realmName
-- Throws:
NoSuchRealmException
-
unloadInstance
Remove realm with given name from cache.- Parameters:
realmName
-- Throws:
NoSuchRealmException
-
setProperty
Set a realm property.- Parameters:
name
- property name.value
- property value.
-
getProperty
Get a realm property.- Parameters:
name
- property name.
-
getProperties
Return properties of the realm. -
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
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 invalidBadRealmException
- if realm data structures are bad
-
getInstance
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 invalidBadRealmException
- if realm data structures are bad
-
getRealmNames
Returns the names of accessible realms.- Returns:
- set of realm names
-
init
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 realmNoSuchRealmException
- if the configuration parameters specify a realm which doesn't exist
-
isValidRealm
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
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
Add assign groups to given Vector of groups. To be used by getGroupNames.- Parameters:
grps
-
-
getMappedGroupNames
-
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
Returns an AuthenticationHandler object which can be used to authenticate within this realm.- Returns:
- An AuthenticationHandler object for this realm.
-
getUserNames
Returns names of all the users in this particular realm.- Returns:
- enumeration of user names (strings)
- Throws:
BadRealmException
- if realm data structures are bad
-
getUser
Returns the information recorded about a particular named user.- Parameters:
name
- name of the user whose information is desired- Returns:
- the user object
- Throws:
NoSuchUserException
- if the user doesn't existBadRealmException
- if realm data structures are bad
-
getGroupNames
Returns names of all the groups in this particular realm.- Returns:
- enumeration of group names (strings)
- Throws:
BadRealmException
- if realm data structures are bad
-
getGroupNames
public abstract Enumeration<String> getGroupNames(String username) throws InvalidOperationException, NoSuchUserException Returns the name of all the groups that this user belongs to- Parameters:
username
- name of the user in this realm whose group listing is needed.- Returns:
- enumeration of group names (strings)
- Throws:
InvalidOperationException
- thrown if the realm does not support this operation - e.g. Certificate realm does not support this operationNoSuchUserException
-
refresh
Refreshes the realm data so that new users/groups are visible.- Throws:
BadRealmException
- if realm data structures are bad
-
refresh
Refreshes the realm data so that new users/groups are visible.- Throws:
BadRealmException
- if realm data structures are bad
-
addUser
public abstract void addUser(String name, char[] password, String[] groupList) throws BadRealmException, IASSecurityException Adds new user to file realm. User cannot exist already.- Parameters:
name
- User name.password
- Cleartext password for the user.groupList
- List of groups to which user belongs.- Throws:
BadRealmException
- If there are problems adding user.IASSecurityException
-
removeUser
Remove user from file realm. User must exist.- Parameters:
name
- User name.- Throws:
NoSuchUserException
- If user does not exist.BadRealmException
-
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)
-
persist
Persist the realm data to permanent storage- Throws:
BadRealmException
-