Enumerated Data Values
Enumerated Data Values
Property classes which allow enumerated data types must encode integer constants representing the enumeration tokens, and must provide a way of translating between the tokens and the integers, and vice versa. Depending on the number of tokens in an enumeration set, the mapping from token to integer is maintained in an array or a HashMap. The switch-over point from array to HashMap was determined by some highly implementation-dependent testing to be in the region of four to five elements.
Many properties share common sets of enumeration tokens, e.g. those which allow color values, and those applying to borders and padding. A special case of enumerated value is the mapped numeric enumeration, in which a token maps to a Numeric value. These situations are discussed below.
Array representation
org.apache.fop.fo.properties.Direction is an example of a class which supports an enumerated value with a small set of tokens. The dataTypes field contains the ENUM data type constant, defined in Property. The enumeration integer constants are defined as public static final int values, LTR and RTL. Associating enumeration tokens with these integer constants occurs in the array String[] rwEnums, which is initialized with the token strings. By convention, zero is never used to represent a valid enumeration constant, anywhere in this code. It is, of course, critical that synchronization between rwEnums and the enumeration constants be maintained.
The publicly accessible mapping from enumeration token to enumeration constant is achieved through the method int getEnumIndex(String). The corresponding mapping from enumeration constant to enumeration token is achieved through the method String getEnumText(int).
HashMap representation
org.apache.fop.fo.properties.RenderingIntent is an example of a class which supports an enumerated value with a larger set of tokens. The dataTypes field contains the ENUM data type constant, defined in Property. Enumeration integer constants are defined as public static final int values. Zero is never used to represent a valid enumeration constant. The enumeration tokens are stored in the array String[] rwEnums, which is initialized with the token strings. Association of enumeration tokens with the integer constants occurs in the HashMap rwEnumHash, which is initialized from the token array in a static {} initializer. It is, of course, critical that synchronization between rwEnums and the enumeration constants be maintained.
The publicly accessible mapping from enumeration token to enumeration constant is achieved through the method int getEnumIndex(String). The corresponding mapping from enumeration constant to enumeration token is achieved through the method String getEnumText(int).
Factoring Out Common Enumeration Values
When a number of properties support a common enumerated value, that value and its associated access methods may be factored out to a new class, which each of the properties then extends. An example of such a common super-class is BorderCommonStyle. Like a property with a normal HashMap representation of an enumerated value, BorderCommonStyle defines public static final int enumeration integer constants. Similarly, the enumeration tokens are stored in the array String[] rwEnums, and the association of enumeration tokens with the integer constants occurs in the HashMap rwEnumHash, initialized in a static {} initializer. The mapping methods int getEnumIndex(String) and String getEnumText(int) are also present.
Notice, however, that the class has none of the static data constants described in the discussion of simple properties. These values are defined in the individual sub-classes of this class, e.g. BorderLeftStyle. None of the above fields or methods occur, and BorderLeftStyle is left looking like an example of a simple property. The enumeration mapping methods are, however, available through the super-class BorderCommonStyle.
Mapped Numeric Values
In "normal" enumerated values, the token is, effectively, passed directly into the layout operation of the flow object to which the property is applied. Some enumerated values, however, generate a Numeric result. Their resolution involves mapping the token to the indicated Numeric value.
An example is the BorderCommonWidth property. This, like the example of BorderCommonStyle above, also represents common enumerated values which have been factored out to form a super-class for particular properties. BorderCommonWidth, therefore, also defines enumeration constant values and an array of tokens. In this case, there is no HashMap, because of the limited number of tokens, but the mapping methods int getEnumIndex(String) and String getEnumText(int) are present.
The added element in this property is the array double[] mappedPoints. The entries in this array must by maintained in syncronization with the String[] rwEnums array of tokens and the set of enumeration constants. The mapping from token to Numeric value is achieved by the Numeric getMappedLength(FONode, int, int) method.
BorderLeftWidth extends BorderCommonWidth. It includes the basic static data, like simple properties, and, in this case, the PropertyValue getInitialValue(int) method to derive the initial value.
Deriving Mapped Numeric Values
As usual with property values, the usual method of deriving a mapped numeric value is by calling the Numeric getMappedNumeric(FONode, int, int) method in pconsts. All properties which support a mapped numeric value must have a Numeric getMappedNumeric(FONode, int) method, which will be called through its singleton instance, stored in the properties array, by the PropertyConsts method.
Previous: getInitialValue()
