org.jsecurity.realm.text
Class PropertiesRealm

java.lang.Object
  org.jsecurity.realm.CachingRealm
      org.jsecurity.realm.AuthenticatingRealm
          org.jsecurity.realm.AuthorizingRealm
              org.jsecurity.realm.SimpleAccountRealm
                  org.jsecurity.realm.text.TextConfigurationRealm
                      org.jsecurity.realm.text.PropertiesRealm

All Implemented Interfaces:

Runnable, LogoutAware, Authorizer, PermissionResolverAware, CacheManagerAware, Realm, Destroyable, Initializable

public class PropertiesRealm
extends TextConfigurationRealm
implements Destroyable, Runnable

A subclass of SimpleAccountRealm that defers all logic to the parent class, but just enables Properties based configuration in addition to the parent class's String configuration.

This class allows processing of a single .properties file for user, role, and permission configuration.

For convenience, if the resourcePath attribute is not set, this class defaults to lookup the properties file definition from classpath:jsecurity-users.properties (root of the classpath). This allows you to use this implementation by simply defining this file at the classpath root, instantiating this class, and then calling init().

Or, you may of course specify any other file path using the url:, file:, or classpath: prefixes.

If none of these are specified, and the jsecurity-users.properties is not included at the root of the classpath, a default failsafe configuration will be used. This is not recommended as it only contains a few simple users and roles which are probably of little value to production applications.

The Properties format understood by this implementation must be written as follows:

Each line's key/value pair represents either a user-to-role(s) mapping or a role-to-permission(s) mapping.

The user-to-role(s) lines have this format:

user.username = password,role1,role2,...

Note that each key is prefixed with the token user. Each value must adhere to the the setUserDefinitions(String) JavaDoc.

The role-to-permission(s) lines have this format:

role.rolename = permissionDefinition1, permissionDefinition2, ...

where each key is prefixed with the token role. and the value adheres to the format specified in the setRoleDefinitions(String) JavaDoc.

Here is an example of a very simple properties definition that conforms to the above format rules and corresponding method JavaDocs: user.root = rootPassword,administrator
user.jsmith = jsmithPassword,manager,engineer,employee
user.abrown = abrownPassword,qa,employee
user.djones = djonesPassword,qa,contractor

role.administrator = org.jsecurity.authz.support.AllPermission
role.manager = com.domain.UserPermission,*,read,write;com.domain.FilePermission,/usr/local/emailManagers.sh,execute
role.engineer = com.domain.FilePermission,/usr/local/tomcat/bin/startup.sh,read,execute
role.employee = com.domain.IntranetPermission,useWiki
role.qa = com.domain.QAServerPermission,*,view,start,shutdown,restart;com.domain.ProductionServerPermission,*,view
role.contractor = com.domain.IntranetPermission,useTimesheet

Since:

0.2

Author:

Les Hazlewood, Jeremy Haile

Field Summary

protected long	fileLastModified
protected int	reloadIntervalSeconds
protected String	resourcePath
protected ExecutorService	scheduler
protected boolean	useXmlFormat

Fields inherited from class org.jsecurity.realm.SimpleAccountRealm

roles

Constructor Summary

PropertiesRealm()

PropertiesRealm(CacheManager cacheManager)

Method Summary

void	afterRoleCacheSet()
void	destroy() Called when this object is being destroyed, allowing any necessary cleanup of internal resources.
protected String	getName(String key, String prefix)
protected String	getRolename(String key)
protected String	getUsername(String key)
protected boolean	isRolename(String key)
protected boolean	isUsername(String key)
void	run()
void	setReloadIntervalSeconds(int reloadIntervalSeconds) Sets the interval in seconds at which the property file will be checked for changes and reloaded.
void	setResourcePath(String resourcePath) Sets the path of the properties file to load user, role, and permission information from.
void	setUseXmlFormat(boolean useXmlFormat) Determines whether or not the properties XML format should be used.
protected void	startReloadThread()

Methods inherited from class org.jsecurity.realm.text.TextConfigurationRealm

accountAndRoleCachesCreated, getRoleDefinitions, getUserDefinitions, onLogout, processDefinitions, processRoleDefinitions, processUserDefinitions, setRoleDefinitions, setUserDefinitions, toLines, toMap

Methods inherited from class org.jsecurity.realm.SimpleAccountRealm

accountExists, add, add, addAccount, addAccount, addRole, afterAuthorizationCacheSet, doGetAuthenticationInfo, doGetAuthorizationInfo, getAuthorizationCacheKey, getRole, getUser, initRoleCache, roleExists, toSet

Methods inherited from class org.jsecurity.realm.AuthorizingRealm

afterCacheManagerSet, checkPermission, checkPermission, checkPermission, checkPermissions, checkPermissions, checkPermissions, checkRole, checkRole, checkRoles, checkRoles, clearCachedAuthorizationInfo, getAuthorizationCache, getAuthorizationCacheName, getAuthorizationInfo, getPermissionResolver, hasAllRoles, hasRole, hasRole, hasRoles, hasRoles, init, initAuthorizationCache, isPermitted, isPermitted, isPermitted, isPermitted, isPermitted, isPermittedAll, isPermittedAll, isPermittedAll, setAuthorizationCache, setAuthorizationCacheName, setPermissionResolver

Methods inherited from class org.jsecurity.realm.AuthenticatingRealm

getAuthenticationInfo, getAuthenticationTokenClass, getCredentialsMatcher, setAuthenticationTokenClass, setCredentialsMatcher, supports

Methods inherited from class org.jsecurity.realm.CachingRealm

getCacheManager, getName, setCacheManager, setName

Methods inherited from class java.lang.Object

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

Field Detail

scheduler

protected ExecutorService scheduler

useXmlFormat

protected boolean useXmlFormat

resourcePath

protected String resourcePath

fileLastModified

protected long fileLastModified

reloadIntervalSeconds

protected int reloadIntervalSeconds

Constructor Detail

PropertiesRealm

public PropertiesRealm()

PropertiesRealm

public PropertiesRealm(CacheManager cacheManager)

Method Detail

afterRoleCacheSet

public void afterRoleCacheSet()

Overrides:

afterRoleCacheSet in class SimpleAccountRealm

destroy

public void destroy()

Description copied from interface: Destroyable

Called when this object is being destroyed, allowing any necessary cleanup of internal resources.

Specified by:

destroy in interface Destroyable

startReloadThread

protected void startReloadThread()

run

public void run()

Specified by:

run in interface Runnable

setUseXmlFormat

public void setUseXmlFormat(boolean useXmlFormat)

Determines whether or not the properties XML format should be used. For more information, see Properties.loadFromXML(java.io.InputStream)

Parameters:

useXmlFormat - true to use XML or false to use the normal format. Defaults to false.

setResourcePath

public void setResourcePath(String resourcePath)

Sets the path of the properties file to load user, role, and permission information from. The properties file will be loaded using ResourceUtils.getInputStreamForPath(String) so any convention recongized by that method is accepted here. For example, to load a file from the classpath use classpath:myfile.properties; to load a file from disk simply specify the full path; to load a file from a URL use url:www.mysite.com/myfile.properties.

Parameters:

resourcePath - the path to load the properties file from. This is a required property.

setReloadIntervalSeconds

public void setReloadIntervalSeconds(int reloadIntervalSeconds)

Sets the interval in seconds at which the property file will be checked for changes and reloaded. If this is set to zero or less, property file reloading will be disabled. If it is set to 1 or greater, then a separate thread will be created to monitor the propery file for changes and reload the file if it is updated.

Parameters:

reloadIntervalSeconds - the interval in seconds at which the property file should be examined for changes. If set to zero or less, reloading is disabled.

getName

protected String getName(String key,
                         String prefix)

isUsername

protected boolean isUsername(String key)

isRolename

protected boolean isRolename(String key)

getUsername

protected String getUsername(String key)

getRolename

protected String getRolename(String key)