Package hirondelle.fish.main.codes

Code Tables for the application.

See:
Description

Class Summary

CodeTableUtil

Fetches code tables from the database upon startup.

Enum Summary

CodeTable

All code tables used in this application.

Package hirondelle.fish.main.codes Description

Code Tables for the application.

The general approach in this implementation is to treat the underlying id (the primary key) of the Code as being most important, and all other items as secondary aliases for the id - the text, short form, and long form. (Some would object to this style, since it makes underlying database identifiers more visible than usually desired. In practice, however, this does not seem to be a significant issue.)

Startup

Upon startup, this application's implementation of StartupTasks will call CodeTableUtil.init(ServletContext) to initialize all items related to Code Tables. This same method must also be called if any code table changes content.

HTML Forms

The code tables fetched during startup are referenced directly in HTML forms, as application scope objects, using CodeTable.getTableName() as key. Typically, two aspects of a Code are referenced in a form : one of the code's textual aliases is made visible to the user, while its underlying id is always used as the value actually POSTed during form submission.

Here is an example which references a code table named 'dispositions' :

  <select name="Disposition">
   <c:forEach var="item" items="${dispositions}">
    <option value="${item.id}">${item}</option>
   </c:forEach>
  </select>

Avoid Double Escaping of Codes

The various translation tags used in multilingual apps always escape special characters as part of their implementation. If the above snippet appears withing a translation tag then it should be changed slightly to :

<w:txtFlow>
  ...
  <select name="Disposition">
   <c:forEach var="item" items="${dispositions}">
    <option value="${item.id}">${item.text.rawString}</option>
   </c:forEach>
  </select>
  ...
</w:txtFlow>

It is easy to forget to perform the above, especially when special characters appear infrequently.
This is a pitfall of using the Code class. This pitfall appears only with multilingual apps, 
and when your codes includes special characters.
See EscapeChars.forHTML() for the list of escaped characters. 

This will avoid double-escaping of special characters, which is always undesirable.

Model Objects

In Model Objects, the constructor takes a single Id for the code - not the full Code object. Inside the constructor, the Id is 'expanded' into a full Code object, using CodeTable.codeFor(Id, CodeTable).

Consequences

This style has these consequences :

• there is no need to repeatedly query the database for simple data which rarely changes (the content of the code table).
• Action classes usually do not need to place code tables into request scope, since they are already present in application scope.
• the regular, short and long forms of a Code are always available, if needed.
• underlying SELECT queries for Model Objects do not need to use joins for code tables, since the lookup is performed in the Model Object constructor.
• logging of the Model Object will display the user-friendly text, not the id.
• there is a drawback concerning translation and ordering of codes : if codes need to be translated according to the user's Locale, then there is an issue with alphabetical ordering. If the ordering is alphabetical, then reordering of codes should be done for each Locale, according to the user-visible text applicable to that Locale. However, there is no explicit provision for this in the implementation described here. A workaround is to simply create a code table in an Action and place it in request scope, to reflect the desired text and order. (This is always possible.)