com.sun.enterprise.security.auth.realm

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 and Description
protected static Logger	_logger
protected GroupMapper	groupMapper
static String	PARAM_GROUP_MAPPING

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Realm() The default constructor creates a realm which will later be initialized, either from properties or by deserializing.

Method Summary

Modifier and Type	Method and 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 to
static 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 storage
abstract 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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

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

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()

instantiate

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

getMappedGroupNames

protected ArrayList<String> getMappedGroupNames(String group)

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 exist

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

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 operation

NoSuchUserException

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