Jessop 1.0.20 API
The jessop project provides multi-language templates in the style of Java Server Pages.
Syntax
The jessop syntax should be familiar to anyone who has written JSPs. A jessop source script may contain
- unprocessed text
- a declaration in the form
<%@ jessop language="javascript" engine="rhino" %> - expressions to generate output in the form
<%= name %> - scriptlets to execute arbitrary code in the form
<% if (name==null) { %>No name<% } %>
Other JSP features such as JSP-EL, beans, tag libraries, and access to HTTP session, request or response objects are not implemented by this ScriptEngine (although if you really wanted to, you could implement a Servlet to serve up jessop files with request/response variables defined).
Jessop operates by translating the jessop source script into a target language script, which is composed entirely of statements in the target language.
Care is taken to preserve line numbers between the source script and the target language script so that runtime errors that occur in the target language script can be easily traced back to the corresponding line in the source script. Some target languages, such as python, have overly strict whitespace conventions, and so line numbers may not be preserved in all cases.
Declarations
Declarations consist of any text within a <%@ ... %> block.
Declarations are used to supply information to the jessop engine, such as the target language being used, the target engine, the filename to use in exception messages and other internal configuration options.
A script may have any number of declarations, but since jessop does not currently support mixing languages within the same source script, you should only have at most one declaration defined at the top of the file.
Target languages may also define their own declarations (although this is not the case for any of the pre-defined languages)
The jessop declaration is in the form
<%@ jessop name1="value1" name2="value2" ... %>.
The developer may supply their own default declaration values to the ScriptEngine using ENGINE_SCOPE bindings, otherwise jessop-defined defaults will apply.
Current jessop declaration attributes are:
| Attribute name | JessopScriptEngine constant | jessop-defined default | Description |
|---|---|---|---|
| filename | FILENAME | null | The filename of the jessop source script. This filename will be included in ScriptExceptions that occur when the target language script is evaluated. |
| language | JESSOP_LANGUAGE
| javascript
| The target language used within the jessop script for expressions and scriptlets
This must be the same string returned by the
|
| engine | JESSOP_ENGINE
| rhino
| The name of the ScriptEngine used to evaluate the target language script.
This should be the same string that the ScriptEngine uses to identify itself; see
|
| exceptionConverter | JESSOP_EXCEPTION_CONVERTER | null | The class name of a JessopExceptionConverter that will
be used to convert exceptions raised by the target language's ScriptEngine to
ScriptExceptions. (This should not normally be required, but exists as a workaround for
the beanshell and luaj engines, which do not do this properly).
|
| compileTarget | JESSOP_COMPILE_TARGET
| true
| If true, and if the target language ScriptEngine supports it, will attempt to compile the target script before evaluation. This may result in increased execution speed. |
| suppressEol | JESSOP_SUPPRESS_EOL
| false
| This attribute will suppress any trailing whitespace and the newline character that
appears after a <% ... %> scriptlet from appearing in the
evaluated target language script output. Whitespace/newline suppression will
only occur if the scriptlet appears at the end of a line in the jessop source.
The suppressEol attribute is used for jessop scripts used for code generation. |
Unprocessed text
Unprocessed text consists of any text that appears in the jessop source that is not contained in a declaration, expression, or scriptlet.
When unprocessed text is encountered in the jessop source script, the text is converted into code that prints that text to the output PrintWriter. The text is escaped if necessary in order to represent it in the target language's native string type.
e.g. if the jessop target language is 'javascript', then the unprocessed text
Lovely day isn't itwill be converted into
out.print('Lovely day isn\'t it\n');
Expressions
Expressions consist of any text within a <%= ... %> block.
When expressions are encountered in the jessop source script, they are converted into code in the target language script that will evaluate the block output, and the print that value to the output PrintWriter.
e.g. if the jessop target language is 'javascript', then the expression block
<%= name %>will be converted into
out.print(name);
Scriptlets
Scriptlets consist of any text within a <% ... %> block.
The term 'scriptlets' is the same term used in the Java Server Pages (JSP) specification.
Scriptlet blocks should contain code written in the target language. When scriptlets are encountered in the jessop source script, this code is copied into the target language script verbatim.
e.g. if the jessop target language is 'javascript', then the expression block
<% if (name==null) { %> No name <% } %>
will be converted into
if (name==null) { out.print(' No name '); }
There are no constraints placed on what actions a scriptlet may perform; a scriptlet may define new variables or functions, call functions, or even call Java code if the target scripting language supports it, including undesired actions such as terminated the JVM via a System.exit() call.
If you are running scripts defined by other users and do wish to restrict what actions a scriptlet may perform, run the ScriptEngine within a SecurityManager.
More information
There's probably a much more opinionated post on this somewhere on the randomnoun blog.