oracle.security.jazn.realm
Interface RoleManager

public interface RoleManager

Interface RoleManager defines the APIs for managing roles in a realm.

The following table shows the predefined properties applicable for a LDAP-based Role Manager. (Note: the property names are tentative and thus are subject to change).

Property names	Descriptions
jazn.realm.roles.ldap.isExternal	A flag, true or false, to specify whether the roles are external to JAZN or not.
jazn.realm.roles.ldap.searchBase#	Set the search base to point to the directory subtree where roles will be searched. JAZN locates roles with a specified name by searching in the subtree, jazn.realm.roles.ldap.searchBase, all the objects defined using the role object class if specified, jazn.realm.roles.ldap.objectClass, with attribute, jazn.realm.roles.ldap.nameAttribute, matching the search value provided by the client.
jazn.realm.roles.ldap.nameAttribute#	Set this property to the attribute that uniquely identifies the name of the role.
jazn.realm.roles.ldap.objectClass##	Set this property to the name of schema object class that is used to represent a role. This property is optional.
azn.realm.roles.ldap.memberAttribute##	Set this property to the name of the attribute that contains a role member in a role entry. Default value is "unqiuemember"

#these properties should be defined for external roles (i.e. when jazn.realm.roles.ldap.isExternal is "true")
##optional property, it is useful for further restricting the search of users.

Method Summary

Type	Method
RealmRole	createRole(String name) Create a RealmRole in this realm.
void	dropRole(RealmRole role) Drop the role given the role instance
void	dropRole(String name) Drop the role with the specifed name.
Set	getGrantedRoles(RealmPrincipal principal, boolean direct_grant) Returns a set of RealmRole which are directly or indirectly granted to the specified principal.
Set	getGrantees(RealmRole role, boolean direct_grant) Returns the Grantees that are directly or indirectly granted the specified role.
Realm	getRealm() Returns the Realm reference that this RoleManager belongs to.
RealmRole	getRole(String name) Returns the RealmRole with the specified name
int	getRoleCount() Returns the number of roles in this RoleManager
Set	getRoles() Returns a Set of roles in this RoleManager
void	grantRole(RealmPrincipal principal, RealmRole role) Grants a role to a RealmPrincipal.
void	initialize(Hashtable attributes) Initialize the RoleManager if it's not yet intialized.
void	refresh() Gives the RoleManager a chance to refresh its cache, so updated data will be visible
void	revokeRole(RealmPrincipal principal, RealmRole role) Revokes a role from a RealmPrincipal
void	setRealm(Realm realm) Set the realm that this RoleManager is associated with.

Method Detail

setRealm

public void setRealm(Realm realm)
              throws JAZNException

Set the realm that this RoleManager is associated with.

Parameters:

realm - an instance of Realm

Throws:

JAZNException - is an exception is encountered.

initialize

public void initialize(Hashtable attributes)
                throws JAZNException

Initialize the RoleManager if it's not yet intialized.

Parameters:

attributes - a possibly null table of attributes and configuration parameters for initialization.

refresh

public void refresh()

Gives the RoleManager a chance to refresh its cache, so updated data will be visible

getRealm

public Realm getRealm()

Returns the Realm reference that this RoleManager belongs to.

getRoles

public Set getRoles()
             throws JAZNException

Returns a Set of roles in this RoleManager

Returns:

a Set of RealmRole instances in this RoleManager.

Throws:

JAZNNamingException - if a naming Exception is encountered.

JAZNException - is exception is encountered.

getRoleCount

public int getRoleCount()
                 throws JAZNException

Returns the number of roles in this RoleManager

Returns:

the number of roles in this RoleManager

Throws:

JAZNNamingException - if a naming Exception is encountered.

JAZNException - is exception is encountered.

getRole

public RealmRole getRole(String name)
                  throws JAZNException

Returns the RealmRole with the specified name

Parameters:

name - name of the role

Throws:

JAZNException - is exception is encountered.

getGrantees

public Set getGrantees(RealmRole role,
                       boolean direct_grant)
                throws JAZNException

Returns the Grantees that are directly or indirectly granted the specified role.

Parameters:

role - the role whose grantees are to be retrieved.

direct_grant - true for retrieving only direct granted principals, false for retriving direct and indirect granted principals.

Returns:

a Set of GranteeEntry containing the RealmPrincipal instances which are directly or indirectly granted the specified role.

Throws:

JAZNNamingException - if a naming Exception is encountered.

JAZNException - is exception is encountered.

getGrantedRoles

public Set getGrantedRoles(RealmPrincipal principal,
                           boolean direct_grant)
                    throws JAZNException

Returns a set of RealmRole which are directly or indirectly granted to the specified principal.

Parameters:

principal - the principal whose granted roles are to be retrieved

direct_grant - true for retrieving only direct granted roles, false for retriving direct and indirect granted roles.

Returns:

a Set of RealmRole containg the RealmRole instances which are directly or indirectly granted to the specified principal.

Throws:

JAZNNamingException - if a naming Exception is encountered.

JAZNException - if an exception is encountered.

createRole

public RealmRole createRole(String name)
                     throws JAZNException

Create a RealmRole in this realm.

Parameters:

realm - name

Throws:

UnsupportedOperationException - if roles are not modifiable.

JAZNObjectExistsException - if object of the same name already exists

JAZNNamingException - if NamingException is encountered.

JAZNExeption - if an exception is encountered.

SecurityException - if the caller does not have permission to invoke this method

dropRole

public void dropRole(String name)
              throws JAZNException

Drop the role with the specifed name. This operation will search for all the granted roles from the specified role. It will revoke the granted roles from the specified role first before dropping the specified role.

Parameters:

realm - name

Throws:

UnsupportedOperationException - if dropRole operation not supported.

JAZNObjectNotFoundException - if the role to be dropped is not found.

JAZNNamingException - if a naming Exception is encountered.

JAZNException - if an exception is encountered.

SecurityException - if the caller does not have permission to invoke this method

dropRole

public void dropRole(RealmRole role)
              throws JAZNException

Drop the role given the role instance

Parameters:

role - the role instance to be dropped. This operation will search for all the granted roles from the specified role. It will revoke the granted roles from the specified role first before dropping the specified role.

Throws:

UnsupportedOperationException - if dropRole operation not supported.

JAZNObjectNotFoundException - if the role to be dropped is not found.

JAZNNamingException - if a naming Exception is encountered.

JAZNException - if an exception is encountered.

SecurityException - if the caller does not have permission to invoke this method

grantRole

public void grantRole(RealmPrincipal principal,
                      RealmRole role)
               throws JAZNException

Grants a role to a RealmPrincipal.

Parameters:

principal - - the RealmPrincipal to be granted the specified role

role - - the RealmRole to be granted

Throws:

UnsupportedOperationException - if dropRole operation is not supported.

JAZNInvalidAttributesException - if InvalidAttributesException is encountered.

JAZNNamingException - if a naming Exception is encountered.

JAZNException - if an exception is encountered.

SecurityException - if the caller does not have permission to invoke this method

revokeRole

public void revokeRole(RealmPrincipal principal,
                       RealmRole role)
                throws JAZNException

Revokes a role from a RealmPrincipal

Parameters:

principal - - the RealmPrincipal to be revoked the specified role

role - - the RealmRole to be revoked

Throws:

UnsupportedOperationException - if revokeRole operation not supported.

JAZNInvalidAttributesException - if InvalidAttributesException is encountered.

JAZNNamingException - if a naming Exception is encountered.

JAZNException - if an Exception is encountered.

SecurityException - if the caller does not have permission to invoke this method