BEA Systems, Inc.

BEA AquaLogic Enterprise Security for Java 2.6 API Reference

com.bea.security
Class AuthorizationService

java.lang.Object
  |
  +--com.bea.security.PublicSecurityService
        |
        +--com.bea.security.AuthorizationService

public class AuthorizationService
extends PublicSecurityService

The authorization service is a service that allows an application to determine if a specific identity is permitted to access a specific resource.

Author:
Copyright © 2004 BEA Systems, Inc. All Rights Reserved.

Field Summary
static java.lang.String ATZ_CACHE_ENTRIES_KEY
          Key value which indicates authorization cache entries.
static java.lang.String ATZ_CACHE_HIT_RATIO_KEY
          Key value which indicates authorization cache hit ratio.
static java.lang.String ATZ_CACHE_HITS_KEY
          Key value which indicates authorization cache hits number.
static java.lang.String ATZ_CACHE_QUERIES_KEY
          Key value which indicates authorization cache queries.
static int ONCE
          Indicates that an authorization query will only be asked once for a resource and action.
static int POST
          Indicates that an authorization query is being asked after a resource is aquired, but before it has been processed or presented.
static int PRIOR
          Indicates that an authorization query is being asked before a resource is aquired.
 
Fields inherited from class com.bea.security.PublicSecurityService
COMPATIBLE, COMPATIBLE_DEPRECATED, COMPATIBLE_UNKNOWN, NOT_COMPATIBLE
 
Method Summary
 java.util.Map getAuthorizationCacheStatistics(AuthenticIdentity ident)
          Get ALES authorization cache statistics.
 ServiceType getServiceType()
          Indicates this service's type.
 ServiceVersion getVersion()
          Indicates this service's version.
 AccessResult isAccessAllowed(AuthenticIdentity ident, RuntimeResource resource, RuntimeAction action)
          Determines if an AuthenticIdentity is permitted to access a specific resource with a specific action.
 AccessResult isAccessAllowed(AuthenticIdentity ident, RuntimeResource resource, RuntimeAction action, AppContext context)
          Determines if an AuthenticIdentity is permitted to access a specific resource with a specific action.
 AccessResult isAccessAllowed(AuthenticIdentity ident, RuntimeResource resource, RuntimeAction action, AppContext context, int direction)
          Determines if an AuthenticIdentity is permitted to access a specific resource with a specific action.
 boolean isAuthenticationRequired(RuntimeResource resource, RuntimeAction action)
          Determines if a resource and action requires authentication before it is accessed.
 int isCompatible(ServiceVersion version)
          Determines if the version of the public service API specified in the Java application is compatible with the current version of the service API in the security runtime instance.
 java.util.List queryActionsOnChildResource(AuthenticIdentity ident, RuntimeResource resourceClippingNode, java.util.List requestedActions, AppContext context)
          Query set of allowed and denied actions for the AuthenticIdentity on the resource clipping node and all child nodes of this node.
 RuntimeEntitlement queryActionsOnResource(AuthenticIdentity ident, RuntimeResource resource, java.util.List requestedActions, AppContext context)
          Query set of allowed and denied actions for the AuthenticIdentity on a specific resource.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ONCE

public static final int ONCE
Indicates that an authorization query will only be asked once for a resource and action.

PRIOR

public static final int PRIOR
Indicates that an authorization query is being asked before a resource is aquired.

POST

public static final int POST
Indicates that an authorization query is being asked after a resource is aquired, but before it has been processed or presented.

ATZ_CACHE_HITS_KEY

public static final java.lang.String ATZ_CACHE_HITS_KEY
Key value which indicates authorization cache hits number. used to get cache hits number from result of method getAuthorizationCacheStatistics
See Also:
getAuthorizationCacheStatistics(com.bea.security.AuthenticIdentity)

ATZ_CACHE_ENTRIES_KEY

public static final java.lang.String ATZ_CACHE_ENTRIES_KEY
Key value which indicates authorization cache entries. used to get cache entries from result of method getAuthorizationCacheStatistics
See Also:
getAuthorizationCacheStatistics(com.bea.security.AuthenticIdentity)

ATZ_CACHE_HIT_RATIO_KEY

public static final java.lang.String ATZ_CACHE_HIT_RATIO_KEY
Key value which indicates authorization cache hit ratio. used to get cache hit ratio from result of method getAuthorizationCacheStatistics
See Also:
getAuthorizationCacheStatistics(com.bea.security.AuthenticIdentity)

ATZ_CACHE_QUERIES_KEY

public static final java.lang.String ATZ_CACHE_QUERIES_KEY
Key value which indicates authorization cache queries. used to get cache queries from result of method getAuthorizationCacheStatistics
See Also:
getAuthorizationCacheStatistics(com.bea.security.AuthenticIdentity)
Method Detail

getServiceType

public ServiceType getServiceType()
Indicates this service's type.

Returns:
a ServiceType object indicating this service's type.
Overrides:
getServiceType in class PublicSecurityService

getVersion

public ServiceVersion getVersion()
Indicates this service's version.

Returns:
a ServiceVersion indicating the service version number and patch level.
Overrides:
getVersion in class PublicSecurityService

isCompatible

public int isCompatible(ServiceVersion version)
Determines if the version of the public service API specified in the Java application is compatible with the current version of the service API in the security runtime instance.

Parameters:
version - a ServiceVersion which is being asked for by the Java application. The current service, that is, the service in the security runtime instance, will indiciate if it supports the version specified in the isCompatible() method.
Returns:
an int equaling NOT_COMPATIBLE if the service is not compatible with the supplied version, COMPATIBLE if the service is fully compatible, COMPATIBLE_DEPRECATED if the service is compatible, but some functions have been depricated between the versions, or, finally, COMPATIBLE_UNKNOWN if the version passed in is newer than the current version, so compatibility is unknown.
Overrides:
isCompatible in class PublicSecurityService

isAccessAllowed

public AccessResult isAccessAllowed(AuthenticIdentity ident,
                                    RuntimeResource resource,
                                    RuntimeAction action)
                             throws IdentityNotAuthenticException,
                                    ParameterException
Determines if an AuthenticIdentity is permitted to access a specific resource with a specific action. The application context is not taken into account for this decision. The direction parameter, which cannot be specified using this version of this method, is set to ONCE by default.

Parameters:
ident - an AuthenticIdentity that is asking permission to access a resource with an action.
resource - the RuntimeResource that is being checked for permission.
action - the RuntimeAction to be performed on the resource.
Returns:
an AccessResult which encodes if the AuthenticIdentity has permission to access this resource or not.
Throws:
IdentityNotAuthenticException - This exception is thrown if the identity provided is invalid or not properly authenticated.
ParameterException - This exception is thrown if a parameter passed in is invalid.

isAccessAllowed

public AccessResult isAccessAllowed(AuthenticIdentity ident,
                                    RuntimeResource resource,
                                    RuntimeAction action,
                                    AppContext context)
                             throws IdentityNotAuthenticException,
                                    ParameterException
Determines if an AuthenticIdentity is permitted to access a specific resource with a specific action. The application context is also taken into account for this decision. The direction parameter, which cannot be specified using this version of this method, is set to ONCE by default.

Parameters:
ident - an AuthenticIdentity that is asking permission to access a resource.
resource - the RuntimeResource that is being checked for permission.
action - the RuntimeAction to be performed on the resource.
context - an object with an AppContext interface containing name/value pairs relevant to this application's current context. Providers may use the values in this context to help determine the answer to this query.
Returns:
an AccessResult which encodes if the AuthenticIdentity has permission to access this resource or not.
Throws:
IdentityNotAuthenticException - An IdentityNotAuthenticException is thrown if the identity provides is invalid or not properly authenticated.
ParameterException - This exception is thrown if a parameter passed in is invalid.

isAccessAllowed

public AccessResult isAccessAllowed(AuthenticIdentity ident,
                                    RuntimeResource resource,
                                    RuntimeAction action,
                                    AppContext context,
                                    int direction)
                             throws ParameterException,
                                    IdentityNotAuthenticException
Determines if an AuthenticIdentity is permitted to access a specific resource with a specific action. The application context is also taken into account for this decision.

Parameters:
ident - an AuthenticIdentity that is asking permission to access a resource.
resource - the RuntimeResource that is being checked for permission.
action - the RuntimeAction to be performed on the resource.
context - an object with an AppContext interface containing name/value pairs relevant to this application's current context. Providers may use the values in this context to help determine the answer to this query.
direction - determines how this access request is processed. This parameter can be set to PRIOR, POST, or ONCE. PRIOR indicates that this access request is to be evaluated before the resource is acquired, POST indicates that this access request is to be evaluated after the resource is required, and ONCE indicates that this access request is to be evaluated only once. An application may use the PRIOR and POST parameters in cases where an AuthenticIdentity may be permitted to acquire a resource prior to using it, but then may not be permitted to use it after it is acquired.
Returns:
an AccessResult which encodes if the Identity has permission to access this resource or not.
Throws:
ParameterException - This exception is thrown if a parameter passed in is invalid.
IdentityNotAuthenticException - This exception is thrown if the identity provided is invalid or not properly authenticated.

getAuthorizationCacheStatistics

public java.util.Map getAuthorizationCacheStatistics(AuthenticIdentity ident)
                                              throws IdentityNotAuthenticException
Get ALES authorization cache statistics. The statistics will be available if authorization caching is turned on in ASI authorization provider. The authorization cache statistics informations below will be returned.
total cache hit number
total cache query number
total cache hit ratio
total cache entries

Parameters:
ident - an AuthenticIdentity
Returns:
a Map contains authorization cache statistics, including following values.
total cache hit number: is an object of java.lang.Long
total cache query number: is an object of java.lang.Long
total cache hit ratio: is an object of java.lang.Float
total cache entries: is an object of java.lang.Long
Use the const keys to get cache statistics.
See Also:
ATZ_CACHE_HITS_KEY, ATZ_CACHE_HIT_RATIO_KEY, ATZ_CACHE_QUERIES_KEY, ATZ_CACHE_ENTRIES_KEY

isAuthenticationRequired

public boolean isAuthenticationRequired(RuntimeResource resource,
                                        RuntimeAction action)
                                 throws ParameterException
Determines if a resource and action requires authentication before it is accessed. This method is only relevant in the case of an unauthenticated (anonymous) user.

Parameters:
resource - a RuntimeResource that indicates the resource in question.
action - a RuntimeAction that indicates the action in question.
Returns:
a true if this resource and action requires the application to authenticate the user and do an isAccessAllowed call to determine the final access decision. A false if this resource and action does not require authentication. In the event no authentication is required, isAccessAllowed need not be called and the application can allow the action on the resource in question.
Throws:
ParameterException - This exception is thrown if a parameter passed in is invalid.

queryActionsOnResource

public RuntimeEntitlement queryActionsOnResource(AuthenticIdentity ident,
                                                 RuntimeResource resource,
                                                 java.util.List requestedActions,
                                                 AppContext context)
                                          throws ParameterException,
                                                 IdentityNotAuthenticException,
                                                 MissingAttributeException
Query set of allowed and denied actions for the AuthenticIdentity on a specific resource. If the application context is not null, it will be taken into account for this query.

Parameters:
ident - an AuthenticIdentity that is asking queries on a resource.
resource - the RuntimeResource that is being checked for this query.
requestedActions - a collection of RuntimeAction object, which lists the actions the application is interested in. If the collection is not null or empty, ALES runtime will check user¡¯s privileges only for these actions.
context - an object with an AppContext interface containing name/value pairs relevant to this application's current context. If the context is not null, providers may use the values in this context to help determine the answer to this query.
Returns:
an RuntimeEntitlement object, which encodes the allowed and denied actions for the ident on the resource. null means error happened in runtime.
Throws:
ParameterException - This exception is thrown if a parameter passed in is invalid.
IdentityNotAuthenticException - This exception is thrown if the identity provided is invalid or not properly authenticated.
MissingAttributeException - This exception is thrown if certain attributes, required by runtime, are missing during query actions

queryActionsOnChildResource

public java.util.List queryActionsOnChildResource(AuthenticIdentity ident,
                                                  RuntimeResource resourceClippingNode,
                                                  java.util.List requestedActions,
                                                  AppContext context)
                                           throws ParameterException,
                                                  IdentityNotAuthenticException,
                                                  MissingAttributeException
Query set of allowed and denied actions for the AuthenticIdentity on the resource clipping node and all child nodes of this node. If the application context is not null, it will be taken into account for this query.

Parameters:
ident - an AuthenticIdentity that is asking queries on a resource clipping node.
resourceClippingNode - the resource clipping node.
requestedActions - a collection of RuntimeAction object, which lists the actions the application is interested in. If the collection is not null or empty, ALES runtime will check user¡¯s privileges only for these actions.
context - an object with an AppContext interface containing name/value pairs relevant to this application's current context. If the context is not null, providers may use the values in this context to help determine the answer to this query.
Returns:
a List of RuntimeEntitlement object. Each object represents one resource and the allowed and denied actions for the ident on the resource. The List is ordered by the resource name. null means error happened in runtime.
Throws:
ParameterException - This exception is thrown if a parameter passed in is invalid.
IdentityNotAuthenticException - This exception is thrown if the identity provided is invalid or not properly authenticated.
MissingAttributeException - This exception is thrown if certain attributes, required by runtime, are missing during query actions on child resource

Documentation is available at
http://edocs.bea.com/ales/docs26