Package com.sas.services.util

# Class WaitPolicy

java.lang.Object
com.sas.services.util.WaitPolicy

public class WaitPolicy extends Object
Defines a wait policy. This class defines a wait policy. Typically a consumer using an API will specify a wait policy (construct an object of this class) if API uses a resource which needs to be locked. The API implementer will use the wait policy in conjunction with the `Waiter` class to determine how frequently to test for the availability of the resource.

A wait policy of `WaitPolicy.TYPE.NONE` implies the consumer does not want to wait. An API implementer when encountering a locked resource should notify the consumer that the operation could not be performed since the consumer has requested that waiting not be done.

A wait policy of `WaitPolicy.TYPE.FINITE` implies the consumer is prepared to wait a finite amount of time. An API implementer when encountering a locked resource will poll it at the intervals specified in this policy using `Waiter.sleep()`. If at the end of the time specified by the consumer, the resource is still locked behavior is similar to the `WaitPolicy.TYPE.NONE` case encountering a locked resource.

A wait policy of `WaitPolicy.TYPE.INFINITE` implies the consumer is prepared to wait an infinite amount of time. An API implementer when encountering a locked resource will poll it at the intervals specified in this policy using `Waiter.sleep()`. Since no time limit has been specified the polling is only stopped once the resource is unlocked.

The values specified for initialWait, waitIncrement, minimumWait, maximumWait and totalWait dictate the behavior of the `Waiter.sleep()`. initialWait sets the time for the first sleep. waitIncrement can be either positive or negative and subsequent sleep periods are adjusted by waitIncrement subject to the bounds imposed by minimumWait and maximumWait. totalWait is only used in the `WaitPolicy.TYPE.FINITE` case.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `WaitPolicy.TYPE`
  The "type" of wait.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `INITIAL_WAIT_KEY`
  `static final int`
  `INITIAL_WAIT_VALUE_N`
  `static final String`
  `INITIAL_WAIT_VALUE_S`
  `static final String`
  `MAXIMUM_WAIT_KEY`
  `static final int`
  `MAXIMUM_WAIT_VALUE_N`
  `static final String`
  `MAXIMUM_WAIT_VALUE_S`
  `static final String`
  `MINIMUM_WAIT_KEY`
  `static final int`
  `MINIMUM_WAIT_VALUE_N`
  `static final String`
  `MINIMUM_WAIT_VALUE_S`
  `static final String`
  `TOTAL_WAIT_KEY`
  `static final long`
  `TOTAL_WAIT_VALUE_N`
  `static final String`
  `TOTAL_WAIT_VALUE_S`
  `static final String`
  `WAIT_INCREMENT_KEY`
  `static final int`
  `WAIT_INCREMENT_VALUE_N`
  `static final String`
  `WAIT_INCREMENT_VALUE_S`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `WaitPolicy(WaitPolicy.TYPE type)`
  Construct a wait policy using default values.
  `WaitPolicy(WaitPolicy.TYPE type, int initialWait, int waitIncrement, int minimumWait, int maximumWait, long totalWait)`
  Construct a wait policy using the values specified.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static WaitPolicy`
  `getDefaultWaitPolicy(WaitPolicy.TYPE type, String prefix)`
  Gets the default wait policy.
  `int`
  `getInitialWait()`
  `int`
  `getMaximumWait()`
  `int`
  `getMinimumWait()`
  `long`
  `getTotalWait()`
  `WaitPolicy.TYPE`
  `getType()`
  `int`
  `getWaitIncrement()`

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

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

- ## Field Details

  - ### INITIAL_WAIT_KEY

    public static final String INITIAL_WAIT_KEY
    See Also:
      - Constant Field Values

  - ### INITIAL_WAIT_VALUE_N

    public static final int INITIAL_WAIT_VALUE_N
    See Also:
      - Constant Field Values

  - ### INITIAL_WAIT_VALUE_S

    public static final String INITIAL_WAIT_VALUE_S
    See Also:
      - Constant Field Values

  - ### WAIT_INCREMENT_KEY

    public static final String WAIT_INCREMENT_KEY
    See Also:
      - Constant Field Values

  - ### WAIT_INCREMENT_VALUE_N

    public static final int WAIT_INCREMENT_VALUE_N
    See Also:
      - Constant Field Values

  - ### WAIT_INCREMENT_VALUE_S

    public static final String WAIT_INCREMENT_VALUE_S
    See Also:
      - Constant Field Values

  - ### MINIMUM_WAIT_KEY

    public static final String MINIMUM_WAIT_KEY
    See Also:
      - Constant Field Values

  - ### MINIMUM_WAIT_VALUE_N

    public static final int MINIMUM_WAIT_VALUE_N
    See Also:
      - Constant Field Values

  - ### MINIMUM_WAIT_VALUE_S

    public static final String MINIMUM_WAIT_VALUE_S
    See Also:
      - Constant Field Values

  - ### MAXIMUM_WAIT_KEY

    public static final String MAXIMUM_WAIT_KEY
    See Also:
      - Constant Field Values

  - ### MAXIMUM_WAIT_VALUE_N

    public static final int MAXIMUM_WAIT_VALUE_N
    See Also:
      - Constant Field Values

  - ### MAXIMUM_WAIT_VALUE_S

    public static final String MAXIMUM_WAIT_VALUE_S
    See Also:
      - Constant Field Values

  - ### TOTAL_WAIT_KEY

    public static final String TOTAL_WAIT_KEY
    See Also:
      - Constant Field Values

  - ### TOTAL_WAIT_VALUE_N

    public static final long TOTAL_WAIT_VALUE_N
    See Also:
      - Constant Field Values

  - ### TOTAL_WAIT_VALUE_S

    public static final String TOTAL_WAIT_VALUE_S
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### WaitPolicy

    public WaitPolicy(WaitPolicy.TYPE type) throws ServiceException
    Construct a wait policy using default values. This method is typically used to construct a policy of `WaitPolicy.TYPE.NONE`. For other types of policies the values used will be static fields ending with the "_N" suffix defined by this class.
    Parameters:
      `type` - the type of the policy
    Throws:
      `ServiceException`

  - ### WaitPolicy

    public WaitPolicy(WaitPolicy.TYPE type, int initialWait, int waitIncrement, int minimumWait, int maximumWait, long totalWait) throws ServiceException
    Construct a wait policy using the values specified. If the type desired is `WaitPolicy.TYPE.NONE` values specified for the other parameters are ignored. If the type desired is `WaitPolicy.TYPE.INFINITE` the value for totalWait is ignored. The units for the value of all parameters except type is milliseconds.
    Parameters:
      `type` - the type of the policy
      `initialWait` - the duration of the first wait
      `waitIncrement` - the change (positive or negative) in wait time for subsequent waits
      `minimumWait` - the lower bound on the wait time
      `maximumWait` - the upper bound on the wait time
      `totalWait` - the total time to wait
    Throws:
      `ServiceException`

- ## Method Details

  - ### getType

    public WaitPolicy.TYPE getType()

  - ### getInitialWait

    public int getInitialWait()

  - ### getWaitIncrement

    public int getWaitIncrement()

  - ### getMinimumWait

    public int getMinimumWait()

  - ### getMaximumWait

    public int getMaximumWait()

  - ### getTotalWait

    public long getTotalWait()

  - ### getDefaultWaitPolicy

    public static WaitPolicy getDefaultWaitPolicy(WaitPolicy.TYPE type, String prefix) throws ServiceException
    Gets the default wait policy. Constructs a `WaitPolicy` whose type is that specified by the type parameter and values obtained from the environment. The values it uses for the constructor are the values obtained using the prefix parameter, a known suffix and the System.getProperty() method.

    An example is used to illustrate the process. If the prefix parameter has a value of "com.sas.mypackage", then the initial wait value obtained by appending a dot and `INITIAL_WAIT_KEY` (whose value is "InitialWait") to the prefix results in a key of "com.sas.mypackage.InitialWait" which is used in a call to System.getProperty(). The default value used if there is no such property defined is the value of `INITIAL_WAIT_VALUE_S`.

    If the type requested is `WaitPolicy.TYPE.NONE`, no attempt is made to obtain values.

    If the type requested is `WaitPolicy.TYPE.INFINITE`, no attempt is made to obtain the total wait value which is not needed.

    If a null or an empty prefix is supplied the key used is just the name - "InitialWait" in the example described above.

    Parameters:
      `type` - the type of the policy
      `prefix` - prefix without the trailing dot used to find property value
    Returns:
    Throws:
      `ServiceException` - if invalid values are specified