orca.shirako.api
Interface IAuthorityPolicy

All Superinterfaces:

IInitialize, IPolicy, IRecover, ISerialize, IServerPolicy

All Known Implementing Classes:

AuthorityBasePolicyPlugin, AuthorityPolicy

public interface IAuthorityPolicy
extends IServerPolicy

IAuthorityPolicy defines the policy interface for an actor acting in the authority role.

Method Summary

void	assign(long cycle) Assigns leases to incoming tickets.
void	available(ResourceSet resources) Informs the policy that concrete resources previously marked as unavailable are now available.
boolean	bind(AuthorityReservation reservation) Handles a requests to allocate resources for a ticketed reservation.
void	correctDeficit(AuthorityReservation reservation)
ResourceSet	correctFailed(ResourceSet rset) Incorporates fixed, but previously failed, resources back to the policy
void	donate(ResourceSet resources) Accepts concrete resources to be used for allocation of client requests.
void	eject(ResourceSet resources) Ejects concrete resources from the inventory.
boolean	extend(AuthorityReservation reservation) Handles a requests to extend the allocation of previously allocated resources.
void	freed(ResourceSet resources) Informs the policy that a set of resources can be considered as free.
void	release(ResourceSet resources) Releases concrete resources that are no longer in use.
int	unavailable(ResourceSet resources) Informs the policy that concrete resources are about to become unavailable.

Methods inherited from interface orca.shirako.api.IServerPolicy

allocate, bind, donate, extend

Methods inherited from interface orca.shirako.api.IPolicy

close, closed, extend, finish, getClosing, getGuid, prepare, query, remove, reset, revisit, setActor, setLogger

Methods inherited from interface orca.shirako.api.IInitialize

initialize

Methods inherited from interface orca.shirako.api.ISerialize

reset, save, save

Methods inherited from interface orca.shirako.api.IRecover

revisit

Method Detail

donate

void donate(ResourceSet resources)
            throws java.lang.Exception

Accepts concrete resources to be used for allocation of client requests. The policy should add the resources represented by this resource set to its inventory. This method is invoked with the kernel lock on.

Parameters:

resources - resource set representing resources to be used for allocation

Throws:

java.lang.Exception

eject

void eject(ResourceSet resources)
           throws java.lang.Exception

Ejects concrete resources from the inventory. Resource ejection is unconditional: the policy must remove the specified concrete nodes from its inventory. Any nodes that reside on ejected hosts should be marked as failed. The policy should take no action to destroy those nodes.

Parameters:

resources -

Throws:

java.lang.Exception

unavailable

int unavailable(ResourceSet resources)
                throws java.lang.Exception

Informs the policy that concrete resources are about to become unavailable. The policy should stop using the concrete resources but should not remove them from its inventory. If the policy currently has active allocations on at least one unit from the concrete resources it should return -1 to indicate that at least one resource cannot be marked unavailable. If the caller still wants to mark a host with hosted nodes as unavailable, the caller may use some administrative interface to move hosts away from the problematic host and then it can retry the operation. Alternatively, the caller may use eject to force the removal of the concrete resources from the policy inventory.

Parameters:

resources -

Returns:

Throws:

java.lang.Exception

available

void available(ResourceSet resources)
               throws java.lang.Exception

Informs the policy that concrete resources previously marked as unavailable are now available.

Parameters:

resources -

Throws:

java.lang.Exception

bind

boolean bind(AuthorityReservation reservation)
             throws java.lang.Exception

Handles a requests to allocate resources for a ticketed reservation. The requested resources can be obtained by calling reservation.getRequestedResources(). The requested lease term can be obtained by calling reservation.getRequestedTerm(). Properties specific to the lease protocol can be obtained by calling reservation.getRequestedResources().getConfigurationProperties(). This method is invoked with the kernel lock on.

If the policy completed processing this request, the functions should return true. If no further intervention is required, e.g., approval by an administrator, the policy should also clear the bidPending flag.

The policy may decide to defer the request for a later time. In this case the function should return false and the bidPending flag should remain unchanged.

This method may be invoked multiple times for a given reservation, i.e., if the policy delays the allocation, the system will continue invoking this method at later times until the policy completes processing this request.

Parameters:

reservation - reservation to allocate resources for.

Returns:

true, if the request has been fulfilled, false, if the allocation of resources will be delayed until a later time.

Throws:

java.lang.Exception

extend

boolean extend(AuthorityReservation reservation)
               throws java.lang.Exception

Handles a requests to extend the allocation of previously allocated resources. The requested resources can be obtained by calling reservation.getRequestedResources(). The requested lease term can be obtained by calling reservation.getRequestedTerm(). Properties specific to the lease protocol can be obtained by calling reservation.getRequestedResources().getConfigurationProperties(). This method is invoked with the kernel lock on.

If the policy completed processing this request, the functions should return true. If no further intervention is required, e.g., approval by an administrator, the policy should also clear the bidPending flag.

The policy may decide to defer the request for a later time. In this case the function should return false and the bidPending flag should remain unchanged.

This method may be invoked multiple times for a given reservation, i.e., if the policy delays the allocation, the system will continue invoking this method at later times until the policy completes processing this request.

Parameters:

reservation - reservation to allocate resources for.

Returns:

true, if the request has been fulfilled, false, if the allocation of resources will be delayed until a later time.

Throws:

java.lang.Exception

assign

void assign(long cycle)
            throws java.lang.Exception

Assigns leases to incoming tickets. This method is called by the policy once per cycle. The method should determine whether to perform resource allocation on the given cycle and what requests to consider in that process. This method is invoked with the kernel lock on.

Parameters:

cycle - the cycle the authority is making assignment for

Throws:

java.lang.Exception

release

void release(ResourceSet resources)
             throws java.lang.Exception

Releases concrete resources that are no longer in use. The set may represent active as well as failed resources. The policy must decide what to do with the released resources. Resources that have been properly closed/terminated are safe to be considered free for future use. Failed resources, however, are problematic. If the policy has no information about the cause of the failure and does not posses the means to recover the falure it should not consider the resources as free. In such cases, and administrator may need to correct the failure manually. When/if the failure is corrected and the resources are safe to be reused, the administrator will issue a call to freed(ResourceSet), which is used to free resources unconditionally.

Parameters:

resources - the resource set to be released

Throws:

java.lang.Exception

See Also:

#closed(ResourceReservation)}

freed

void freed(ResourceSet resources)
           throws java.lang.Exception

Informs the policy that a set of resources can be considered as free. Most probably these resources represent previously failed resources, which have been repaired by an administrator. The policy must update its data structures to reflect the fact that the incoming resources are not longer in use. The policy should regard any state information that individual resource units may contain.

Parameters:

resources -

Throws:

java.lang.Exception

correctDeficit

void correctDeficit(AuthorityReservation reservation)
                    throws java.lang.Exception

Throws:

java.lang.Exception

correctFailed

ResourceSet correctFailed(ResourceSet rset)
                          throws java.lang.Exception

Incorporates fixed, but previously failed, resources back to the policy

Parameters:

rset - the resources

Throws:

java.lang.Exception