Package com.elastisys.scale.cloudpool.api.client

Class CloudPoolClient

java.lang.Object

com.elastisys.scale.cloudpool.api.client.CloudPoolClient

All Implemented Interfaces:

CloudPool

public class CloudPoolClient
extends java.lang.Object
implements CloudPool

A CloudPool REST API client.

Constructor Summary

Constructors

Constructor	Description
CloudPoolClient(com.elastisys.scale.commons.net.http.client.AuthenticatedHttpClient httpClient, java.lang.String cloudPoolHost, int cloudPoolPort)	Constructs a CloudPoolClient for a given CloudPool endpoint, using a given AuthenticatedHttpClient for communication.

Method Summary

Modifier and Type	Method	Description
void	attachMachine(java.lang.String machineId)	Attaches an already running machine instance to the pool, growing the pool with a new member.
void	configure(com.google.gson.JsonObject configuration)	Updates the configuration for this CloudPool.
void	detachMachine(java.lang.String machineId, boolean decrementDesiredSize)	Removes a member from the pool without terminating it.
java.util.Optional<com.google.gson.JsonObject>	getConfiguration()	Returns the configuration currently set for this CloudPool, if one has been set.
MachinePool	getMachinePool()	Returns a list of the members of the cloud pool.
PoolSizeSummary	getPoolSize()	Returns the current size of the MachinePool -- both in terms of the desired size and the actual size (as these may differ at any time).
CloudPoolStatus	getStatus()	Returns the execution status for the CloudPool.
java.util.concurrent.Future<?>	setDesiredSize(int desiredSize)	Sets the desired number of machines in the machine pool.
void	setMembershipStatus(java.lang.String machineId, MembershipStatus membershipStatus)	Sets the membership status of a given pool member.
void	setServiceState(java.lang.String machineId, ServiceState serviceState)	Sets the service state of a given machine pool member.
void	start()	Starts the CloudPool.
void	stop()	Stops the CloudPool.
void	terminateMachine(java.lang.String machineId, boolean decrementDesiredSize)	Terminates a particular machine pool member.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CloudPoolClient

public CloudPoolClient(com.elastisys.scale.commons.net.http.client.AuthenticatedHttpClient httpClient,
                       java.lang.String cloudPoolHost,
                       int cloudPoolPort)

Constructs a CloudPoolClient for a given CloudPool endpoint, using a given AuthenticatedHttpClient for communication.

Parameters:

httpClient - The AuthenticatedHttpClient used to communicate over the REST API.

cloudPoolHost - Host/IP address of the CloudPool.

cloudPoolPort - The port on which the CloudPool server is listening.

Method Detail

configure

public void configure(com.google.gson.JsonObject configuration)
               throws java.lang.IllegalArgumentException,
                      CloudPoolException

Description copied from interface: CloudPool

Updates the configuration for this CloudPool.

This operation does not change the CloudPool's started state -- if the CloudPool is started it should remain started, and if it is in a stopped state it should remain stopped.

The configuration is passed as a JSON object. It is up to the CloudPool to validate and apply the contents of the configuration as well as to perform whatever changes are needed for the new configuration to take effect.

Specified by:

configure in interface CloudPool

Parameters:

configuration - The JSON configuration to be set.

Throws:

java.lang.IllegalArgumentException - If the received configuration was invalid.

CloudPoolException - If the configuration could not be applied.

getConfiguration

public java.util.Optional<com.google.gson.JsonObject> getConfiguration()

Description copied from interface: CloudPool

Returns the configuration currently set for this CloudPool, if one has been set.

Specified by:

getConfiguration in interface CloudPool

Returns:

A JSON configuration if set, Optional#absent() otherwise.

start

public void start()
           throws NotConfiguredException

Description copied from interface: CloudPool

Starts the CloudPool.

This will set the CloudPool in an activated state where it will start to accept requests to query or modify the machine pool.

If the CloudPool has not been configured the method will fail. If the CloudPool is already started this is a no-op.

Specified by:

start in interface CloudPool

Throws:

NotConfiguredException - If the CloudPool has not been configured.

stop

public void stop()

Description copied from interface: CloudPool

Stops the CloudPool.

A stopped CloudPool is in a passivated state and will not accept any requests to query or modify the machine pool.

If the CloudPool is already in a stopped state this is a no-op.

Specified by:

stop in interface CloudPool

getStatus

public CloudPoolStatus getStatus()

Description copied from interface: CloudPool

Returns the execution status for the CloudPool.

Specified by:

getStatus in interface CloudPool

Returns:

getMachinePool

public MachinePool getMachinePool()
                           throws CloudPoolException,
                                  NotStartedException

Description copied from interface: CloudPool

Returns a list of the members of the cloud pool.

Note, that the response may include machines in any MachineState, even machines that are in the process of terminating.

The MembershipStatus of a machine in an allocated/started state determines if it is to be considered an active member of the pool.The active size of the machine pool should be interpreted as the number of allocated machines (in any of the non-terminal machine states REQUESTED, PENDING or RUNNING that have not been marked with an inactive MembershipStatus. See Machine.isActiveMember().

The service state should be set to UNKNOWN for all machine instances for which no service state has been reported (see CloudPool.setServiceState(String, ServiceState)).

Similarly, the MembershipStatus should be set to MembershipStatus.defaultStatus() for all machine instances for which no membership status has been reported (see CloudPool.setMembershipStatus(String, MembershipStatus)).

Specified by:

getMachinePool in interface CloudPool

Returns:

A list of cloud pool members.

Throws:

CloudPoolException - If the operation could not be completed.

NotStartedException - If the CloudPool is not started.

getPoolSize

public PoolSizeSummary getPoolSize()
                            throws CloudPoolException,
                                   NotStartedException

Description copied from interface: CloudPool

Returns the current size of the MachinePool -- both in terms of the desired size and the actual size (as these may differ at any time).

Specified by:

getPoolSize in interface CloudPool

Returns:

The current PoolSizeSummary.

Throws:

CloudPoolException - If the operation could not be completed.

NotStartedException - If the CloudPool is not started.

setDesiredSize

public java.util.concurrent.Future<?> setDesiredSize(int desiredSize)
                                              throws java.lang.IllegalArgumentException,
                                                     CloudPoolException,
                                                     NotStartedException

Description copied from interface: CloudPool

Sets the desired number of machines in the machine pool. This method is asynchronous and returns immediately after updating the desired size. There may be a delay before the changes take effect and are reflected in the machine pool. The method returns a Future that the caller can use if it needs to wait for the size update to be applied to the pool.

Note: the CloudPool implementation should take measures to ensure that requested machines are recognized as pool members. The specific mechanism to mark pool members, which may depend on the features offered by the particular cloud API, is left to the implementation but could, for example, make use of tags.

Specified by:

setDesiredSize in interface CloudPool

Parameters:

desiredSize - The desired number of machines in the pool.

Returns:

A Future that the caller can use to wait for the size update to be applied to the pool.

Throws:

java.lang.IllegalArgumentException - If the desired size is illegal.

CloudPoolException - If the operation could not be completed.

NotStartedException - If the CloudPool is not started.

terminateMachine

public void terminateMachine(java.lang.String machineId,
                             boolean decrementDesiredSize)
                      throws NotFoundException,
                             CloudPoolException,
                             NotStartedException

Description copied from interface: CloudPool

Terminates a particular machine pool member. The caller can control if a replacement machine is to be provisioned via the decrementDesiredSize parameter.

Note: a machine that is protected from removal by a membership status with evictable: false can not be terminated.

Specified by:

terminateMachine in interface CloudPool

Parameters:

machineId - The machine to terminate.

decrementDesiredSize - If the desired pool size should be decremented (true) or left at its current size (false).

Throws:

NotFoundException - If the specified machine is not a member of the pool.

NotEvictableException - If the specified machine has a MembershipStatus that prevents it from being removed.

CloudPoolException - If the operation could not be completed.

NotStartedException - If the CloudPool is not started.

setServiceState

public void setServiceState(java.lang.String machineId,
                            ServiceState serviceState)
                     throws NotFoundException,
                            CloudPoolException,
                            NotStartedException

Description copied from interface: CloudPool

Sets the service state of a given machine pool member. Setting the service state does not have any functional implications on the pool member, but should be seen as way to supply operational information about the service running on the machine to third-party services (such as load balancers).

Specified by:

setServiceState in interface CloudPool

Parameters:

machineId - The id of the machine whose service state is to be updated.

serviceState - The ServiceState to assign to the machine.

Throws:

NotFoundException - If the specified machine is not a member of the pool.

CloudPoolException - If the operation could not be completed.

NotStartedException - If the CloudPool is not started.

setMembershipStatus

public void setMembershipStatus(java.lang.String machineId,
                                MembershipStatus membershipStatus)
                         throws NotFoundException,
                                CloudPoolException,
                                NotStartedException

Description copied from interface: CloudPool

Sets the membership status of a given pool member.

The membership status for a machine can be set to protect the machine from being terminated (by setting its evictability status) and/or to mark a machine as being in need of replacement by flagging it as an inactive pool member.

Specified by:

setMembershipStatus in interface CloudPool

Parameters:

machineId - The id of the machine whose status is to be updated.

membershipStatus - The MembershipStatus to set.

Throws:

NotFoundException

CloudPoolException

NotStartedException - If the CloudPool is not started.

attachMachine

public void attachMachine(java.lang.String machineId)
                   throws NotFoundException,
                          CloudPoolException,
                          NotStartedException

Description copied from interface: CloudPool

Attaches an already running machine instance to the pool, growing the pool with a new member. This operation implies that the desired size of the pool is incremented by one.

Specified by:

attachMachine in interface CloudPool

Parameters:

machineId - The identifier of the machine to attach to the pool.

Throws:

NotFoundException - If the specified machine does not exist.

CloudPoolException - If the operation could not be completed.

NotStartedException - If the CloudPool is not started.

detachMachine

public void detachMachine(java.lang.String machineId,
                          boolean decrementDesiredSize)
                   throws NotFoundException,
                          CloudPoolException,
                          NotStartedException

Description copied from interface: CloudPool

Removes a member from the pool without terminating it. The machine keeps running but is no longer considered a pool member and, therefore, needs to be managed independently. The caller can control if a replacement machine is to be provisioned via the decrementDesiredSize parameter.

Note: a machine that is protected from removal by a membership status with evictable: false can not be terminated.

Specified by:

detachMachine in interface CloudPool

Parameters:

machineId - The identifier of the machine to detach from the pool.

decrementDesiredSize - If the desired pool size should be decremented (true) or left at its current size (false).

Throws:

NotFoundException - If the specified machine is not a member of the pool.

NotEvictableException - If the specified machine has a MembershipStatus that prevents it from being removed.

CloudPoolException - If the operation could not be completed.

NotStartedException - If the CloudPool is not started.