hirondelle.web4j.model
Class Code

Object
  hirondelle.web4j.model.Code

All Implemented Interfaces:

Serializable

public final class Code
extends Object
implements Serializable

An item in a code table.

Here, a value in a code table is modeled with one required item (text), and four optional items (id, short form, long form, and order index). The id is optional, since for 'add' operations it is not yet specified. This class is offered as a convenience for implementing Code Tables. Applications are not required to use it.

Please see the example application for an example of one way of implementing code tables.

Code Tables

A code table is an informal term describing a set of related values. It resembles an enumeration. Simple examples :

• geographical divisions - countries, states or provinces
• list of accepted credit cards - Mastercard, Visa, and so on
• the account types offered by a bank - chequing, savings, and so on

Other important aspects of code tables :

• most applications use them.
• they often appear in the user interface as drop-down SELECT controls.
• they usually don't change very often.
• they may have a specific sort order, unrelated to alphabetical ordering.
• it is almost always desirable that the user-visible text attached to a code be unique (in a given code table), since the user will usually have no means to distinguish the identical items.
• it is often desirable to present the same code in different ways, according to context. For example, report listings may present codes in an abbreviated style, while a tool-tips may present a codes in a more verbose style, to explain their meaning.
• they are usually closely related to various foreign keys in the database.

Underlying Data

Code tables may be implemented in various ways, including

• database tables constructed explicitly for that purpose
• database tables that have already been constructed to hold problem domain items. That is, data from an existing table may be extracted in a shortened form, to be used as a code table.
• simple in-memory data. For example, a 1..10 rating system might use simple Integer objects created upon startup.

Avoiding Double-Escaping

This class uses SafeText, which escapes special characters. When rendering a Code object in a JSP, some care must be taken to ensure that special characters are not mistakenly escaped twice.

In a single language app, it's usually safe to render a Code by simply using ${code}. This calls toString(), which returns escaped text, safe for direct rendering in a JSP.

In a multilingual app, however, the various translation tags (<w:txt>, <w:txtFlow>, <w:tooltip>) already escape special characters. So, if a translation tag encounters a Code somewhere its body, the Code must be in an unescaped form, otherwise it wil be escaped twice, which undesirable. In a multilingual app, you should usually render a Code using ${code.text.rawString}.

This asymmetry between single-language and many-language apps is somewhat displeasing, and constitutes a pitfall of using this class. If desired, you could define an alternate Code class whose toString returns a String instead of SafeText.

See Also:

Serialized Form

Constructor Summary

Code(Id aId, SafeText aText)
As in the full constructor, but without a short description, long description, or an order index.

Code(Id aId, SafeText aText, SafeText aShortText)
As in the full constructor, but without a long description or order index.

Code(Id aId, SafeText aText, SafeText aShortText, SafeText aLongText)
As in the full constructor, but without an order index.

Code(Id aId, SafeText aText, SafeText aShortText, SafeText aLongText, Integer aOrderIdx)
Full constructor.

Method Summary

boolean	equals(Object aThat)
Id	getId() Return the Id passed to the constructor.
SafeText	getLongText() Return the Long Text passed to the constructor.
Integer	getOrderIdx() Return the Order Index passed to the constructor.
SafeText	getShortText() Return the Short Text passed to the constructor.
SafeText	getText() Return the Text passed to the constructor.
int	hashCode()
String	toString() Returns getText().toString().

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Code

public Code(Id aId,
            SafeText aText,
            SafeText aShortText,
            SafeText aLongText,
            Integer aOrderIdx)
     throws ModelCtorException

Full constructor.

Parameters:

aId - underlying database identifier for the code value. Optional, 1..50 characters.

aText - default text for presentation to the end user. Required, 1..50 characters.

aShortText - short form for text presented to the end user. This item is useful for terse presentation in reports, often as an abbreviation of one or two letters. Optional, 1..10 characters.

aLongText - long form for text presented to the user. For example, this may be a description or definition of the meaning of the code. Optional, 1..200 characters.

aOrderIdx - defines the order of appearance of this item in a listing. Optional, range 1..1000. This item is used to provide explicit control over the order of appearance of items as presented to the user, and will often be related to an ORDER BY clause in an SQL statement.

Throws:

ModelCtorException

Code

public Code(Id aId,
            SafeText aText)
     throws ModelCtorException

As in the full constructor, but without a short description, long description, or an order index.

Throws:

ModelCtorException

Code

public Code(Id aId,
            SafeText aText,
            SafeText aShortText)
     throws ModelCtorException

As in the full constructor, but without a long description or order index.

Throws:

ModelCtorException

Code

public Code(Id aId,
            SafeText aText,
            SafeText aShortText,
            SafeText aLongText)
     throws ModelCtorException

As in the full constructor, but without an order index.

Throws:

ModelCtorException

Method Detail

getId

public Id getId()

Return the Id passed to the constructor.

getText

public SafeText getText()

Return the Text passed to the constructor.

getShortText

public SafeText getShortText()

Return the Short Text passed to the constructor.

getLongText

public SafeText getLongText()

Return the Long Text passed to the constructor.

getOrderIdx

public Integer getOrderIdx()

Return the Order Index passed to the constructor.

toString

public String toString()

Returns getText().toString().

This is the most user-friendly form of a code, and is useful for rendering in JSPs.

Overrides:

toString in class Object

equals

public boolean equals(Object aThat)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object