Package wt.eff.format

Interface EffFormatService

@RemoteInterface 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:

  • Method Details

    • 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:
      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:
      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:
      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 {@link #addToRangeValue(String, int, EffState, java.util.Map{@literal <String, String>})} 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 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:
      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:
      WTException
      See Also:

    • 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:
      WTException
      See Also: