Japid-Play, a template engine at raw Java speed

                Bing Ran<bing.ran@iclass.com>
                

Latest version: 0.9.6.2

• Links:

-- Japid for Play 2: https://github.com/branaway/japid42 -- The Japid/Play User Manual:
http://www.playframework.org/modules/japid-0.9.10/home -- Use Japid as a Generic Template Engine: https://github.com/branaway/Japid/wiki/Japid-Generic-Template-Engine-Guide -- Porting to Japid:
https://github.com/branaway/Japid/wiki/Porting-ZenContact-to-Japid -- The Japid Plugin for Eclipse: https://github.com/branaway/playclipse

• Note 1:

Whenever you upgrade the Japid module,

1. do a "play japid:regen" to regenerate all the derived Java files.
2. Or if you're using the Japid Plugin for Eclipse, re-enable the "Play nature", or do a "Project -> clean"

• Note 2:

I have made a patched version of the original Play 1.2.x stream which is hosted here: https://github.com/branaway/play. It works very well with Japid to give developers a very short turn-around time in DEV mode. Please check it out. That version's jdk8 branch is compatible with jdk 8.

• Note 3: Use this dependencies.yml to reference the latest distribution, adjusting the version number accordingly:

<code> require: - cn.bran -> japid {latest version} - cn.bran -> japidplay {latest version} - com.google.code.javaparser -> javaparser 1.0.8

My custom repositories

repositories: - bran: type: http artifact: "https://raw.githubusercontent.com/branaway/Japid/master/dist-lib/[module]-[revision].[ext]" contains: - cn.bran -> * </code>

*Note 4: "play bm" to build the module. The module version is in the build.xml. "git push" to publish the module in the github.

• Version History:

2016/6/14: version: 0.9.6.2: 1. adjust the JapidSampleDecoupled to use the latest Japid and corrected a few path errors in the sample. 2. added a configuration entry in application.conf that enables/disables simple expression notation, $xxx, syntax. Turn it off so one can use $xxx as in some client-side expr: japid.simple.expr.enabled=true|false. The default is true so that old applications won't break.
2016/3/11: version: 0.9.6.1: 1. bug: absolute reverse lookup for websocket (WS) protocol failed. 2016/3/11: V0.9.6: 1. bug: get methods reverse lookup not working for AutoPath generated routes. 2. change: some JDK8 usage in AutoPath. Compiled with JDK8 2014/7/17: V0.9.5.2: 1. enhancement: removed all jdk8 construct to make the source code compile-able in previous JDKs.
2013/12/21: V0.9.5.1: 1. enhancement: to define class immediately after compiling them, in prod mode
2013/12/21: V0.9.5: 1. new feature: updated JDT compiler to support jdk 8.
2013/12/21: V0.9.37.3: 1. enhancement: to detect scripts with a future time stamp and reset them to current time so that newly generated java files would be always newer.
2013/11/12: V0.9.37: 1. performance enhancement: tag initializing took from 0.050 ms down to 0.015 ms. Stand-alone Japid benefits from the enhancement too. Less StringBuffer junk shall be created too. 2013/11/12: V0.9.36: 1. bug fix: the substitute expression in an Elvis expression in an escaped expression was not escaped. 2. bug fix: japid version display message was displayed literally instead of showing the version number. 3. enhancement: some initial work relating to benchmarking code fragments in a script using `stopwatch 2013/10/23: V0.9.35: 1. enhancement: japid compiler detects java classes generated by older versions of Japid and automatically invalidate them. No manual re-generation is required. 2. API change and enhancement: the "open for" loop and the "each" tag now uses a simpler implementation that gives better performance and also allows for the use of regular Java "continue" and "break" to redirect code flow in the loops. One caveat is the iteration target must be "final" if it's a locally defined variable. The arguments to a Japid script are already implicitly final.
3. new feature regarding rendering Japid compilation errors: a new API was introduced to the JapidPlayRenderer class that can render runtime exceptions in compiling Japid artifacts and give accurate errors in Japid scripts. It works for the "tight integration mode", i.e., all the Japid scripts are located in the "app/japidviews" folder. The API usage is to replace a line in the "app/views/errors/500.html" as in the following: #{if play.mode.name() == 'DEV'} ${cn.bran.play.JapidPlayRenderer.renderPlayException(exception).raw()} #{/if}

2013/09/02: V0.9.31: 1. bug fix: japid classes were not loaded in prod mode when using JapidRenderer directly. This woule lead to class not found error in standalone prod mode.

2013/09/02: V0.9.30: 1. bug fix: did not check the null state of app class of ApplicationClass in buildRoutes(); 2013/08/30: V0.9.29: 1. bug fix: &{xxx} message syntax did not allow more than one argument to the arg list. 2013/08/08: V0.9.28: 1. enhancement: the original Japid script do not need to present in PROD mode if all the Java artifacts have been generated in advance. Note: in DEV mode, any Java artifacts without corresponding Japid scripts will be removed.

2013/08/08: V0.9.27: 1. enhancement: action methods annotated with POST do not take arguments from HTTP path. 2. enhancement: the JapidController now takes over the japid renderer class searching from "japidroot", effectively this controller is compatible with both tight-integration and loose-integration mode. 3. enhancement: in DEV mode, one can re-generate all Japid classes by running http://xxx/_japidregen. As long as the URL ends with _japidregen, it'll run the regen command to recompile all Japid scripts. 2013/08/06: V0.9.26: 1. enhancement: added file name to the line marker of Java artifacts 2. enhancement: detected classloader state change and cached generated routes.
2013/08/02: V0.9.25: 1. new feature: added nice error reporting for isolated Japid mode.
2013/08/02: V0.9.24: 1. bug fix: also rebuild auto routes at onRouteLoaded event. a workaround to the servletwrapper defect, or deployment with a context in Tomcat won't work. 2013/08/02: V0.9.23: 1. bug fix: dealt with root path starting with "." 2. enhancement: TemplateClassLoaderWithPlay now deals with pre-compiled classes. May help with Tomcat deployment using the post-controller mode.
2013/08/02: V0.9.22: 1. enhancement: set the template root path in relative to the Play.applicationRoot unless it's an absolute value. This also solves compatibility issue with running in servlet containers.

2013/08/01: V0.9.20: 1. new feature: added annotation and convention based route rule generation. Here is an example:

package controllers.t3; import cn.bran.play.JapidController; import cn.bran.play.JapidPlayAdapter; import cn.bran.play.routing.AutoPath; import cn.bran.play.routing.HttpMethod.GET; import cn.bran.play.routing.HttpMethod.POST; import cn.bran.play.routing.EndWith;

@AutoPath // == @AutoPath("/t3.App") public class App extends JapidController {

// effective path -> * /t3.App.foo
public static void foo() {
	renderText("hi foo  ");
}

// effective rule: *  /t3.App.tee/{a}/{b}
public static void tee(int a, String b) {
	renderText("tee: " + a +"::" + b);
}

// effective rule: * /t3.App.ff.  
// The param s will be taken from query string
@AutoPath(".ff") 
public static void fff(String s) {
	renderText("hi fff: " + s);
}

// effective rule: GET|POST  /t3.App.bb/{a}/{b}.html
@GET
@POST
@EndWith // ".html" by default
public static void bb(int a, String b) {
	renderText("hi: " + a +":" + b + "... reverse: " + JapidPlayAdapter.lookup("t3.App.bb", new Object[] {a, b}));
}

}

Please see the "effective" line to get the idea how the routing rule is generated. In theory what I call "Auto-rounting" has nothing to do with the rendering engine. I have rolled them together for convenience.

2012/10/15: V0.9.12: 1. bug: Any html files sitting directly in the {Japid Root} folder would lead to an exception. Now those files are ignored.
2. enhancement: view files now have an apply() method to match the naming convention in Play 2 views, sort of. 2012/10/15: V0.9.11: 1. bug: %{}% code block cannot have a leading new_line character 2012/10/15: V0.9.10.1: 1. bug: forgot to check op mode in JapidPlayRender.refreshClasses(); 2012/10/8: V0.9.10: 1. major feature: introduced JapidController2 and JapidPlayRenderer which employed independent view class loading and reloading to further decouple the view layer and the rest of Play. It should offer better turn-around time in DEV mode. See JapidSampleDecoupled for an example. The module doc was updated too. 2012/10/2: V0.9.6.1: 1. minor issue: validate file names when detecting file changes t filter out files with special chars in name. 2012/7/19: V0.9.6: 1. minor issue: removed extra line breaks around the "enter" and "exit" marker in the output when "tracefile" directive is on 2. new feature: added a method named traceFile() in the base class for Java classes comppiled from Japid templates to precisely put the "enter" file comment in tracing template. usage: just call the method from the template files like any Java methods: `traceFile();
2012/7/12: V0.9.5: 1. new feature: added evictJapidResultCache() in JapidController for invalidate a cached result of a Japid invoke action. See the Portlets.java in the JapidSample application for an example. The below is a few passages from the documentation: Since version 0.9.4.4, programmer have a couple of APIs in the JapidController to control the use of a cached JapidResult that is resulted from the use invoke in the Japid templates.

	1. *public static void ig