be.SIRAPRISE.typeimplementations
Interface PossRepImplementation

All Known Subinterfaces:

PossRepImplementation14

All Known Implementing Classes:

DbmsAngleImplementation, DbmsAverageImplementation, DbmsBarImplementation, DbmsBitsImplementation, DbmsBooleanImplementation, DbmsCharImplementation, DbmsDateImplementation, DbmsDecimalImplementation, DbmsFilenameImplementation, DbmsFloatImplementation, DbmsFooImplementation, DbmsIntImplementation, DbmsLongImplementation, DbmsNameImplementation, DbmsRelationImplementation, DbmsStringImplementation, DbmsTimeofdayImplementation, DbmsTupleImplementation, IntervalTypeImplementation

public interface PossRepImplementation

Defines the methods that the implementation class for a SIRA_PRISE PossRep must provide

Author:

Erwin Smout

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
java.lang.String	getPossrepName() Gets the possrep name
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.

Method Detail

getComponentValue

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

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

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

getComponentNameMap

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

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.

Returns:

a map of component/type names.

getPossrepName

java.lang.String getPossrepName()

Gets the possrep name

Returns:

The possrep name

valueFromExternalRepresentation

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

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.

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

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

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.

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.

valueToExternalRepresentation

java.lang.String valueToExternalRepresentation(ValueBuffer valueBuffer)

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

Parameters:

valueBuffer - The value in internal format.

Returns:

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

valueToEscapedExternalRepresentation

java.lang.String valueToEscapedExternalRepresentation(ValueBuffer valueBuffer)

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.

Parameters:

valueBuffer - The value in internal format.

Returns:

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

valueFromComponentValues

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.

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.