org.sandev.ui.util
Interface SandTransformer

public interface SandTransformer

An abstraction of declarative display customization used in indirect display interfaces. Displays with an intermediate language (like XML) typically apply templates by writing to a buffer and then transforming the buffer using a template language. We refer to these as indirect displays. Direct displays (such as a typical GUI app) tend to apply templates as an integral part of the rendering process and therefore tend not to make use of a SandTransformer.

The format of the template text depends on the technology of the implementing class. The seminal indirect display usage is XSLT. However it is also possible to define a template consisting of attribute/value pairs, where each attribute refers to a display aspect of the form or page (eg form.backgroundColor or text.firstParagraph). This approach has the advantage of being applicable to both indirect and direct rendering applications.

We recommend using a simple identifier for a template name (for example "MainTemplate" rather than "/trans/MainTemplate.xsl"), since that gives maximum flexibility to the TemplateReader to find the appropriate file. This leaves open the possibility of multiple alternate translations (such as for localization), and organizational changes (such as moving template files to different places or changing extensions). Plus its less typing.

Template transformation can also be used in messaging conversions and other applications beyond user interface. Since all SAND platforms support apps/ui, the same SandTransformer implementations can still be used for these purposes regardless of user interface technology being used for the application.

Method Summary

java.lang.String	transform(java.lang.String template, java.lang.String text, java.util.Locale locale) Transform the text according to the template, returning the transformed result text.
void	transform(java.lang.String template, java.lang.String text, java.io.OutputStream out, java.util.Locale locale) Transform the text according to the template, streaming output to the given stream.

Method Detail

transform

public java.lang.String transform(java.lang.String template,
                                  java.lang.String text,
                                  java.util.Locale locale)
                           throws SandTransformerException

Transform the text according to the template, returning the transformed result text. The locale may be used to select an appropriate template using the specified name as a base.

Throws:

SandTransformerException

transform

public void transform(java.lang.String template,
                      java.lang.String text,
                      java.io.OutputStream out,
                      java.util.Locale locale)
               throws SandTransformerException

Transform the text according to the template, streaming output to the given stream. Implementing classes may require specific types of streams, but must

1. clearly document what classes are supported.
2. preemptively verify their parameters and throw something more descriptive than a ClassCastException if given input they cannot work with.

Throws:

SandTransformerException