Package wt.eff.format

Interface EffFormat

All Known Implementing Classes:
AbstractEffFormat, AlphaNumericUnitEffFormat, DefaultUnitEffFormat, NumericUnitEffFormat, UnitEffFormat
public interface EffFormat
General Documentation: This interface and its supporting implementations provide the capability of specifying formats, the effectivity statements follow. This allows users to accurately specify how the various supported operations are implemented, giving them a chance to customize them, if they are not satisfactory. These include operations for comparisons, validation and range arithmetic. These formats are further driven by parameters, the users can specify, which are external to the format implementation and exist to provide meta-data related to the format in question. This is especially important, because the formats themselves are intended to be stateless, providing mere business logic.

Technical Documentation: This is the top-level interface of all Effectivity Format classes. It states the contract that an effectivity format must implement. Eff. Format classes are not instantiated directly by clients, but are created and managed by the format factory EffFormatFactory, which encapsulates the logic of creation and looking-up Eff. Format classes.

All concrete subclasses of this class are intended to be stateless. Hence they run as singleton objects, safely shared and managed by the EffFormatFactory. Identity of an Eff. Format is also class based and not instance-based. All instances of a format class, share their identities. Hence effectivity formats do not need to implement Object's equals() and hashCode() methods. Two Eff. Format object instances x and y are equal if and only if x and y refer to the same object (x == y has the value true).

Documentation for Custom Effectivity Format Implementations: To provide customized effectivity format implementations, customizers can either implement this interface or extend any of the documented extendable format classes, as per your needs. See the Customizer's Guide for more information, where you will also find details on how to specify effectivity format implementations for use by the system.


Supported API: true

Extendable: true
Since:
Windchill 9.0
See Also:

  • Method Details

    • getDisplayName

      String getDisplayName(Locale locale)
      Returns the (localizable) name of this format implementation. It can be used for presenting in the user interface or logging for example.

      Supported API: true
      Parameters:
      locale - the locale to be used to determine the display name of this format
      Returns:
      the displayable name of this format.
      See Also:
      • wt.eff.format#getDisplayDescription()

    • getDisplayDescription

      String getDisplayDescription(Locale locale)
      Returns the (localizable) description of this format implementation. It can be used for presenting in the user interface or logging for example.

      Supported API: true
      Parameters:
      locale - the locale to be used to determine the description of this format
      Returns:
      the displayable description of this format.
      See Also:
      • wt.eff.format#getDisplayName()

    • validateRangeValue

      String validateRangeValue(String rangeValue, EffState state, Map<String,String> formatParams, boolean isStartRange)
      Checks whether the range value adheres to right format. Note: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.

      Sample usage (only intended for use by EffFormatService): 
       String errStr = validateRangeValue(...)
 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
 }


      Supported API: true
      Parameters:
      rangeValue - the string range value 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
      formatParams - a Map<String, String> object with the param name as the key (lowercase) and the value is associated with the key as originally specified (See the Customizer's Guide for details on how to associate format parameters with a particular format)
      isStartRange - indicates that range passed in is start range.
      Returns:
      An empty string if the range value is valid, else a string describing the reason of its invalidity. A null value is never returned.

    • compareRangeValues

      int compareRangeValues(String leftValue, String rightValue, EffState state, Map<String,String> formatParams) throws EffFormatException
      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. It is not used by the effectivity configuration specification and other clients. They continue to use their comparison logic, and hence it is important to not implement this operation for those purposes.

      Compares the left (first) effectivity range value with the right (second) value if the range value 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:
      EffFormatException - when the range values or other required paramters passed in are null or when the range values can not be parsed and hence are invalid. Only valid range values are expected as arguments and hence the range values must be first validated before calling this operation.
      EffFormatException

    • supportsRangeArithmetic

      boolean supportsRangeArithmetic()
      Determines whether this effectivity format supports range arithmetic. 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
      Returns:
      True if the format supports range arithmetic; false otherwise.

    • addToRangeValue

      String addToRangeValue(String rangeValue, int amount, EffState state, Map<String,String> formatParams) throws EffFormatException
      Add the amount to the effecitivity range value passed in, if the range value passed in are valid. Else, throws an EffFormatException which essentially states to validate the range first.

      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
      formatParams - a Map<String, String> object with the param name as the key (lowercase) and the value is associated with the key as originally specified (See the Customizer's Guide for details on how to associate format parameters with a particular format)
      Returns:
      the value after the addition operation.
      Throws:
      EffFormatException - when the range value or other required paramters passed in are null or when the range values can not be parsed and hence are invalid. Only valid range values are expected as arguments and hence the range values must be first validated before calling this operation.
      EffFormatException
      See Also:

    • formatRangeValue

      String formatRangeValue(String sRangeValue, EffState effState, Map<String,String> mapFormatParams)
      This method formats a range value for those formats which specify formatting of the value. Currently, the numeric and alphanumeric formats will prepend zeroes onto the number (or the numeric portion of the number in the case of alphanumeric) to extend the number out to its defined length. The method will assume the passed in string is correct aside from the lack of preformatted zeroes and will only insert the zeroes if possible, and will do no other formatting. If the method cannot reliably autopopulate the zeroes, it will return the string as is. If the string passed in is already as long or longer than the format specifies, the method returns the string as is.

      Example: If you define a numeric format of length 8, and a user enters "123" as a unit number in the client, this method will return "00000123". Similarily, if you define an alphanumeric format of length 10 and prefix "ABC", and in the client enter "ABC123", this method will return "ABC0000123".



      Supported API: true

      Parameters:
      sRangeValue -
      effState -
      mapFormatParams -
      Returns:
      String