orca.shirako.api
Interface IPolicy

All Superinterfaces:

IInitialize, IRecover, ISerialize

All Known Subinterfaces:

IAuthorityPolicy, IBrokerPolicy, IClientPolicy, IServerPolicy, IServiceManagerPolicy

All Known Implementing Classes:

AgentQueuedBestFitPolicyPlugin, AuthorityBasePolicyPlugin, AuthorityPolicy, BaseServiceManagerCalendarPolicy, BrokerBasePolicyPlugin, BrokerBestFitPolicyPlugin, BrokerPolicy, BrokerPriorityPolicyPlugin, BrokerQueuedWorstFitPolicyPlugin, BrokerSimplePolicyPlugin, BrokerWorstFitMultiplePoolsPolicyPlugin, BrokerWorstFitPolicyPlugin, Policy, ServiceManagerPolicy, ServiceManagerSimplePolicyPlugin

public interface IPolicy
extends IInitialize, ISerialize, IRecover

IPolicy encapsulates all policy decisions an actor must make to perform its functions. Each actor has one policy instance that controls its policy decisions. The policy instance must implement the IPolicy interface together with one or more of the other policy interfaces (depending on the role the actor performs).

Some things to know when implementing a policy:

1. The policy is always called under the protection of the kernel Lock. No synchronization is required, but method implementations should not block for long periods of time.
2. The policy operates on the passed ResourceSets. ResourceSets encapsulate the free resource pools and resource requests. The policy satisfies requests by using ResourceSet methods to shift resources from one ResourceSet to another. Resource attributes etc. flow with these operations, and they drive other resource-specific operations including SHARP ticket delegation.
3. The policy has access to all ResourceData attributes attached to the request and the free resource pools. The client-side methods may decorate the request with attributes (e.g., bids), which are passed through to the server-side policy that handles the request. The client-side also has the option of touching the AuthToken passed with the request...this may be a bit goofy.
4. If it is necessary to defer an allocation request, return false. At some later time, when the mapper is ready to satisfy the request (e.g., after an auction on an agent), set bidPending == false and arrange a call to probePending on the requesting reservation. This causes the reservation to retry the pending operation.

Method Summary

void	close(ResourceReservation reservation) Notifies the policy that a reservation is about to be closed.
void	closed(ResourceReservation reservation) Notifies the policy that a reservation has been closed.
void	extend(ResourceReservation reservation, ResourceSet resources, Term term) Notifies the policy that a reservation is about to be extended.
void	finish(long cycle) Informs the mapper that all processing for the specified cycle is complete.
ReservationSet	getClosing(long cycle) Returns a set of reservations that must be closed.
ID	getGuid() Returns the globally unique identifier of this policy object instance.
void	prepare(long cycle) Informs the policy that processing for a new cycle is about to begin.
java.util.Properties	query(java.util.Properties p) Answers a query from another actor.
void	remove(ResourceReservation reservation) Notifies the policy that a reservation is about to be removed.
void	reset() Post recovery entry point.
void	revisit(ResourceReservation reservation) Informs the mapper about a reservation.
void	setActor(IActor actor) Sets the actor the mapper belongs to.
void	setLogger(LoggingTool logger) Sets the logger to be used by the mapper.

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

getGuid

ID getGuid()

Returns the globally unique identifier of this policy object instance. Each policy object instance should have a unique guid.

Returns:

prepare

void prepare(long cycle)

Informs the policy that processing for a new cycle is about to begin. The policy should initialize whatever internal state is necessary to process a new cycle. This method is invoked with the kernel lock on.

Note: The cycle number parameter is redundant and is passed for convenience. The policy can always obtain the cycle number by calling IActor.getCurrentCycle().

Parameters:

cycle - the cycle number that is about to be processed

finish

void finish(long cycle)

Informs the mapper that all processing for the specified cycle is complete. The mapper can safely discard any state associated with the cycle or any previous cycles. This method is invoked with the kernel lock on.

Note: The cycle number parameter is redundant and is passed for convenience. The policy can always obtain the cycle number by calling IActor.getCurrentCycle().

Parameters:

cycle - the cycle number that has just passed

query

java.util.Properties query(java.util.Properties p)

Answers a query from another actor. This method is intended to be used to obtain policy-specific parameters and information. This method should be used when writing more complex policies requiring additional interaction among actors. Instead of extending the proxies to support passing/obtaining the required information, policy code can use the query interface to request/obtain such information. This method is invoked with the kernel lock on: the implementation should not block for prolonged periods of time. If necessary, future versions will update this interface two allow query responses to be delivered using callbacks.

Parameters:

properties - a properties list of query parameters. Can be null or empty.

Returns:

a properties list of outgoing values. If the incoming properties collection is null or empty, should return all possible properties that can be relevant to the caller.

close

void close(ResourceReservation reservation)

Notifies the policy that a reservation is about to be closed. This method will be invoked for every reservation that is about to be closed, even if the close was triggered by the policy itself. The policy should update its internal state/cancel pending operations associated with the reservation. This method is invoked with the kernel lock on.

Parameters:

reservation - reservation about to close

closed

void closed(ResourceReservation reservation)

Notifies the policy that a reservation has been closed. This method will be invoked for every reservation that closes successfully. The policy must uncommit any resources associated with the reservation, e.g, physical machines, currency, etc. This method is invoked with the kernel lock on.

Note: For an authority resources are released using the #IAuthorityPolicy.release(ResourceSet) method. Authority policy implementations should not consider the resources of the passed reservation as released. The release will take place once all configuration actions complete.

Parameters:

reservation - closed reservation

Throws:

java.lang.Exception

See Also:

IAuthorityPolicy.release(ResourceSet)

extend

void extend(ResourceReservation reservation,
            ResourceSet resources,
            Term term)

Notifies the policy that a reservation is about to be extended. This method will be invoked only for reservations, whose extensions have not been triggered by the policy, e.g, from the management interface. The policy should update its state to reflect the extend request. This method is invoked with the kernel lock on.

Parameters:

reservation - reservation to be extended

resources - resource set used for the extension

term - term used for the extension

remove

void remove(ResourceReservation reservation)

Notifies the policy that a reservation is about to be removed. This method will be invoked for each reservation that is to be removed from the system. The policy should remove any state that it maintains for the reservation. This method is invoked with the kernel lock on.

Note: Only failed and closed reservations can be removed. The system will not invoke this method if the reservation is not closed or failed.

Parameters:

reservation - reservation to be removed

getClosing

ReservationSet getClosing(long cycle)

Returns a set of reservations that must be closed. This method is invoked with the kernel lock on.

Parameters:

cycle - the current cycle

revisit

void revisit(ResourceReservation reservation)
             throws java.lang.Exception

Informs the mapper about a reservation. Called during recovery/startup. The mapper must re-establish any state required for the management of the reservation.

Throws:

java.lang.Exception

reset

void reset()
           throws java.lang.Exception

Post recovery entry point. This method will be invoked once all revisit operations are complete and the actor is ready to operate normally.

Throws:

java.lang.Exception

setActor

void setActor(IActor actor)

Sets the actor the mapper belongs to.

Parameters:

actor - the actor the mapper belongs to

setLogger

void setLogger(LoggingTool logger)

Sets the logger to be used by the mapper.

Parameters:

logger - logger to use