com.isomorphic.js
Class JSTranslater

java.lang.Object
  |
  +--com.isomorphic.base.Base
        |
        +--com.isomorphic.js.JSTranslater

public class JSTranslater

extends com.isomorphic.base.Base

JSTranslater provides translation of Java objects to JavaScript equivalents. The translation is robust, intuitive, high performance and extensible. Generally speaking, any non-trivial Java data that you would like to make available to the browser should go through JSTranslater.

Use JSTranslater to deliver data to the browser, such as:

• a database-derived or XML dataset
• dynamically generated XML component definitions
• metadata such as DataSource fields
• information that allows client-side authorization checks

Warning: always use "get()" to retrieve a JSTranslater. Attempting to use "new JSTranslater()" will produce unexpected results.

See Also:

get(), toJS(Object, Writer)

Method Summary

void	alwaysToString() Sets the translater to output the Java objects that aren't specifically handled by the translater as strings, using the toString method on those objects.
JSTranslater	collapseSmallContainers(boolean value) Enables or disables the option to print the contents of containers (maps or collections) on one line if they don't contain other containers.
JSTranslater	enablePrettyPrinting() Turns pretty printing on.
JSTranslater	enablePrettyPrinting(boolean value) Turns pretty printing on if value is true, otherwise turns pretty printing off.
static JSTranslater	get() Retrieve a JSTranslater instance.
void	quoteForTextArea() Sets the translater to output the Javascript object with escaping/quoting suitable for the contents of a TEXTAREA HTML tag.
void	quoteForXML() Sets the translater to output the Javascript object with escaping/quoting suitable for embedding in XML.
java.lang.String	toJS(java.lang.Object javaObj) Returns a string containing the Javascript equivalent of javaObj.
void	toJS(java.lang.Object javaObj, java.io.Writer out) Writes the Javascript equivalent of javaObj to the output stream out.
void	toJSVariable(java.lang.Object javaObj, java.lang.String variableName, java.io.Writer out) Writes JavaScript code to define a variable with the JavaScript-converted value of the passed Java object.
void	toJSVariableInScript(java.lang.Object javaObj, java.lang.String variableName, java.io.Writer out) Writes JavaScript code to define a variable with the JavaScript-converted value of the passed Java object, enclosed in HTML SCRIPT tags.

Method Detail

get

public static JSTranslater get()

Retrieve a JSTranslater instance.

Warning: always use "get()" to retrieve a JSTranslater. Attempting to use "new JSTranslater()" will produce unexpected results.

enablePrettyPrinting

public JSTranslater enablePrettyPrinting()

Turns pretty printing on. With this option on, the Javascript output is indented for better readability. You can set the default behaviour to be pretty printing by setting the jsTranslater.prettyPrint property to true in the properties file. (Default is false)

Warning: pretty printing drastically slows down translation speed, and should not be used for high-load production servers.

enablePrettyPrinting

public JSTranslater enablePrettyPrinting(boolean value)

Turns pretty printing on if value is true, otherwise turns pretty printing off. With this option on, the Javascript output is indented for better readability. You can set the default behaviour to be pretty printing by setting the jsTranslater.prettyPrint property to true in the properties file. (Default is false)

Warning: pretty printing drastically slows down translation speed, and should not be used for high-load production servers.

Parameters:

value - if true, pretty printing is turned on, otherwise it's turned off

collapseSmallContainers

public JSTranslater collapseSmallContainers(boolean value)

Enables or disables the option to print the contents of containers (maps or collections) on one line if they don't contain other containers. This option only has an effect when pretty printing is turned on. Default behaviour can be set with the jsTranslater.prettyPrint.collapseSmallContainers property. (Default is false)

Warning: container collapsing somewhat slows translation speed, and should not be used for very high load production servers.

Parameters:

value - if true, and pretty printing is on, then output container contents on one line

See Also:

enablePrettyPrinting(boolean)

quoteForTextArea

public void quoteForTextArea()

Sets the translater to output the Javascript object with escaping/quoting suitable for the contents of a TEXTAREA HTML tag. Specifically, ampersands (the '&' character) are never escaped and is escaped so that the browser doesn't interpret it as the closing TEXTAREA tag.

This can be used to deliver a data structure to the browser without actually creating JavaScript objects until a subsequent eval().

Mutually exclusive with quoteForXML().

quoteForXML

public void quoteForXML()

Sets the translater to output the Javascript object with escaping/quoting suitable for embedding in XML. Specifically, '<', '>' and '&' are written as entity references (eg '<').

This can be used to embed a JavaScript data structure inside an XML document, for subsequent evaluation in the browser (via eval()).

Mutually exclusive with quoteForTextArea().

alwaysToString

public void alwaysToString()

Sets the translater to output the Java objects that aren't specifically handled by the translater as strings, using the toString method on those objects.

See Also:

toJS(Object, Writer)

toJS

public java.lang.String toJS(java.lang.Object javaObj)
                      throws UnconvertableException

Returns a string containing the Javascript equivalent of javaObj.

Parameters:

javaObj - the object to be written out as a Javascript object

Returns:

the Javascript equivalent of javaObj, as a string

See Also:

toJS(Object, Writer)

toJS

public void toJS(java.lang.Object javaObj,
                 java.io.Writer out)
          throws UnconvertableException,
                 java.io.IOException

Writes the Javascript equivalent of javaObj to the output stream out.

Any Java object or nested structure of Java Objects can be translated to JavaScript. The general rules are:

• Basic types such as String, Integer, Float, Boolean and Date become the same-named JavaScript built-in type.
• Collections become JavaScript Arrays. This includes List and Set, and also other Array-like structures such as Iterator, Enumeration and native Java Arrays.
• Maps become JavaScript Objects, where each key-value pair becomes a JavaScript property.
• XML Elements (org.w3c.dom.Element) and XML Documents (org.w3c.dom.Document) are treated identically to XML found in <isomorphic:XML> tags in .jsps, that is, component definitions like <ListGrid .. /> become live SmartClient components, and any other Elements become JavaScript Objects, where each attribute or subelement becomes a JavaScript property.
• Any other Java object is treated as a Java Bean, and becomes a JavaScript Object where each Bean property becomes a JavaScript property.

There are a few ways to customize this translation:

• translate your objects to collections before calling toJS().
• implement a Collections interface (such as Iterator or Map) either directly on your object or as a wrapper for your object. Since you really only have to implement the read methods from the Collection interface, this is straightforward.
• provide a JSONFilter for your object(s)
• implement the com.isomorphic.js.IToJSON interface to do completely custom translation.

This example shows a simple way to customize Bean translation by implementing the IToJSON interface.

 class MyBean implements IToJSON {
    public void toJSON (Writer out, JSTranslater jsTrans) {
       try {
          Map beanProps = DataTools.getProperties(this);
          // here, remove any properties you don't want to send 
          // (or add or modify any others)
          jsTrans.toJS(beanProps, out);
       } catch (Exception ignored) {}
    }
 } 

In this example we use DataTools.getProperties() to get all of the Bean's public properties as a Map. This Map can be modified arbitrarily, then the JSTranslater is invoked to transform the Map to a JavaScript Object. The same approach can be used externally to an object if you can't add the IToJSON interface.

Alternatively, if you simply want to filter your bean down to a set of properties, you can use the JSONFilter class.

NOTE: if the default translation yields a structure that contains all the right information but isn't arranged correctly, it is often better to re-arrange the dataset on the client. This reduces server load, providing a tremendous scalability advantage.

Parameters:

javaObj - the object to be written out as a Javascript object

out - the output stream for the Javascript equivalent of javaObj

See Also:

JSONFilter, IToJSON, com.isomorphic.util.DataTools#getProperties(Map)

toJSVariableInScript

public void toJSVariableInScript(java.lang.Object javaObj,
                                 java.lang.String variableName,
                                 java.io.Writer out)
                          throws UnconvertableException,
                                 java.io.IOException

Writes JavaScript code to define a variable with the JavaScript-converted value of the passed Java object, enclosed in HTML SCRIPT tags.

Parameters:

javaObj - the object to be written out as a Javascript object

variableName - the Javascript variable name

out - the output stream for the Javascript equivalent of javaObj

See Also:

toJS(Object, Writer)

toJSVariable

public void toJSVariable(java.lang.Object javaObj,
                         java.lang.String variableName,
                         java.io.Writer out)
                  throws UnconvertableException,
                         java.io.IOException

Writes JavaScript code to define a variable with the JavaScript-converted value of the passed Java object.

Parameters:

javaObj - the object to be written out as a Javascript object

variableName - the Javascript variable name

out - the output stream for the Javascript equivalent of javaObj

See Also:

toJS(Object, Writer)