com.sas.services.util
Class WaitPolicy

com.sas.services.util.WaitPolicy

public class WaitPolicy

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

static class

WaitPolicy.TYPE The "type" of wait.

Field Summary

static java.lang.String	INITIAL_WAIT_KEY
static int	INITIAL_WAIT_VALUE_N
static java.lang.String	INITIAL_WAIT_VALUE_S
static java.lang.String	MAXIMUM_WAIT_KEY
static int	MAXIMUM_WAIT_VALUE_N
static java.lang.String	MAXIMUM_WAIT_VALUE_S
static java.lang.String	MINIMUM_WAIT_KEY
static int	MINIMUM_WAIT_VALUE_N
static java.lang.String	MINIMUM_WAIT_VALUE_S
static java.lang.String	TOTAL_WAIT_KEY
static long	TOTAL_WAIT_VALUE_N
static java.lang.String	TOTAL_WAIT_VALUE_S
static java.lang.String	WAIT_INCREMENT_KEY
static int	WAIT_INCREMENT_VALUE_N
static java.lang.String	WAIT_INCREMENT_VALUE_S

Constructor Summary

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

static WaitPolicy	getDefaultWaitPolicy(WaitPolicy.TYPE type, java.lang.String prefix) Gets the default wait policy.
int	getInitialWait()
int	getMaximumWait()
int	getMinimumWait()
long	getTotalWait()
WaitPolicy.TYPE	getType()
int	getWaitIncrement()

Field Detail

INITIAL_WAIT_KEY

public static final java.lang.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 java.lang.String INITIAL_WAIT_VALUE_S

See Also:

Constant Field Values

WAIT_INCREMENT_KEY

public static final java.lang.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 java.lang.String WAIT_INCREMENT_VALUE_S

See Also:

Constant Field Values

MINIMUM_WAIT_KEY

public static final java.lang.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 java.lang.String MINIMUM_WAIT_VALUE_S

See Also:

Constant Field Values

MAXIMUM_WAIT_KEY

public static final java.lang.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 java.lang.String MAXIMUM_WAIT_VALUE_S

See Also:

Constant Field Values

TOTAL_WAIT_KEY

public static final java.lang.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 java.lang.String TOTAL_WAIT_VALUE_S

See Also:

Constant Field Values

Constructor Detail

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 Detail

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,
                                              java.lang.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