be.SIRAPRISE.server
Class IntervalTypeImplementation

java.lang.Object
  be.SIRAPRISE.server.IntervalTypeImplementation

All Implemented Interfaces:

PossRepImplementation, TypeImplementation

public final class IntervalTypeImplementation
extends java.lang.Object
implements TypeImplementation, PossRepImplementation

IntervalTypeImplementation generically defines implementation objects for each interval type. The physical encoding for values of any INTERVAL type always has the following structure :

• Physical encoding of the value of the BEGIN() (or FROM()) component.
• A two-byte marker indicating negative and positive infinity of the interval value (i.e. the presence/absence of the BEGIN() and END() components, respectively.
• Physical encoding of the value of the END() component if that is present, or else all binary zeroes.

The length of the physical encoding of a single component is determined by the MAXIMUM logical length of the underlying base type. So the byte length needed to encode an interval value is fixed at (2 + 2 * maxphlength), where maxphlength is the byte size needed to encode a value of the underlying type of maximal logical length. The meaning of the two-byte marker is as follows :

• 0x0000 : interval is wholly finite (i.e. has both a BEGIN() and an END() component)
• 0xFFFF : interval is positive infinite (i.e. has a BEGIN() and no END() component)
• 0xFF00 : interval is negative infinite (i.e. has no BEGIN() component, but does have an END() component).
• 0x00FF : interval is wholly infinite (i.e. has neither a BEGIN() nor an END() component)

Observe that the latter two, which involve negative infinity, are ONLY defined for purposes of possible future implementation, and are currently NOT supported.

Author:

Erwin

Method Summary

java.util.Map<java.lang.String,java.lang.String>	getComponentNameMap() Gets a map of component/type names.
ValueBuffer	getComponentValue(java.lang.String componentName, ScalarValueBuffer valueBuffer) "Extracts" a possrep component value out of a value of the type
PossRepImplementation	getDefaultPossrepImplementation() Gets the possrep implementation that is to be considered the default for the type.
int	getDfltLogicalSize() Gets the default (logical) size of an attribute of this type.
int	getMaxLogicalSize() Gets the maximum logical size of an attribute of this type.
int	getMinLogicalSize() Gets the minimum logical size of an attribute of this type.
int	getPhysicalSizeFor(int logicalSize) Determines the number of bytes needed to encode a value of the given logical size of this type.
PossRepImplementation	getPossrepImplementation(java.lang.String componentName) Gets the PossrepImplementation object implementing the possrep of which the given component name names a component.
java.util.Set<PossRepImplementation>	getPossrepImplementations() Gets the set of all PossRepImplementations for this type.
java.lang.String	getPossrepName() Gets the possrep name
static boolean	isNegativeInfinite(short finitenessIndicator) Checks whether the interval value that the given finiteness indicator was drawn from, lacks a begin component.
static boolean	isPositiveInfinite(short finitenessIndicator) Checks whether the interval value that the given finiteness indicator was drawn from, lacks an end component
ValueBuffer	valueFromComponentValues(java.util.HashMap<java.lang.String,ValueBuffer> componentValueMap, int logicalSize) Returns a ValueBuffer holding the value of the type that this PossRepImplementation is for, and that corresponds to the component values given in the componentValueMap argument.
ValueBuffer	valueFromExternalRepresentation(java.lang.String value) Convert a value of this possrep's type to internal format.
ValueBuffer	valueFromExternalRepresentation(java.lang.String value, int maximumLogicalLengthAllowed) Converts a value of this type from external to internal format, given a specified maximum allowable logical size for the value to be returned.
java.lang.String	valueToEscapedExternalRepresentation(ValueBuffer valueBuffer) Converts a value in internal format to the appropriate textual representation of that value for this possrep.
java.lang.String	valueToExternalRepresentation(ValueBuffer valueBuffer) Converts a value in internal format to the appropriate textual representation of that value for this possrep.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

isNegativeInfinite

public static boolean isNegativeInfinite(short finitenessIndicator)

Checks whether the interval value that the given finiteness indicator was drawn from, lacks a begin component.

0000 ===> false

FFFF ===> false (these values were used to indicate infinity at the time when negative infinity was not yet supported)

00ff ===> true

FF00 ===> true

Parameters:

finitenessIndicator - The finiteNess indicator obtained from some physically recorded interval value

Returns:

true if the indicator indicates that the interval value lacks an begin component

isPositiveInfinite

public static boolean isPositiveInfinite(short finitenessIndicator)

Checks whether the interval value that the given finiteness indicator was drawn from, lacks an end component

Parameters:

finitenessIndicator - The finiteNess indicator obtained from some physically recorded interval value

Returns:

true if the indicator indicates that the interval value lacks an end component

getComponentNameMap

public final java.util.Map<java.lang.String,java.lang.String> getComponentNameMap()

Description copied from interface: PossRepImplementation

Gets a map of component/type names. The keys in the map are the names of the components of this possrep. The values in the map are the typenames corresponding to (the values for) the named component. Since both the keys and the values in the map are all names, they must both be all uppercase. The map can be empty, if this is a possrep that does not consist of components.

Specified by:

getComponentNameMap in interface PossRepImplementation

Returns:

a map of component/type names.

getComponentValue

public final ValueBuffer getComponentValue(java.lang.String componentName,
                                           ScalarValueBuffer valueBuffer)

Description copied from interface: PossRepImplementation

"Extracts" a possrep component value out of a value of the type

Specified by:

getComponentValue in interface PossRepImplementation

Parameters:

componentName - The possrep component Name

valueBuffer - The scalarValueBuffer holding the value of which the possrep's component's value is to be extracted

Returns:

The value of the component in this possrep's representation of the given value

getDefaultPossrepImplementation

public final PossRepImplementation getDefaultPossrepImplementation()

Description copied from interface: TypeImplementation

Gets the possrep implementation that is to be considered the default for the type. If the type does not provide any possrep(implementation)s at all, then this method should return null, and this type will be treated as a singleton type.

Specified by:

getDefaultPossrepImplementation in interface TypeImplementation

Returns:

the possrep implementation that is to be considered the default for the type, or null if the type is a singleton.

getDfltLogicalSize

public final int getDfltLogicalSize()

Description copied from interface: TypeImplementation

Gets the default (logical) size of an attribute of this type. The implementation is responsible for ensuring that the default size is >= the minimum size, and <= the maximum size.

Specified by:

getDfltLogicalSize in interface TypeImplementation

Returns:

the default (logical) size of an attribute of this type.

getMaxLogicalSize

public final int getMaxLogicalSize()

Description copied from interface: TypeImplementation

Gets the maximum logical size of an attribute of this type. If this type has an ordering operator, then the corresponding interval type will have a fixed (i.e. min=max=default) logical size that is equal to twice this maximum size.

Specified by:

getMaxLogicalSize in interface TypeImplementation

Returns:

The maximum logical size of an attribute of this type.

getMinLogicalSize

public final int getMinLogicalSize()

Description copied from interface: TypeImplementation

Gets the minimum logical size of an attribute of this type.

Specified by:

getMinLogicalSize in interface TypeImplementation

Returns:

The minimum logical size of an attribute of this type

getPhysicalSizeFor

public final int getPhysicalSizeFor(int logicalSize)

Description copied from interface: TypeImplementation

Determines the number of bytes needed to encode a value of the given logical size of this type. If the type is variable-length, then the number returned here must be >= 4. These four mandatory bytes are used to hold the actual logical length of the encoded value.

Specified by:

getPhysicalSizeFor in interface TypeImplementation

Parameters:

logicalSize - The logical size of a declared attribute of this type

Returns:

The total number of bytes needed to encode a value of the given logical size of this type, i.e. including the four length bytes that are used in variable-length types to hold the logical length of the value itself.

getPossrepImplementation

public PossRepImplementation getPossrepImplementation(java.lang.String componentName)

Description copied from interface: TypeImplementation

Gets the PossrepImplementation object implementing the possrep of which the given component name names a component. This method is introduced in version 1.3. The method is optional, but implementers are strongly encouraged to add this method to any implementing class they already have developed.

Specified by:

getPossrepImplementation in interface TypeImplementation

Parameters:

componentName - The name of a component of some possrep of this type (and for which the corresponding PossrepImplementation object is to be returned)

Returns:

The PossrepImplementation object implementing the possrep of which the given component name names a component

getPossrepImplementations

public final java.util.Set<PossRepImplementation> getPossrepImplementations()

Description copied from interface: TypeImplementation

Gets the set of all PossRepImplementations for this type.

Specified by:

getPossrepImplementations in interface TypeImplementation

Returns:

The set of all PossRepImplementations for this type.

getPossrepName

public final java.lang.String getPossrepName()

Description copied from interface: PossRepImplementation

Gets the possrep name

Specified by:

getPossrepName in interface PossRepImplementation

Returns:

The possrep name

valueFromComponentValues

public final ValueBuffer valueFromComponentValues(java.util.HashMap<java.lang.String,ValueBuffer> componentValueMap,
                                                  int logicalSize)

Description copied from interface: PossRepImplementation

Returns a ValueBuffer holding the value of the type that this PossRepImplementation is for, and that corresponds to the component values given in the componentValueMap argument.

Specified by:

valueFromComponentValues in interface PossRepImplementation

Parameters:

componentValueMap - A Map holding component names and their corresponding values, held in a ValueBuffer.

logicalSize - The maximum logical size that the returned value is allowed to have. This only applies to certain variable-length types. E.g. imagine that type STRING has a possrep with components LENGTH and NONBLANKS, such that the string represented by LENGTH(12)NONBLANKS(A) represents the string "A ". An InvalidValueException should be thrown if these component values are passed to this method, along with a logicalSize of, say, 8.

Returns:

a ValueBuffer holding the value of the type that this PossRepImplementation is for, and that corresponds to the component values given in the componentValueMap argument.

valueFromExternalRepresentation

public final ValueBuffer valueFromExternalRepresentation(java.lang.String value)
                                                  throws InvalidValueException

Description copied from interface: PossRepImplementation

Convert a value of this possrep's type to internal format. The implementation is responsible for ensuring that the result is within bounds with the possrep's type's minimum or maximum logical size (and thus with the corresponding minimum and maximum physical encoding size). If the type is variable-length, then any length may be chosen for the ByteBuffer returned, as long as the encoding of the value fits within that byteBuffer length. If the encoding of a value takes less bytes than the chosen length, then the remaining bytes must be filled with null bytes (0x00). Failing to obey this rule will subvert certain checksum computations that are done internally by SIRA_PRISE, and thus cause it to possibly produce wrong results. Note that if a type is variable-length, then the first four bytes in the returned ScalarValueBuffer's ByteBuffer must hold the logical length of the value.

Specified by:

valueFromExternalRepresentation in interface PossRepImplementation

Parameters:

value - the value in external format.

Returns:

the value in internal format.

Throws:

InvalidValueException - If the textual representation does not represent a value of the possrep's type.

valueFromExternalRepresentation

public final ValueBuffer valueFromExternalRepresentation(java.lang.String value,
                                                         int maximumLogicalLengthAllowed)
                                                  throws InvalidValueException

Description copied from interface: PossRepImplementation

Converts a value of this type from external to internal format, given a specified maximum allowable logical size for the value to be returned. All SIRA_PRISE's invoking methods guarantee that this size is within bounds with the possrep's type's minimal and maximal logical sizes. So, invocations from other places notwithstanding, this parameter doesn't need checking. If the type is variable-length, then any length may be chosen for the ByteBuffer returned, as long as the encoding of the value fits within that byteBuffer length. If the encoding of a value takes less bytes than the chosen length, then the remaining bytes must be filled with null bytes (0x00). Failing to obey this rule will subvert certain checksum computations that are done internally by SIRA_PRISE, and thus cause it to possibly produce wrong results. Note that if a type is variable-length, then the first four bytes in the returned ScalarValueBuffer's ByteBuffer must hold the logical length of the value.

Specified by:

valueFromExternalRepresentation in interface PossRepImplementation

Parameters:

value - the textual representation of the value.

maximumLogicalLengthAllowed - the maximum logical length that the returned value can be allowed to have.

Returns:

The parsed value, encoded in internal format.

Throws:

InvalidValueException - If the textual representation does not represent a value of the possrep's type.

valueToEscapedExternalRepresentation

public final java.lang.String valueToEscapedExternalRepresentation(ValueBuffer valueBuffer)

Description copied from interface: PossRepImplementation

Converts a value in internal format to the appropriate textual representation of that value for this possrep. In this method, all tokens of the SIRA_PRISE metalanguage must be output in 'escaped' format, i.e. each '(' character in the representation of the value must be represented as the string "\(", each ')' as a "\)" and each '\' as a "\\". Observe that this does NOT apply to the opening and closing parentheses that delimit the value of a component.

Specified by:

valueToEscapedExternalRepresentation in interface PossRepImplementation

Parameters:

valueBuffer - The value in internal format.

Returns:

The string representation of the given value, for this possrep.

valueToExternalRepresentation

public final java.lang.String valueToExternalRepresentation(ValueBuffer valueBuffer)

Description copied from interface: PossRepImplementation

Converts a value in internal format to the appropriate textual representation of that value for this possrep.

Specified by:

valueToExternalRepresentation in interface PossRepImplementation

Parameters:

valueBuffer - The value in internal format.

Returns:

The string representation of the given value, for this possrep.