GHNReservation
Date: 2014-06-04

org.gcube.vremanagement.resourcebroker.impl.support.types

## Class GHNReservation

- java.lang.Object
- - org.gcube.vremanagement.resourcebroker.impl.support.types.SortableElement<java.lang.Long,PlanBuilderIdentifier>
  - - org.gcube.vremanagement.resourcebroker.impl.support.types.GHNReservation

- All Implemented Interfaces:
    java.lang.Comparable<SortableElement<java.lang.Long,PlanBuilderIdentifier>>

      public class GHNReservation
      extends SortableElement<java.lang.Long,PlanBuilderIdentifier>

  To keep track of the GHNs that have been reserved during a `PlanBuilderWorkflow` session, to each workflow is associated, in a persistent way, a `GHNReservation`. The reservation essentially consists of an expiration time and a list of `GHNDescriptor` elements that have been reserved for that session. Once the reservation time expires, or a feedback is received from the caller, all the reserved `GHNDescriptor` are restored and made available for further reuse. This solution ensures that until the Reservation is alive all the GHNs assigned to it are not available to other `PlanBuilderWorkflow` sessions. A reservation is supposed to be sorted on the expiration time (a `Long`) and identified by the unique `PlanBuilderIdentifier` of the `PlanBuilderWorkflow` it is involved in. Two `GHNReservation` assigned to the same `PlanBuilderIdentifier` are assumed to be equals, namely for each `PlanBuilderWorkflow` a single reservation can be done. Once created a reservation, the `GHNDescriptor` can be inserted inside it. To each `PlanBuilderElem` of a `PlanBuilderWorkflow` a `GHNReservation` is automatically assigned.
  Author:
    Daniele Strollo (ISTI-CNR)

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `GHNReservation(PlanBuilderIdentifier wfID, long ttl)` Builds a `GHNReservation` to assign to a `PlanBuilderWorkflow` session uniquely identified by its `PlanBuilderIdentifier`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addGHN(GHNDescriptor ghn)` Stores a new `GHNDescriptor` in the list of reserved GHNs in this reservation context.
    `boolean` | `equals(java.lang.Object obj)` Allows to compare a `GHNReservation` with both another `GHNReservation` or a `GHNDescriptor`.
    `java.util.List<GHNDescriptor>` | `getGHNsForScope(GCUBEScope scope)`
    `int` | `hashCode()`
    `boolean` | `isExpired()`
    `void` | `lock()` Deprecated. This method should be only accessed by feedback handling function.
    `void` | `revoke()`
    `void` | `unlock()` Deprecated. This method should be only accessed by feedback handling function.

    - ### Methods inherited from class org.gcube.vremanagement.resourcebroker.impl.support.types.SortableElement

      `compareTo, getElement, getSortIndex, toString`

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

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### GHNReservation

          public GHNReservation(PlanBuilderIdentifier wfID,
                        long ttl)

      Builds a `GHNReservation` to assign to a `PlanBuilderWorkflow` session uniquely identified by its `PlanBuilderIdentifier`. The `SortableElement.getElement()` will return the `PlanBuilderIdentifier` passed at construction phase and is the key element to use for equals. Once created the reservation stores the creation timestamp that can be acceded through `SortableElement.getSortIndex()` method.
      Parameters:
        `ttl` - the time to live for the reservation expressed in mills.
        `wfID` - the `PlanBuilderIdentifier` workflow session.

  - ### Method Detail

    - #### isExpired

          public final boolean isExpired()

      Returns:
        true if the elapsed time is greater than the granted ttl.

    - #### equals

          public final boolean equals(java.lang.Object obj)

      Allows to compare a `GHNReservation` with both another `GHNReservation` or a `GHNDescriptor`. The comparison is done on the GHN unique ID. This method is used to discover `GHNDescriptor` that have been moved inside a private queue of reserved `GHNDescriptor` owned by a workflow.
      Overrides:
        `equals` in class `java.lang.Object`

    - #### hashCode

          public final int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### addGHN

          public final void addGHN(GHNDescriptor ghn)
                            throws GCUBEFault

      Stores a new `GHNDescriptor` in the list of reserved GHNs in this reservation context.
      Parameters:
        `ghn` -
      Throws:
        `GCUBEFault`

    - #### revoke

          public final void revoke()

    - #### getGHNsForScope

          public final java.util.List<GHNDescriptor> getGHNsForScope(GCUBEScope scope)
                                                              throws GCUBEFault

      Throws:
        `GCUBEFault`

    - #### lock

          public final void lock()
                          throws java.lang.InterruptedException

      Deprecated. This method should be only accessed by feedback handling function.
      The locking has been added for ensuring that during the feedback handling a single process access it.
      Throws:
        `java.lang.InterruptedException`

    - #### unlock

          public final void unlock()

      Deprecated. This method should be only accessed by feedback handling function.