com.elastisys.scale.cloudpool.api.types

## Class Machine

- java.lang.Object
- - com.elastisys.scale.cloudpool.api.types.Machine

    public class Machine
    extends Object

Represents a machine that is a member of a `MachinePool` managed by a `CloudPool`.

As explained in the cloud pool REST API, a `Machine` has three different states of interest:

- The machine state, being the execution state of the machine as reported by the cloud API.
- The membership status, indicating if the machine is to be given special treatment in the pool. This includes protecting it from termination and/or marking it in need of a replacement.
- The service state, being the operational state of the service running on the machine.

See Also:
  `MachinePool`, `CloudPool`

### Nested Class Summary

Nested Classes
`static class` `Machine.ActiveMemberPredicate` A `Predicate` that returns `true` when passed a `Machine` that is an active pool member -- it has been allocated from the underlying infrastructure (`MachineState.REQUESTED`, `MachineState.PENDING` or `MachineState.RUNNING`) and is an active pool member (`MembershipStatus.isActive()`).
`static class` `Machine.AllocatedMachinePredicate` A `Predicate` that returns `true` when passed a `Machine` that has been allocated from the underlying infrastructure (machine state `MachineState.REQUESTED`, `MachineState.PENDING` or `MachineState.RUNNING`).
`static class` `Machine.Builder` A builder for creating `Machine` instances.
`static class` `Machine.EvictableMemberPredicate` A `Predicate` that returns `true` when passed a `Machine` with an evictable `MembershipStatus`.
`static class` `Machine.InstanceHourStart` A `Function` that for a given `Machine` calculates when the started its most recent hour.
`static class` `Machine.MachineIdExtractor` A transformation `Function` that when applied to a `Machine` extracts the `Machine`'s id.
`static class` `Machine.MachineStateExtractor` A transformation `Function` that when applied to a `Machine` extracts the `Machine`'s state.
`static class` `Machine.MachineWithState` A `Predicate` that returns `true` when passed a `Machine` in a given `MachineState`.
`static class` `Machine.RemainingInstanceHourTime` A `Function` that for a given `Machine` calculates the remaining time (in seconds) of the machine's current hour.
`static class` `Machine.RequestAge` A `Function` that optionally returns the number of milliseconds of how long ago the request to start a given `Machine` was made.
`static class` `Machine.StartedMachinePredicate` A `Predicate` that returns `true` when passed a `Machine` that has been started by the underlying infrastructure (machine state is `MachineState.PENDING` or `MachineState.RUNNING`).
`static class` `Machine.ToShortMachineFormat` A `Function` that, for a given `Machine`, returns a clone of the `Machine` that excludes the meta data field of the original `Machine`.
`static class` `Machine.ToShortMachineString` A `Function` that, for a given `Machine`, returns a string representation that excludes any `Machine` meta data (which can produce quite some log noise).

### Constructor Summary

Constructors
`protected` `Machine(String id, MachineState machineState, MembershipStatus membershipStatus, ServiceState serviceState, String cloudProvider, String region, String machineSize, org.joda.time.DateTime requestTime, org.joda.time.DateTime launchTime, List<String> publicIps, List<String> privateIps, com.google.gson.JsonElement metadata)` Constructs a new `Machine`.

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`static Machine.Builder` `builder()` Creates a `Machine.Builder` object for generating `Machine` instances.
`boolean` `equals(Object obj)`
`String` `getCloudProvider()` Returns The name of the cloud provider that this machine originates from, for example `AWS-EC2`.
`String` `getId()` Returns the identifier of the `Machine`.
`org.joda.time.DateTime` `getLaunchTime()` Returns the launch time of the `Machine` if it has been launched.
`String` `getMachineSize()` Return the size (or type) of the `Machine`.
`MachineState` `getMachineState()` Returns the execution state of the `Machine`.
`MembershipStatus` `getMembershipStatus()` Returns the pool membership status of this `Machine`.
`com.google.gson.JsonElement` `getMetadata()` Returns any additional cloud provider-specific meta data about the `Machine` if set, otherwise `null`.
`List<String>` `getPrivateIps()` Returns the list of private IP addresses associated with this `Machine`.
`List<String>` `getPublicIps()` Returns the list of public IP addresses associated with this `Machine`.
`String` `getRegion()` Returns the name of the cloud region/zone/data center where this machine is located.
`org.joda.time.DateTime` `getRequestTime()` Returns the request time of the `Machine`.
`ServiceState` `getServiceState()` Returns the service state of the `Machine`.
`int` `hashCode()`
`static com.google.common.base.Function<? super Machine,org.joda.time.DateTime>` `instanceHourStart()` Returns a `Function` that given a `Machine` (with a launch time set) returns the starting point of the `Machine`'s most recently started hour.
`static com.google.common.base.Predicate<? super Machine>` `inState(MachineState state)` Returns a `Predicate` that returns `true` when passed a `Machine` in a given `MachineState`.
`static com.google.common.base.Predicate<Machine>` `isActiveMember()` Returns a `Predicate` that returns `true` when passed a `Machine` that is an active pool member -- it has been allocated from the underlying infrastructure (`MachineState.REQUESTED`, `MachineState.PENDING` or `MachineState.RUNNING`) and is an active pool member (`MembershipStatus.isActive()`).
`static com.google.common.base.Predicate<Machine>` `isAllocated()` Returns a `Predicate` that returns `true` when passed a `Machine` that has been allocated from the underlying infrastructure (machine state `MachineState.REQUESTED`, `MachineState.PENDING` or `MachineState.RUNNING`).
`static com.google.common.base.Predicate<Machine>` `isEvictable()` Returns a `Predicate` that returns `true` for any `Machine` with an evictable `MembershipStatus`.
`static com.google.common.base.Predicate<Machine>` `isStarted()` A `Predicate` that returns `true` when passed a `Machine` that has been started by the underlying infrastructure (machine state is `MachineState.PENDING` or `MachineState.RUNNING`).
`static com.google.common.base.Function<? super Machine,Long>` `remainingInstanceHourTime()` Returns a `Function` that given a `Machine` returns the remaining time (in seconds) to the start of its next hour.
`static com.google.common.base.Function<? super Machine,com.google.common.base.Optional<Long>>` `requestAge(org.joda.time.DateTime now)` Optionally returns how many milliseconds ago a request was made.
`void` `setMachineState(MachineState machineState)` Sets the execution state of the `Machine`.
`static List<Machine>` `sort(Collection<Machine> machines, Comparator<Machine> comparator)` Sorts a collection of `Machine`s according to the order prescribed by a certain `Comparator`.
`static com.google.common.base.Function<? super Machine,String>` `toId()` Returns a transformation `Function` that given a `Machine` extracts its identifier.
`static com.google.common.base.Function<Machine,Machine>` `toShortFormat()` Factory method for the `Machine.ToShortMachineFormat` `Function`.
`static com.google.common.base.Function<Machine,String>` `toShortString()` Factory method for the `Machine.ToShortMachineString` `Function`.
`static com.google.common.base.Function<? super Machine,MachineState>` `toState()` Returns a transformation `Function` that given a `Machine` extracts its `MachineState`.
`String` `toString()`
`Machine` `withMetadata(com.google.gson.JsonObject metadata)` Creates a copy of this `Machine` with a different value for the metadata field.

### Methods inherited from class java.lang.Object

`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

### Constructor Detail

#### Machine

    protected Machine(String id,
                      MachineState machineState,
                      MembershipStatus membershipStatus,
                      ServiceState serviceState,
                      String cloudProvider,
                      String region,
                      String machineSize,
                      org.joda.time.DateTime requestTime,
                      org.joda.time.DateTime launchTime,
                      List<String> publicIps,
                      List<String> privateIps,
                      com.google.gson.JsonElement metadata)

Constructs a new `Machine`.

Parameters:
  `id` - The identifier of the `Machine`.
  `machineState` - The execution state of the `Machine`.
  `membershipStatus` - The pool membership status of this `Machine`.
  `serviceState` - The operational state of the service running on the `Machine`.
  `cloudProvider` - The name of the cloud provider that this `Machine` originates from. For example, `AWS-EC2`.
  `region` - The name of the cloud region/zone/data center where this machine is located. For example, `us-east-1`.
  `machineSize` - The size (or type) of the `Machine`. For example, `m1.medium` for an Amazon EC2 `CloudPool`.
  `requestTime` - The request time of the `Machine`, if this time is known. If the time when the machine was initially and successfully requested is not known, this attribute shall be `null`.
  `launchTime` - The launch time of the `Machine` if it has been launched. This attribute may be `null`, depending on the state of the `Machine`.
  `publicIps` - The list of public IP addresses associated with this `Machine`. If the machine hasn't (yet) been assigned any IP addresses, this attribute can be set to `null` or an empty list.
  `privateIps` - The list of private IP addresses associated with this `Machine`. If the machine hasn't (yet) been assigned any IP addresses, this attribute can be set to `null` or an empty list.
  `metadata` - Additional cloud provider-specific meta data about the `Machine`. May be `null`.

### Method Detail

#### getId

    public String getId()

Returns the identifier of the `Machine`.

Returns:

#### getMachineState

    public MachineState getMachineState()

Returns the execution state of the `Machine`.

Returns:

#### setMachineState

    public void setMachineState(MachineState machineState)

Sets the execution state of the `Machine`.

Parameters:
  `machineState` -

#### getMembershipStatus

    public MembershipStatus getMembershipStatus()

Returns the pool membership status of this `Machine`.

Returns:

#### getServiceState

    public ServiceState getServiceState()

Returns the service state of the `Machine`.

Returns:

#### getCloudProvider

    public String getCloudProvider()

Returns The name of the cloud provider that this machine originates from, for example `AWS-EC2`. It might not be immediately apparent why this field is required since the cloud pool itself states which cloud provider it supports, but it is useful to distinguish where different machines originate from in multi-cloud scenarios where multiple down-stream cloud pools are abstracted by an upstream aggregating cloud pool (such as a splitter pool). Without this field, an autoscaler would not be able to tell from which clouds different machines originate (which it may need to know, from an accounting/billing perspective).

Returns:

#### getRegion

    public String getRegion()

Returns the name of the cloud region/zone/data center where this machine is located. For example, `us-east-1`.

Returns:

#### getMachineSize

    public String getMachineSize()

Return the size (or type) of the `Machine`. For example, `m1.medium` for an Amazon EC2 `CloudPool`.

Returns:

#### getLaunchTime

    public org.joda.time.DateTime getLaunchTime()

Returns the launch time of the `Machine` if it has been launched. This attribute may be `null`, depending on the state of the `Machine`.

Returns:

#### getRequestTime

    public org.joda.time.DateTime getRequestTime()

Returns the request time of the `Machine`. This attribute shall be set immediately when a VM has been successfully requested from the cloud backend. It may be null, if the cloud pool has no way of determining the correct value, e.g., if it was started with a pool of VMs already allocated and there is no way to find out when they were requested.

Returns:
  A `DateTime` object with the request time if set. Otherwise `null`.

#### getPublicIps

    public List<String> getPublicIps()

Returns the list of public IP addresses associated with this `Machine`. Depending on the state of the `Machine`, this list may be empty.

Returns:

#### getPrivateIps

    public List<String> getPrivateIps()

Returns the list of private IP addresses associated with this `Machine`. Depending on the state of the `Machine`, this list may be empty.

Returns:

#### getMetadata

    public com.google.gson.JsonElement getMetadata()

Returns any additional cloud provider-specific meta data about the `Machine` if set, otherwise `null`.

Returns:

#### hashCode

    public int hashCode()

Overrides:
  `hashCode` in class `Object`

#### equals

    public boolean equals(Object obj)

Overrides:
  `equals` in class `Object`

#### toString

    public String toString()

Overrides:
  `toString` in class `Object`

#### withMetadata

    public Machine withMetadata(com.google.gson.JsonObject metadata)

Creates a copy of this `Machine` with a different value for the metadata field.

Parameters:
  `metadata` - Metadata to set for the `Machine` copy, or `null` if no metadata is desired.
Returns:
  A copy

#### toState

    public static com.google.common.base.Function<? super Machine,MachineState> toState()

Returns a transformation `Function` that given a `Machine` extracts its `MachineState`.

Returns:

#### toId

    public static com.google.common.base.Function<? super Machine,String> toId()

Returns a transformation `Function` that given a `Machine` extracts its identifier.

Returns:

#### remainingInstanceHourTime

    public static com.google.common.base.Function<? super Machine,Long> remainingInstanceHourTime()

Returns a `Function` that given a `Machine` returns the remaining time (in seconds) to the start of its next hour.

Returns:

#### requestAge

    public static com.google.common.base.Function<? super Machine,com.google.common.base.Optional<Long>> requestAge(org.joda.time.DateTime now)

Optionally returns how many milliseconds ago a request was made.

Parameters:
  `now` - The time to regard as the current time.
Returns:
  A `Function` that given a `Machine` and the current time returns how many milliseconds ago it was requested from the underlying cloud infrastructure. Since not all clouds support reporting how old a request is, the return value is optional.

#### instanceHourStart

    public static com.google.common.base.Function<? super Machine,org.joda.time.DateTime> instanceHourStart()

Returns a `Function` that given a `Machine` (with a launch time set) returns the starting point of the `Machine`'s most recently started hour.

Returns:

#### inState

    public static com.google.common.base.Predicate<? super Machine> inState(MachineState state)

Returns a `Predicate` that returns `true` when passed a `Machine` in a given `MachineState`.

Parameters:
  `state` - The `MachineState` for which this `Predicate` will return `true`.
Returns:

#### isActiveMember

    public static com.google.common.base.Predicate<Machine> isActiveMember()

Returns a `Predicate` that returns `true` when passed a `Machine` that is an active pool member -- it has been allocated from the underlying infrastructure (`MachineState.REQUESTED`, `MachineState.PENDING` or `MachineState.RUNNING`) and is an active pool member (`MembershipStatus.isActive()`).

Returns:

#### isAllocated

    public static com.google.common.base.Predicate<Machine> isAllocated()

Returns a `Predicate` that returns `true` when passed a `Machine` that has been allocated from the underlying infrastructure (machine state `MachineState.REQUESTED`, `MachineState.PENDING` or `MachineState.RUNNING`).

Returns:

#### isStarted

    public static com.google.common.base.Predicate<Machine> isStarted()

A `Predicate` that returns `true` when passed a `Machine` that has been started by the underlying infrastructure (machine state is `MachineState.PENDING` or `MachineState.RUNNING`).

See Also:
  `MachineState`

#### isEvictable

    public static com.google.common.base.Predicate<Machine> isEvictable()

Returns a `Predicate` that returns `true` for any `Machine` with an evictable `MembershipStatus`.

Returns:

#### sort

    public static List<Machine> sort(Collection<Machine> machines,
                                     Comparator<Machine> comparator)

Sorts a collection of `Machine`s according to the order prescribed by a certain `Comparator`.

Parameters:
  `machines` -
  `comparator` -
Returns:

#### toShortFormat

    public static com.google.common.base.Function<Machine,Machine> toShortFormat()

Factory method for the `Machine.ToShortMachineFormat` `Function`.

Returns:

#### toShortString

    public static com.google.common.base.Function<Machine,String> toShortString()

Factory method for the `Machine.ToShortMachineString` `Function`.

Returns:

#### builder

    public static Machine.Builder builder()

Creates a `Machine.Builder` object for generating `Machine` instances.

Returns: