|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325 |
- <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
- <html>
- <head>
- <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
- <title>Enumerated Data Values</title>
- <style type= "text/css" >
- body {
- font-family: Verdana, Helvetica, sans-serif;
- }
-
- .note { border: solid 1px #7099C5; background-color: #f0f0ff; }
- .note .label { background-color: #7099C5; color: #ffffff; }
- .content {
- padding: 5px 5px 5px 10px;
- font : Verdana, Helvetica, sans-serif; font-size : 90%;
- }
- </style>
- </head>
- <body marginheight="0" marginwidth="0" topmargin="0" leftmargin="0" text="#000000" bgcolor="#FFFFFF">
- <div class="content">
- <h1>Enumerated Data Values</h1>
- <ul class="minitoc">
- <li>
- <a href="#N1000C">Enumerated Data Values</a>
- <ul class="minitoc">
- <li>
- <a href="#N10020">Array representation</a>
- </li>
- <li>
- <a href="#N1005C">HashMap representation</a>
- </li>
- <li>
- <a href="#N1009D">
- Factoring Out Common Enumeration Values
- </a>
- </li>
- <li>
- <a href="#N100DD">Mapped Numeric Values</a>
- </li>
- </ul>
- </li>
- </ul>
-
- <a name="N1000C"></a>
- <h3>Enumerated Data Values</h3>
- <p>
- 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 <em>vice versa</em>. Depending on the number of
- tokens in an enumeration set, the mapping from token to
- integer is maintained in an array or a <span
- class="codefrag">HashMap</span>. The switch-over point from
- array to <span class="codefrag">HashMap</span> was determined
- by some highly implementation-dependent testing to be in the
- region of four to five elements.
- </p>
- <p>
- 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.
- </p>
- <a name="N10020"></a>
- <h4>Array representation</h4>
- <p>
-
- <a href= "javascript:parent.displayCode(
- 'Direction.html#DirectionClass' )" ><span
- class="codefrag">org.apache.fop.fo.properties.Direction</span></a>
- is an example of a class which supports an enumerated value
- with a small set of tokens. The <a href=
- "javascript:parent.displayCode( 'Direction.html#dataTypes' )"
- ><span class="codefrag">dataTypes</span></a> field contains
- the <a href= "javascript:parent.displayCode(
- 'Property.html#NOTYPE' )" ><span class="codefrag">ENUM</span>
- data type constant, defined in <span
- class="codefrag">Property</span></a>. The enumeration integer
- constants are defined as <span class="codefrag">public static
- final int</span> values, <a href=
- "javascript:parent.displayCode( 'Direction.html#LTR') "><span
- class="codefrag' )" >LTR</span> and <span
- class="codefrag">RTL</span></a>. Associating enumeration
- tokens with these integer constants occurs in the array <a
- href= "javascript:parent.displayCode( 'Direction.html#rwEnums'
- )" ><span class="codefrag">String[] rwEnums</span></a>, 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 <span class="codefrag">rwEnums</span> and the
- enumeration constants be maintained.
- </p>
- <p>
- The publicly accessible mapping from enumeration token to
- enumeration constant is achieved through the method <a href=
- "javascript:parent.displayCode( 'Direction.html#getEnumIndex'
- )" ><span class="codefrag">int
- getEnumIndex(String)</span></a>. The corresponding mapping
- from enumeration constant to enumeration token is achieved
- through the method <a href= "javascript:parent.displayCode(
- 'Direction.html#getEnumText' )" ><span class="codefrag">String
- getEnumText(int)</span></a>.
- </p>
- <a name="N1005C"></a>
- <h4>HashMap representation</h4>
- <p>
-
- <a href= "javascript:parent.displayCode(
- 'RenderingIntent.html#RenderingIntentClass' )" ><span
- class="codefrag"
- >org.apache.fop.fo.properties.RenderingIntent</span ></a> is
- an example of a class which supports an enumerated value with
- a larger set of tokens. The <a href=
- "javascript:parent.displayCode(
- 'RenderingIntent.html#dataTypes' )" ><span
- class="codefrag">dataTypes</span></a> field contains the <a
- href= "javascript:parent.displayCode( 'Property.html#NOTYPE'
- )" ><span class="codefrag">ENUM</span> data type constant,
- defined in <span class="codefrag">Property</span></a>.
- Enumeration integer constants are defined as <a href=
- "javascript:parent.displayCode(
- 'RenderingIntent.html#PERCEPTUAL' )" ><span
- class="codefrag">public static final int</span></a> values.
- Zero is never used to represent a valid enumeration constant.
- The enumeration tokens are stored in the array <a href=
- "javascript:parent.displayCode( 'RenderingIntent.html#rwEnums'
- )" ><span class="codefrag">String[] rwEnums</span></a>, which
- is initialized with the token strings. Association of
- enumeration tokens with the integer constants occurs in the
- <span class="codefrag">HashMap</span> <a href=
- "javascript:parent.displayCode(
- 'RenderingIntent.html#rwEnumHash"><span class="codefrag' )" >
- rwEnumHash</span></a>, which is initialized from the token
- array in a <span class="codefrag">static {}</span>
- initializer. It is, of course, critical that synchronization
- between <span class="codefrag">rwEnums</span> and the
- enumeration constants be maintained.
- </p>
- <p>
- The publicly accessible mapping from enumeration token to
- enumeration constant is achieved through the method <a href=
- "javascript:parent.displayCode(
- 'RenderingIntent.html#getEnumIndex' )" ><span
- class="codefrag">int getEnumIndex(String)</span></a>. The
- corresponding mapping from enumeration constant to enumeration
- token is achieved through the method <a href=
- "javascript:parent.displayCode(
- 'RenderingIntent.html#getEnumText' )" ><span
- class="codefrag">String getEnumText(int)</span></a>.
- </p>
- <a name="N1009D"></a>
- <h4 id="common-enum-values">
- Factoring Out Common Enumeration Values
- </h4>
- <p>
- 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 <a href=
- "javascript:parent.displayCode(
- 'BorderCommonStyle.html#BorderCommonStyleClass' )" ><span
- class="codefrag">BorderCommonStyle</span></a>. Like a
- property with a normal HashMap representation of an enumerated
- value, BorderCommonStyle defines <a href=
- "javascript:parent.displayCode(
- 'BorderCommonStyle.html#HIDDEN' )" ><span
- class="codefrag">public static final int</span></a>
- enumeration integer constants. Similarly, the enumeration
- tokens are stored in the array <a href=
- "javascript:parent.displayCode(
- 'BorderCommonStyle.html#rwEnums' )" ><span
- class="codefrag">String[] rwEnums</span></a>, and the
- association of enumeration tokens with the integer constants
- occurs in the <span class="codefrag">HashMap</span> <a href=
- "javascript:parent.displayCode(
- 'BorderCommonStyle.html#rwEnumHash' )" ><span
- class="codefrag"> rwEnumHash</span></a>, initialized in a
- <span class="codefrag">static {}</span> initializer. The
- mapping methods <a href= "javascript:parent.displayCode(
- 'BorderCommonStyle.html#getEnumIndex' )" ><span
- class="codefrag">int getEnumIndex(String)</span></a> and <a
- href= "javascript:parent.displayCode(
- 'BorderCommonStyle.html#getEnumText' )" ><span
- class="codefrag">String getEnumText(int)</span></a> are also
- present.
- </p>
- <p>
- Notice, however, that the class has none of the static data
- constants described in the discussion of <a
- href="simple-properties.html">simple properties</a>. These
- values are defined in the individual sub-classes of this
- class, e.g. <a href= "javascript:parent.displayCode(
- 'BorderLeftStyle.html#BorderLeftStyleClass' )" ><span
- class="codefrag">BorderLeftStyle</span></a>. None of the
- above fields or methods occur, and <span
- class="codefrag">BorderLeftStyle</span> is left looking like
- an example of a simple property. The enumeration mapping
- methods are, however, available through the super-class <span
- class="codefrag">BorderCommonStyle</span>.
- </p>
- <a name="N100DD"></a>
- <h4>Mapped Numeric Values</h4>
- <p>
- 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 <span class="codefrag">Numeric</span>
- result. Their resolution involves mapping the token to the
- indicated <span class="codefrag">Numeric</span> value.
- </p>
- <p>
- An example is the <a href= "javascript:parent.displayCode(
- 'BorderCommonWidth.html#BorderCommonWidthClass' )" ><span
- class="codefrag">BorderCommonWidth</span></a> property. This,
- like the example of <a href="#common-enum-values"><span
- class="codefrag">BorderCommonStyle</span></a> above, also
- represents common enumerated values which have been factored
- out to form a super-class for particular properties. <span
- class="codefrag">BorderCommonWidth</span>, therefore, also
- defines <a href= "javascript:parent.displayCode(
- 'BorderCommonWidth.html#THIN' )" ><span
- class="codefrag">enumeration constant values</span></a> and an
- array of tokens. In this case, there is no <span
- class="codefrag">HashMap</span>, because of the limited number
- of tokens, but the mapping methods <a href=
- "javascript:parent.displayCode(
- 'BorderCommonWidth.html#getEnumIndex' )" ><span
- class="codefrag">int getEnumIndex(String)</span></a> and <a
- href= "javascript:parent.displayCode(
- 'BorderCommonWidth.html#getEnumText' )" ><span
- class="codefrag">String getEnumText(int)</span></a> are
- present.
- </p>
- <p>
- The added element in this property is the array <a href=
- "javascript:parent.displayCode(
- 'BorderCommonWidth.html#mappedPoints' )" ><span
- class="codefrag">double[] mappedPoints</span></a>. The
- entries in this array must by maintained in syncronization
- with the <a href= "javascript:parent.displayCode(
- 'BorderCommonWidth.html#rwEnums' )" ><span
- class="codefrag">String[] rwEnums</span></a> array of tokens
- and the set of <a href= "javascript:parent.displayCode(
- 'BorderCommonWidth.html#THIN' )" >enumeration constants</a>.
- The mapping from token to Numeric value is achieved by the <a
- href= "javascript:parent.displayCode(
- 'BorderCommonWidth.html#getMappedLength' )" ><span
- class="codefrag">Numeric getMappedLength(FONode, int,
- int)</span></a> method.
- </p>
- <p>
-
- <a href= "javascript:parent.displayCode(
- 'BorderLeftWidth.html#BorderLeftWidthClass' )" ><span
- class="codefrag">BorderLeftWidth</span></a> extends <a href=
- "javascript:parent.displayCode( 'BorderCommonWidth.html' )"
- ><span class="codefrag">BorderCommonWidth</span></a>. It
- includes the basic static data, like <a
- href="simple-properties.html">simple properties</a>, and, in
- this case, the <a href= "javascript:parent.displayCode(
- 'BorderLeftWidth.html#getInitialValue' )" ><span
- class="codefrag">PropertyValue getInitialValue(int)</span></a>
- method to derive the initial value.
- </p>
- <a name="N10139"></a>
- <h4>Deriving Mapped Numeric Values</h4>
- <p>
- As usual with property values, the usual method of deriving a
- mapped numeric value is by calling the <a href=
- "javascript:parent.displayCode(
- '../PropertyConsts.html#getMappedNumeric' )" ><span
- class="codefrag">Numeric getMappedNumeric(FONode, int,
- int)</span></a> method in <a href=
- "javascript:parent.displayCode(
- '../PropertyConsts.html#pconsts' )" ><span
- class="codefrag">pconsts</span></a>. All properties which
- support a mapped numeric value must have a <span
- class="codefrag">Numeric getMappedNumeric(FONode, int)</span>
- method, which will be called through its singleton instance,
- stored in the <a href= "javascript:parent.displayCode(
- 'PropertyConsts.html#properties' )" ><span class= "codefrag"
- >properties</span ></a> array, by the <span
- class="codefrag">PropertyConsts</span> method.
- </p>
-
- <p>
- <strong>Previous:</strong> <a href= "getInitialValue.html"
- >getInitialValue()</a>
- </p>
- <!--
- <p>
- <strong>Next:</strong> <a href= "getInitialValue.html"
- >getInitialValue()</a>
- </p>
- -->
-
- </div>
- <table summary="footer" cellspacing="0" cellpadding="0" width="100%" height="20" border="0">
- <tr>
- <td colspan="2" height="1" bgcolor="#4C6C8F"><img height="1"
- width="1" alt="" src="../../../skin/images/spacer.gif"><a
- href="../../../skin/images/label.gif"></a><a
- href="../../../skin/images/page.gif"></a><a
- href="../../../skin/images/chapter.gif"></a><a
- href="../../../skin/images/chapter_open.gif"></a><a
- href="../../../skin/images/current.gif"></a><a
- href="../../..//favicon.ico"></a></td>
- </tr>
- <tr>
- <td colspan="2" bgcolor="#CFDCED" class="copyright"
- align="center"><font size="2" face="Arial, Helvetica,
- Sans-Serif">Copyright © 1999-2002 The Apache
- Software Foundation. All rights reserved.<script
- type="text/javascript" language="JavaScript"><!--
- document.write(" - "+"Last Published: " +
- document.lastModified); // --></script></font></td>
- </tr>
- <tr>
- <td align="left" bgcolor="#CFDCED" class="logos"></td><td
- align="right" bgcolor="#CFDCED" class="logos"></td>
- </tr>
- </table>
- </body>
- </html>
|