orca.shirako.api
Interface IConcreteSet

All Superinterfaces:

IRecover, ISerialize

All Known Implementing Classes:

NodeGroup, Ticket

public interface IConcreteSet
extends ISerialize, IRecover

IConcreteSet defines the interface for concrete set resources. A concrete set is intended to represent a set of resources. For example, compute servers, storage servers, network paths, etc.

Method Summary

void	add(IConcreteSet set, boolean configure) Adds the passed set to the current set.
void	change(IConcreteSet set, Term term, boolean configure) Makes changes to the resources in the concrete set.
IConcreteSet	clone() Makes a clone of the concrete set.
IConcreteSet	cloneEmpty() Makes an "empty" clone of this concrete set.
void	close() Closes all resources contained in the set.
IConcreteSet	collectReleased() Collects any released (closed) and/or failed resources.
void	destroy() Completes close for a concrete set with closed resources.
void	extend(Term term) Informs the concrete set that its term has been extended.
IConcreteSet	extract(int count, Term term, java.util.Properties properties, AuthToken client) Extracts the specified units of resources for the given period of time.
java.lang.String	getNotices() Gets a string of notices or events pertaining to the underlying resources.
IAuthorityProxy	getSiteProxy() Return a proxy or reference for the unique site that owns these resources.
int	getUnits() Returns how many units are contained in the set.
int	holding(java.util.Date date) Returns how many units are in the set at the given time instance.
int	holding(Term term) Returns how many units will be in the set for the given period of time.
boolean	isActive() Checks if the concrete set is active.
void	modify(IConcreteSet set, boolean configure) Updates the units in the current set with information contained in the passed set.
void	probe() Checks the status of pending operations.
void	remove(IConcreteSet set, boolean configure) Removes the passed set from the current set.
void	setShirakoPlugin(IShirakoPlugin plugin)
void	setSiteProxy(IAuthorityProxy authority) Set a proxy or reference for the unique site that owns these resources.
void	setup(ResourceReservation reservation) Initializes the concrete set with information about the containing reservation.
void	validateConcrete(ResourceType type, int units, Term term) Validate that the concrete set matches the abstract resource set parameters.
void	validateIncoming() Validates a concrete set as it is received by an actor from another actor.
void	validateOutgoing() Validates a concrete set as it is about to be sent from the actor to another actor.

Methods inherited from interface orca.shirako.api.ISerialize

reset, save, save

Methods inherited from interface orca.shirako.api.IRecover

revisit

Method Detail

setup

void setup(ResourceReservation reservation)

Initializes the concrete set with information about the containing reservation. This method is called with the manager lock on and hence should not block for long periods of time.

Parameters:

reservation - reservation this concrete set belongs to

validateIncoming

void validateIncoming()
                      throws java.lang.Exception

Validates a concrete set as it is received by an actor from another actor. This method should examine the contents of the concrete set and determine whether it is well-formed. Well-formed is an implementation specific notion. For example, a Sharp ticket is well-formed if all claims the ticket is composed of nest properly. This method is also the place to perform any additional verification required to ascertain that the resources represented by the concrete set are valid. For example, a Sharp ticket is valid if it does not result in oversubscription.

This method is called from ResourceSet with no locks on.

Throws:

java.lang.Exception - if validation fails

validateOutgoing

void validateOutgoing()
                      throws java.lang.Exception

Validates a concrete set as it is about to be sent from the actor to another actor. This method should examine the contents of the concrete set and determine if whether it is well-formed. Any other validation required before sending the concrete set should go in this function.

This method is called from ResourceSet with no locks on.

Throws:

java.lang.Exception - if validation fails

validateConcrete

void validateConcrete(ResourceType type,
                      int units,
                      Term term)
                      throws java.lang.Exception

Validate that the concrete set matches the abstract resource set parameters.

Parameters:

type - abstract resources resource type

units - abstract resources units

term - abstract resources term

Throws:

java.lang.Exception

extract

IConcreteSet extract(int count,
                     Term term,
                     java.util.Properties properties,
                     AuthToken client)
                     throws java.lang.Exception

Extracts the specified units of resources for the given period of time. Transfers control over the extracted resources to the client. Annotates the extracted resources with the passed properties. This is an inventory method.

The concrete set is not required to maintain bookkeeping to verify if the extract operation can actually be completed successfully. The caller is responsible for all bookkeeping and ensuring that the concrete set has sufficient units to satisfy this request. Extract should not decrement the available units from the concrete set.

This method will typically be called with the kernel lock on.

Parameters:

count - number of units to extract

term - the term for extraction

properties - properties to attach to the extracted resources. If any, these properties will replace any properties contained in the set the resources are being extracted from.

client - the client to extract resources to

Returns:

new IConcreteSet representing the extracted resources.

Throws:

java.lang.Exception

add

void add(IConcreteSet set,
         boolean configure)
         throws java.lang.Exception

Adds the passed set to the current set. Optionally triggers configuration actions on all added units. If the lease term for the concrete set has changed, this call must be followed by a call to extend(Term).

Parameters:

set - set to add

configure - if true, configuration actions will be triggered for all added units

Throws:

java.lang.Exception

remove

void remove(IConcreteSet set,
            boolean configure)
            throws java.lang.Exception

Removes the passed set from the current set. Optionally triggers configuration actions for all removed units. If the lease term for the concrete set has changed, this call must be followed by a call to extend(Term).

Parameters:

set - set to remove

configure - if true, configuration actions will be triggered for all removed units

Throws:

java.lang.Exception

modify

void modify(IConcreteSet set,
            boolean configure)
            throws java.lang.Exception

Updates the units in the current set with information contained in the passed set. Note that the passed set may contain only a subset of the units contained in the current set. Optionally triggers configuration actions for all removed units. If the lease term for the concrete set has changed, this call must be followed by a call to extend(Term).

Parameters:

set - set containing the update data

configure - if true, configuration actions will be triggered for all modified units

Throws:

java.lang.Exception

change

void change(IConcreteSet set,
            Term term,
            boolean configure)
            throws java.lang.Exception

Makes changes to the resources in the concrete set. The incoming concrete set represents the state that the current set has to be updated to. The implementation must determine what units have been added/removed/modified and perform the appropriate actions.

Parameters:

set - concrete resources representing the new state of the current set

term - new term

configure - if true, configuration actions will be triggered for all added, removed, or modified units

Throws:

java.lang.Exception - thrown if something is wrong

extend

void extend(Term term)
            throws java.lang.Exception

Informs the concrete set that its term has been extended.

Parameters:

term - new term

Throws:

java.lang.Exception

collectReleased

IConcreteSet collectReleased()
                             throws java.lang.Exception

Collects any released (closed) and/or failed resources.

Returns:

a concrete set containing released and or/failed resources

Throws:

java.lang.Exception

getUnits

int getUnits()

Returns how many units are contained in the set.

Returns:

number of units contained in the set

holding

int holding(Term term)

Returns how many units will be in the set for the given period of time.

Parameters:

term - period of time

Returns:

how many units will be in the set for the given period of time

holding

int holding(java.util.Date date)

Returns how many units are in the set at the given time instance.

Parameters:

date - time instance

Returns:

how many units how many units will be in the set for the given period of time

probe

void probe()
           throws java.lang.Exception

Checks the status of pending operations.

Throws:

java.lang.Exception

close

void close()
           throws java.lang.Exception

Closes all resources contained in the set.

Throws:

java.lang.Exception

destroy

void destroy()
             throws java.lang.Exception

Completes close for a concrete set with closed resources.

Throws:

java.lang.Exception

cloneEmpty

IConcreteSet cloneEmpty()

Makes an "empty" clone of this concrete set. An "empty" clone is a copy of a concrete set with the "set" removed from it.

Returns:

an "empty" clone of this concrete set

clone

IConcreteSet clone()

Makes a clone of the concrete set. Unlike cloneEmpty(), this method preserves the set: the set elements are the same objects as the original IConcreteSet, but the indexing structures are different. That is, adding/removing units to the original should not affect the clone. But modifications to an individual unit should be visible form the original and the clone.

Returns:

a clone of the concrete set

isActive

boolean isActive()

Checks if the concrete set is active. A concrete set is active if all units contained in the set are active.

Returns:

true if the set is active

setShirakoPlugin

void setShirakoPlugin(IShirakoPlugin plugin)

getSiteProxy

IAuthorityProxy getSiteProxy()
                             throws java.lang.Exception

Return a proxy or reference for the unique site that owns these resources.

Returns:

the authority that owns the resources

Throws:

java.lang.Exception

setSiteProxy

void setSiteProxy(IAuthorityProxy authority)
                  throws java.lang.Exception

Set a proxy or reference for the unique site that owns these resources.

Throws:

java.lang.Exception

getNotices

java.lang.String getNotices()

Gets a string of notices or events pertaining to the underlying resources. The event notices are consumed: subsequent calls return only new information. May return null.