wt.eff.format
Class StandardEffFormatService

java.lang.Object
  wt.services.StandardManager
      wt.eff.format.StandardEffFormatService

All Implemented Interfaces:

Serializable, EffFormatService, NetFactor, wt.services.Manager

public class StandardEffFormatService
extends StandardManager
implements EffFormatService, Serializable

Standard implementation of the EffFormatService interface.

Note: All implementing methods that accept range values trim (@link java.lang.String#trim()} them before sending it to the actual format implementations to provide consistentency in the implementation logic from the service perspective.

Use the newStandardEffFormatService static factory method(s), not the StandardEffFormatService constructor, to construct instances of this class. Instances must be constructed using the static factory(s), in order to ensure proper initialization of the instance.

Supported API: true

Extendable: false

Since:

Windchill 9.0

See Also:

EffFormatService, EffFormatException, Serialized Form

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.

Methods inherited from class wt.services.StandardManager

getManagerService, getManagerStatus, getName, getStartupType

Methods inherited from class java.lang.Object

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

Method Detail

validateRangeValues

public 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

Specified by:

validateRangeValues in interface EffFormatService

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

public 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

Specified by:

compareRangeValues in interface EffFormatService

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

public 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

Specified by:

isAdjacentTo in interface EffFormatService

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

public 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

Specified by:

supportsRangeArithmetic in interface EffFormatService

Parameters:

state -

Returns:

True if the format supports range arithmetic; false otherwise.

Throws:

WTException

See Also:

addToRangeValue(String, int, EffState)

addToRangeValue

public 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

Specified by:

addToRangeValue in interface EffFormatService

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

public 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

Specified by:

incrementRangeValue in interface EffFormatService

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

public 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

Specified by:

decrementRangeValue in interface EffFormatService

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)