wt.eff.format
Interface EffFormatService

All Known Implementing Classes:

StandardEffFormatService

public interface EffFormatService

EffFormatService accepts "messages" that are of interest to Effectivity Format classes. For the most part, the service does some pre and post processing but eventually delegates the actual work to the actual format classes. This service interface also defines some other operations of interest to clients such as retrieving the effectivity format in a context.

The right format for the current context is found by using the EffFormatFactory's services. The EffFormatFactory deals with the actual finding of the format class. This service is loosely coupled to the format classes and only depends on its interfaces.



Supported API: true

Extendable: false

Since:

Windchill 9.0

See Also:

EffFormat, EffFormatHelper, EffFormatException

Method Summary

String	addToRangeValue(String rangeValue, int amount, EffState state) Add the amount to the effecitivity range value passed in.
int	compareRangeValues(String leftValue, String rightValue, EffState state) This operation is used by Windchill to find whether the left and right eff.
String	decrementRangeValue(String rangeValue, EffState state) Decrements the effecitivity range value passed in by 1.
String	incrementRangeValue(String rangeValue, EffState state) Increments the effecitivity range value passed in by 1.
boolean	isAdjacentTo(String leftValue, String rightValue, EffState state) This operation is used by Windchill to find whether the left and right eff.
boolean	supportsRangeArithmetic(EffState state) Determines whether range arithmetic is supported for the criteria specified in the state object.
String	validateRangeValues(EffRangeValues range, EffState state) Checks whether the range value adheres to right format.

Method Detail

validateRangeValues

String validateRangeValues(EffRangeValues range,
                           EffState state)
                           throws WTException

Checks whether the range value adheres to right format. This operation does not throw a checked or an intentional unchecked exception when the range value to be validated is null or is invalid. An appropriate String error message is returned on those occasions stating the reasons for its invalidity. An empty String ("") object signifies that the range value passed in is valid.

It is expected that this method is called after normalizing the range values (See #normalizeRangeValues(EffRangeValues range, EffState state)).

Sample usage:

 // create EffRangeValues and EffState instances
 rangeValues = EffFormatHelper.service.normalizeRangeValues(rangeValues,
 state);   // get normalized range values
 String errStr = EffFormatHelper.service.validateRangeValues(rangeValues,
 state);
 if (EffFormatHelper.isEmptyOrNull(errStr)) {
    // valid
    // EffFormat implementations return an empty string when the range
 values are valid
 } else {
    // errStr details the error condition
    // EffFormat implementations return a non-empty string when the
 range values are invalid
 }
 

An effectivity range is considered valid when the following conditions are true:

• The start value is not null and is valid
• If the end value is not null, it is also valid and greater than the end value.

Supported API: true

Parameters:

rangeValues - an EffRangeValues object that contains the string range values to be validated. UnitEffFormat's validate considering their format's logic. DateEffFormat's validate it considering a string value having a pattern supported by the system's locale. See wt.query.dateHelperResource for a list of valid format patterns available for a particular locale. Null values are valid values and are treated as invalid and hence an appropriate String error message is returned.

state - a wt.eff.format.EffState object recording the the various attributes of interest to the this operation

Returns:

An empty string if the range values are valid, else a string describing the reason of their invalidity. A null value is never returned.

Throws:

wt.eff.EffFormatExceptionwhen - the range or state parameter is null

WTException

compareRangeValues

int compareRangeValues(String leftValue,
                       String rightValue,
                       EffState state)
                       throws WTException

This operation is used by Windchill to find whether the left and right eff. ranges "overlap", in which case the right range is 'merged' into the left.

Compares the left (first) effectivity range value with the right (second) value, provided the range values passed in are valid, else, throws an EffFormatException which essentially states to validate the range values first.


Supported API: true

Parameters:

leftValue - this value is expected to be a valid string representing a unit number for UnitEffFormat's. For DateEffFormat's this value is expected to be a valid string representation of the time in milliseconds since January 1, 1970, 00:00:00 GMT, which is generally obtained by calling the java.sql.Timestamp.getTime() method to get the long time value and then converting it to a String object by using the static java.lang.Long.toString() method. Null values are not valid values and an EffFormatException (unchecked) is thrown on those occasions. Also, the range value must be a valid one.

rightValue - this value is expected to be a validstring representing a unit number for UnitEffFormat's. For DateEffFormat's this value is expected to be a valid string representation of the time in milliseconds since January 1, 1970, 00:00:00 GMT, which is generally obtained by calling the java.sql.Timestamp.getTime() method to get the long time value and then converting it to a String object by using the static java.lang.Long.toString() method. Null values are not valid values and an EffFormatException (unchecked) is thrown on those occasions. Also, the range value must be a valid one.

state - a wt.eff.format.EffState object recording the the various attributes of interest to the this operation

Returns:

The value 0 if the left effectivity value is equal to right effectivity value; a value less than 0 if the left effectivity value is less than the right effectivity value; and a value greater than 0 if this left effectivity value is greater than the right effectivity value.

Throws:

wt.eff.EffFormatExceptionwhen - the leftValue, rightValue or state parameter is null.

wt.eff.EffFormatExceptionwhen - the leftValue or rightValue is invalid. Only valid range values are accepted by this method and hence the range values must be first validated.

WTException

isAdjacentTo

boolean isAdjacentTo(String leftValue,
                     String rightValue,
                     EffState state)
                     throws WTException

This operation is used by Windchill to find whether the left and right eff. ranges "touch", in which case the right range is 'merged' into the left.

Determines whether the left (first) effectivity range value is adjacent to (exactly one unit less than the other) the right (second) value, provided the range values passed in are valid, else, throws an EffFormatException which essentially states to validate the range values first.


Supported API: true

Parameters:

leftValue - this value is expected to be a valid string representing a unit number for UnitEffFormat's. For DateEffFormat's this value is expected to be a valid string representation of the time in milliseconds since January 1, 1970, 00:00:00 GMT, which is generally obtained by calling the java.sql.Timestamp.getTime() method to get the long time value and then converting it to a String object by using the static java.lang.Long.toString() method. Null values are not valid values and an EffFormatException (unchecked) is thrown on those occasions. Also, the range value must be a valid one.

rightValue - this value is expected to be a validstring representing a unit number for UnitEffFormat's. For DateEffFormat's this value is expected to be a valid string representation of the time in milliseconds since January 1, 1970, 00:00:00 GMT, which is generally obtained by calling the java.sql.Timestamp.getTime() method to get the long time value and then converting it to a String object by using the static java.lang.Long.toString() method. Null values are not valid values and an EffFormatException (unchecked) is thrown on those occasions. Also, the range value must be a valid one.

state - a wt.eff.format.EffState object recording the the various attributes of interest to the this operation

Returns:

The value 0 if the left effectivity value is equal to right effectivity value; a value less than 0 if the left effectivity value is less than the right effectivity value; and a value greater than 0 if this left effectivity value is greater than the right effectivity value.

Throws:

wt.eff.EffFormatExceptionwhen - the leftValue, rightValue or state parameter is null.

wt.eff.EffFormatExceptionwhen - the leftValue or rightValue is invalid. Only valid range values are accepted by this method and hence the range values must be first validated.

WTException

supportsRangeArithmetic

boolean supportsRangeArithmetic(EffState state)
                                throws WTException

Determines whether range arithmetic is supported for the criteria specified in the state object. Windchill uses range arithmetic for operations such as sibling propagation (closing-off effectivity range values of prior versions). In order to support range arithmetic, an effectivity format must provide an implementation of the #addToRangeValue(String, int, EffState, java.util.Map{@literal }) operation.

If format implementations need to support range arithmetic, they must override this method to return a true value. See the Customizer's Guide to find out more about range arithmetic operations and how they can be used to support operations like closing off prior effectivity ranges.

Supported API: true

Parameters:

state -

Returns:

True if the format supports range arithmetic; false otherwise.

Throws:

WTException

See Also:

addToRangeValue(String, int, EffState)

addToRangeValue

String addToRangeValue(String rangeValue,
                       int amount,
                       EffState state)
                       throws WTException

Add the amount to the effecitivity range value passed in. The amount can be negative value, in which case the format decrements the range value by that amount.This operation is optional for effectivity formats to implement and is only implemented if it supports range arithmetic.


Supported API: true

Parameters:

rangeValue - this value is expected to be a validstring representing a unit number for UnitEffFormat's. For DateEffFormat's this value is expected to be a valid string representation of the time in milliseconds since January 1, 1970, 00:00:00 GMT, which is generally obtained by calling the java.sql.Timestamp.getTime() method to get the long time value and then converting it to a String object by using the static java.lang.Long.toString() method. Null values are not valid values and an EffFormatException (unchecked) is thrown on those occasions. Also, the range value must be a valid one.

amount - the value to be added (if positive) or subtracted (if negative) from the rangeValue

state - a wt.eff.format.EffState object recording the the various attributes of interest to the this operation

Returns:

the value after the addition operation.

Throws:

wt.eff.EffFormatExceptionwhen - the rangeValue or state parameter is null.

wt.eff.EffFormatExceptionwhen - the rangeValue is invalid. Only valid range values are accepted by this method and hence the range value must be first validated.

WTException

See Also:

#supportsRangeArithmetic()

incrementRangeValue

String incrementRangeValue(String rangeValue,
                           EffState state)
                           throws WTException

Increments the effecitivity range value passed in by 1. This operation is optional for effectivity formats to implement and is only implemented if it supports range arithmetic.


Supported API: true

Parameters:

rangeValue - this value is expected to be a validstring representing a unit number for UnitEffFormat's. For DateEffFormat's this value is expected to be a valid string representation of the time in milliseconds since January 1, 1970, 00:00:00 GMT, which is generally obtained by calling the java.sql.Timestamp.getTime() method to get the long time value and then converting it to a String object by using the static java.lang.Long.toString() method. Null values are not valid values and an EffFormatException (unchecked) is thrown on those occasions. Also, the range value must be a valid one.

state - a wt.eff.format.EffState object recording the the various attributes of interest to the this operation

Returns:

the value after the increment operation.

Throws:

wt.eff.EffFormatExceptionwhen - the rangeValue or state parameter is null.

wt.eff.EffFormatExceptionwhen - the rangeValue is invalid. Only valid range values are accepted by this method and hence the range value must be first validated.

WTException

See Also:

#supportsRangeArithmetic(), addToRangeValue(String, int, EffState)

decrementRangeValue

String decrementRangeValue(String rangeValue,
                           EffState state)
                           throws WTException

Decrements the effecitivity range value passed in by 1. This operation is optional for effectivity formats to implement and is only implemented if it supports range arithmetic.


Supported API: true

Parameters:

rangeValue - this value is expected to be a validstring representing a unit number for UnitEffFormat's. For DateEffFormat's this value is expected to be a valid string representation of the time in milliseconds since January 1, 1970, 00:00:00 GMT, which is generally obtained by calling the java.sql.Timestamp.getTime() method to get the long time value and then converting it to a String object by using the static java.lang.Long.toString() method. Null values are not valid values and an EffFormatException (unchecked) is thrown on those occasions. Also, the range value must be a valid one.

state - a wt.eff.format.EffState object recording the the various attributes of interest to the this operation

Returns:

the value after the decrement operation.

Throws:

wt.eff.EffFormatExceptionwhen - the rangeValue or state parameter is null.

wt.eff.EffFormatExceptionwhen - the rangeValue is invalid. Only valid range values are accepted by this method and hence the range value must be first validated.

WTException

See Also:

#supportsRangeArithmetic(), addToRangeValue(String, int, EffState)