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.

The JSTranslater is used automatically by the SmartClient RPCManager to provide Java to JavaScript translation of data provided to a RPCResponse or DSResponse. See JSTranslater.toJS() for the general rules of Java to JavaScript translation, and how to customize translation.

The JSTranslater may also be used directly, for uses such as outputting Java-derived data into a .jsp as JavaScript variables. For example, the following Java code, called from a .jsp, would produce a global JavaScript variable "myJavaData" whose value would be the translated form of "myJavaObj":

    JSTranslater.get().toJSVariable(myJavaObj, "myJavaData", out);

Use JSTranslater to deliver various kinds of data, including:

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:

Note that for handling JDBC ResultSets, the SQLTransform class can be used to transform a ResultSet into Collections that the JSTranslator accepts.

There are a few ways to customize this 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:
SQLTransform, 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)