Class Realm
- java.lang.Object
-
- com.sun.enterprise.security.auth.realm.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
-
-
Field Summary
Fields Modifier and Type Field Description protected static Logger
_logger
protected GroupMapper
groupMapper
static String
PARAM_GROUP_MAPPING
-
Constructor Summary
Constructors Modifier Constructor Description protected
Realm()
The default constructor creates a realm which will later be initialized, either from properties or by deserializing.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods Modifier and Type Method Description protected String[]
addAssignGroups(String[] grps)
Add assign groups to given Vector of groups.abstract void
addUser(String name, char[] password, String[] groupList)
Adds new user to file realm.int
compareTo(Object realm)
Compares a realm to another.abstract AuthenticationHandler
getAuthenticationHandler()
Returns an AuthenticationHandler object which can be used to authenticate within this realm.abstract String
getAuthType()
Returns a short (preferably less than fifteen characters) description of the kind of authentication which is supported by this realm.protected String
getDefaultDigestAlgorithm()
static Realm
getDefaultInstance()
Convenience method which returns the Realm object representing the current default realm.static String
getDefaultRealm()
Returns the name of the default realm.abstract Enumeration
getGroupNames()
Returns names of all the groups in this particular realm.abstract Enumeration
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.String
getJAASContext()
Returns name of JAAS context used by this realm.protected ArrayList<String>
getMappedGroupNames(String group)
String
getName()
Returns the name of this realm.protected Properties
getProperties()
Return properties of the realm.String
getProperty(String name)
Get a realm property.static Enumeration
getRealmNames()
Returns the names of accessible realms.static void
getRealmStatsProvier()
abstract User
getUser(String name)
Returns the information recorded about a particular named user.abstract Enumeration
getUserNames()
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
refresh(String configName)
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 void
setName(String name)
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
supportsUserManagement()
String
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 Detail
-
PARAM_GROUP_MAPPING
public static final String PARAM_GROUP_MAPPING
- See Also:
- Constant Field Values
-
groupMapper
protected GroupMapper groupMapper
-
_logger
protected static final Logger _logger
-
-
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.
-
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 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
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.
-
unloadInstance
public static void unloadInstance(String realmName) throws NoSuchRealmException
Remove realm with given name from cache.- Parameters:
realmName
-- Throws:
NoSuchRealmException
-
unloadInstance
public static void unloadInstance(String configName, String realmName) throws NoSuchRealmException
Remove realm with given name from cache.- Parameters:
realmName
-- Throws:
NoSuchRealmException
-
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 invalidBadRealmException
- 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 invalidBadRealmException
- 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 realmNoSuchRealmException
- 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
-
getUser
public abstract User getUser(String name) throws NoSuchUserException, BadRealmException
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
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
-
getGroupNames
public abstract Enumeration 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
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
-
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
public abstract void removeUser(String name) throws NoSuchUserException, BadRealmException
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
public abstract void persist() throws BadRealmException
Persist the realm data to permanent storage- Throws:
BadRealmException
-
-