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:

EffFormatService, EffState, EffRangeValues

Method Summary

String	addToRangeValue(String rangeValue, int amount, EffState state, Map<String,String> formatParams) Add the amount to the effecitivity range value passed in, if the range value passed in are valid.
int	compareRangeValues(String leftValue, String rightValue, EffState state, Map<String,String> formatParams) This operation is used by Windchill to find whether the left and right eff.
String	getDisplayDescription(Locale locale) Returns the (localizable) description of this format implementation.
String	getDisplayName(Locale locale) Returns the (localizable) name of this format implementation.
boolean	supportsRangeArithmetic() Determines whether this effectivity format supports range arithmetic.
String	validateRangeValue(String rangeValue, EffState state, Map<String,String> formatParams, boolean isStartRange) Checks whether the range value adheres to right format.

Method Detail

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 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 #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

Returns:

True if the format supports range arithmetic; false otherwise.

See Also:

#addToRangeValue(String, int, EffState, java.util.Map{@literal })

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

supportsRangeArithmetic()