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 Object
    implements CloudPool

A `CloudPool` REST API client.

### Constructor Summary

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

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `attachMachine(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(String machineId, boolean decrementDesiredSize)` Removes a member from the pool without terminating it.
`com.google.common.base.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.
`CloudPoolMetadata` `getMetadata()`
`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`.
`void` `setDesiredSize(int desiredSize)` Sets the desired number of machines in the machine pool.
`void` `setMembershipStatus(String machineId, MembershipStatus membershipStatus)` Sets the membership status of a given pool member.
`void` `setServiceState(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(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,
                           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 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:
  `IllegalArgumentException` - If the received configuration was invalid.
  `CloudPoolException` - If the configuration could not be applied.

#### getConfiguration

    public com.google.common.base.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 void setDesiredSize(int desiredSize)
                        throws 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.

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.
Throws:
  `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(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.

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.
  `CloudPoolException` - If the operation could not be completed.
  `NotStartedException` - If the `CloudPool` is not started.

#### setServiceState

    public void setServiceState(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(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(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(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.

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.
  `CloudPoolException` - If the operation could not be completed.
  `NotStartedException` - If the `CloudPool` is not started.

#### getMetadata

    public CloudPoolMetadata getMetadata()

Specified by:
  `getMetadata` in interface `CloudPool`
Returns:
  A `CloudPoolMetadata` object that describes certain static metadata about the cloud pool implementation and the cloud it manages.