001: /*
002: ItsNat Java Web Application Framework
003: Copyright (C) 2007 Innowhere Software Services S.L., Spanish Company
004: Author: Jose Maria Arranz Santamaria
005:
006: This program is free software: you can redistribute it and/or modify
007: it under the terms of the GNU Affero General Public License as published by
008: the Free Software Foundation, either version 3 of the License, or
009: (at your option) any later version. See the GNU Affero General Public
010: License for more details. See the copy of the GNU Affero General Public License
011: included in this program. If not, see <http://www.gnu.org/licenses/>.
012: */
013:
014: package org.itsnat.core.script;
015:
016: import org.w3c.dom.Node;
017:
018: /**
019: * Utility interface to generate JavaScript code mainly to bridge server DOM nodes
020: * with client nodes.
021: *
022: * <p>When a DOM node is used a parameter this must be part of the document tree
023: * (server and client) otherwise an exception is thrown, and the generated code
024: * MUST be sent to the client normally calling
025: * {@link org.itsnat.core.ItsNatDocument#addCodeToSend(Object)}
026: * because this node may have been automatically cached at the server, the generated code contains
027: * the order and information to cache at the client too, otherwise the server and client
028: * caches are unsynchronized (if localization cache is disabled this issue does not apply).</p>
029: *
030: * @author Jose Maria Arranz Santamaria
031: */
032: public interface ScriptUtil {
033: /**
034: * Generates the appropriated code to locate the specified DOM node at the client.
035: *
036: * <p>Returned code may be considered as a JavaScript reference to the specified node.</p>
037: *
038: * <p>The following example generates JavaScript to set 'City' to the "value" property of
039: * the specified DOM node:</p>
040: *
041: * <blockquote><pre>
042: * String code = itsNatDoc.getScriptUtil().getNodeReference(aNode) + ".value = 'City';";
043: * itsNatDoc.addCodeToSend(code);
044: * </pre></blockquote>
045: *
046: * @param node the node to generate a JavaScript reference.
047: * @return the JavaScript reference to send to the client.
048: */
049: public String getNodeReference(Node node);
050:
051: /**
052: * Creates a new script expression object wrapping the specified object.
053: *
054: * @return a new script expression object.
055: */
056: public ScriptExpr createScriptExpr(Object value);
057:
058: /**
059: * Generates the appropriated code to call the specified object method at the client.
060: *
061: * @param obj the object reference, converted to JavaScript calling {@link #toScript(Object)}.
062: * @param methodName method name.
063: * @param params the parameter list. Are converted to JavaScript calling {@link ScriptUtil#toScript(Object)}.
064: * @param endSentence if true adds a ; at the end.
065: * @return the JavaScript code.
066: */
067: public String getCallMethodCode(Object obj, String methodName,
068: Object[] params, boolean endSentence);
069:
070: /**
071: * Generates the appropriated code to call the specified object method at the client.
072: *
073: * @param obj the object reference, converted to JavaScript calling {@link #toScript(Object)}.
074: * @param methodName method name.
075: * @param params the parameter list. Are converted to JavaScript calling {@link ScriptUtil#toScript(Object)}.
076: * @return the JavaScript code.
077: */
078: public String getCallMethodCode(Object obj, String methodName,
079: Object[] params);
080:
081: /**
082: * Generates the JavaScript code to set a value to the specified property.
083: *
084: * @param obj the object reference, converted to JavaScript calling {@link #toScript(Object)}.
085: * @param propName property name.
086: * @param value the value to set. Is converted to JavaScript calling {@link ScriptUtil#toScript(Object)}.
087: * @param endSentence if true adds a ; at the end.
088: * @return the JavaScript code.
089: */
090: public String getSetPropertyCode(Object obj, String propName,
091: Object value, boolean endSentence);
092:
093: /**
094: * Generates the JavaScript code to set a value to the specified property.
095: *
096: * @param obj the object reference, converted to JavaScript calling {@link #toScript(Object)}.
097: * @param propName property name.
098: * @param value the value to set. Is converted to JavaScript calling {@link ScriptUtil#toScript(Object)}.
099: * @return the JavaScript code.
100: */
101: public String getSetPropertyCode(Object obj, String propName,
102: Object value);
103:
104: /**
105: * Generates the JavaScript code to get the value of the specified property.
106: *
107: * @param obj the object reference, converted to JavaScript calling {@link #toScript(Object)}.
108: * @param propName property name.
109: * @param endSentence if true adds a ; at the end.
110: * @return the JavaScript code.
111: */
112: public String getGetPropertyCode(Object obj, String propName,
113: boolean endSentence);
114:
115: /**
116: * Generates the JavaScript code to get the value of the specified property.
117: *
118: * @param obj the object reference, converted to JavaScript calling {@link #toScript(Object)}.
119: * @param propName property name.
120: * @return the JavaScript code.
121: */
122: public String getGetPropertyCode(Object obj, String propName);
123:
124: /**
125: * Converts the specified Java <code>String</code> to a JavaScript string literal, this
126: * string can be send to the client.
127: *
128: * <p>Any special character like end of lines, tabs, " , ' , \ etc are escaped to sent
129: * to the client as a JavaScript string literal.</p>
130: *
131: * @param text the <code>String</code> to convert.
132: * @return the resulting JavaScript string literal.
133: */
134: public String getTransportableStringLiteral(String text);
135:
136: /**
137: * Converts the specified Java <code>String</code> to a JavaScript string literal, this
138: * string can be send to the client.
139: *
140: * <p>Any special character like end of lines, tabs, " , ' , \ etc are escaped to sent
141: * to the client as a JavaScript string literal.</p>
142: *
143: * @param c the Java <code>char</code> to convert.
144: * @return the resulting JavaScript string literal.
145: */
146: public String getTransportableCharLiteral(char c);
147:
148: /**
149: * Is a Java implementation of the JavaScript <code>encodeURIComponent</code> function.
150: * The string encoded with this method can be unencoded using the JavaScript <code>decodeURIComponent</code> function.
151: *
152: * <p>This method is an alternative (slower and bigger) to {@link #getTransportableStringLiteral(String)}
153: * to transport texts to the client.</p>
154: *
155: * <p>The encoded Java String is not a string literal. The following
156: * example encloses the <code>String</code> as a literal: </p>
157: *
158: * <p><code> String code = "\"" + encodeURIComponent(someText) + "\""; </code></p>
159: *
160: * @param text the Java <code>String</code> to encode.
161: * @return the encoded text.
162: */
163: public String encodeURIComponent(String text);
164:
165: /**
166: * Is a Java implementation of the JavaScript <code>encodeURIComponent</code> function
167: * applied to a Java <code>char</code>.
168: *
169: * <p>This method is an alternative (slower and bigger) to {@link #getTransportableCharLiteral(char)}
170: * to transport characters to the client.</p>
171: *
172: * <p>The encoded Java char is not a char literal. The following
173: * example encloses the <code>char</code> as a literal: </p>
174: *
175: * <p><code> String code = "'" + encodeURIComponent(someChar) + "'"; </code></p>
176: *
177: * @param c the Java <code>char</code> to encode.
178: * @return the encoded char.
179: */
180: public String encodeURIComponent(char c);
181:
182: /**
183: * Converts the specified object value to JavaScript code.
184: *
185: * <p>Conversion rules if value is a:</p>
186: * <ul>
187: * <li>DOM Node: conversion is done calling {@link #getNodeReference(org.w3c.dom.Node)}.</li>
188: * <li>Boolean: calling value.toString() (returns the literals <code>true</code> and <code>false</code>.</li>
189: * <li>Character: calling {@link #getTransportableCharLiteral(char)}.</li>
190: * <li>Number: calling value.toString().</li>
191: * <li>ScriptExpr: calling {@link ScriptExpr#getCode()}.</li>
192: * <li>String: calling {@link #getTransportableStringLiteral(String)}.</li>
193: * <li>Others: calling value.toString().</li>
194: * </ul>
195: *
196: * @param value the object to convert to JavaScript.
197: * @return the JavaScript code.
198: */
199: public String toScript(Object value);
200: }
|