org.edg.security.voms.operation
Interface Action

All Superinterfaces:
java.io.Serializable
All Known Implementing Classes:
ActionHelper

public interface Action
extends java.io.Serializable

An interface for representing high-level update operations in the VO database. Classes implementing this interface usually have attributes representing all the parameters that are necessary for the action. VOMS calls perform() when it is time to carry out the operation.

Actions should not normally need to return a value to the caller. For the few cases when returning a value is unavoidable (e.g. creating a new request should return its id), a performWithResult() method is provided. (In each class, exactly one of perform() and performWithResult() must be implemented -- the default implementations provided by ActionHelper take care of the correct semantics.)

The Database class provides methods for executing (performing) actions. These methods are the only way to perform an action. Note that act of performing an action always returns a value. If the action is valueless, i.e. perform() is implemented, then the returned value is null.

TODO: If you find this mess with the return values confusing, you are right, and you are welcome to add a return value to perform(), delete performWithResult(), and add a return null; to the end of each existing action. Bear in mind though that the mostly extraneous return statement would make writing actions even more unpleasant than it already is.

All action types must be derived from ActionHelper, because the Database class depends on the internal semantics implemented by that helper class.

Note that it is possible that this interface will be extended with new methods when the notification mechanism is implemented. If this happens, ActionHelper will provide adequate default implementations, so that existing actions would not need to be changed.

Version:
$Name: v0_7_0 $
Author:
Karoly Lorentey

Method Summary
 void checkPermission()
          Check that the current client (as specified by the current security context) has the right to perform this action.
 java.util.List getAdminUsers()
          Return the list of User objects, who are allowed to perform the action.
 java.lang.String getContainerName()
          Return the FQCN of the container that this request wants to change.
 java.lang.String getDescription()
          Return a human-readable description of this request.
 java.util.Map getParameters()
          Return the parameters of the requested action as an array of strings.
 void perform()
          Do the operation that this action represents, without ACL checks.
 java.lang.Object performWithResult()
          Do the operation that this action represents, without ACL checks, and return a value.
 

Method Detail

checkPermission

public void checkPermission()
                     throws VOMSException
Check that the current client (as specified by the current security context) has the right to perform this action. The method returns normally when the access is granted. Otherwise, it throws a VOMSSecurityException.

Throws:
VOMSSecurityException - when the access is denied.
DatabaseError - if an SQL error occurs.
InconsistentDatabase - if a database inconsistency is detected.
VOMSException
See Also:
SecurityContext

getAdminUsers

public java.util.List getAdminUsers()
                             throws VOMSException
Return the list of User objects, who are allowed to perform the action. The method only returns the users, who are also members of the Virtual Organization, thus there is a user object associated with them.

Actions that are not part of a requests need not implement this method.

Throws:
DatabaseError - if an SQL error occurs.
VOMSException
See Also:
DBACL

perform

public void perform()
             throws VOMSException
Do the operation that this action represents, without ACL checks. Any errors must be signalled by throwing an exception. This is essentially a shorthand for performWithResult(), for actions that do not need a return value. Most actions are like this, so the elimination of the extra return statement seems worthwhile.

VOMSException

performWithResult

public java.lang.Object performWithResult()
                                   throws VOMSException
Do the operation that this action represents, without ACL checks, and return a value. This is the more general version of perform() for use when the action must return a value. A typical scenario when this is needed is the creation of a new request: performing the action must return the id of the newly created request.

VOMSException

getDescription

public java.lang.String getDescription()
Return a human-readable description of this request.


getContainerName

public java.lang.String getContainerName()
Return the FQCN of the container that this request wants to change. This is used for listing requests belonging to administrators of a given container, which eases VO administration. It is legal to return null if the action is not specific to any container.

Actions that are not part of a requests need not implement this method.


getParameters

public java.util.Map getParameters()
Return the parameters of the requested action as an array of strings. The array has an even number of members; even-numbered indices contain parameter names, odd-numbered indices contain parameter values. This method is for enumerating the parameters for the user.