This guide shows how to get a simple "Hello World" bLight application up and running using command-line tools. For simplicity, this example is a command-line application which runs and template and then exits. It is not an example of good practice, as it omits nicities such as error handling, logging and unit testing. The complete source code and configuration discussed here can be downloaded together in a single zip file.
bLight includes a command-line interface to the template compiler to allow integration with other build systems. An example built using the command-line is shown below.
Templates should be placed together with your other Java code under src/main/java. It is recommended that templates are placed in their own package. In the example, the application consists of the main MyApp application class, and a single template named MyTemplate. The lib directory will eventually contain the libraries required to build and run the application.
/ |-- lib/ `-- src/ `-- main/java/example/mycompany/myapp/ |-- MyApp.java `-- templates/ `-- MyTemplate.java
The bLight Java API is quite small. There are only two classes which you need to be familiar with - AbstractTemplate which is the default parent class for all templates, and the TemplateManager which executes templates.
The application code creates a template, sets the output to System.out and executes the template. Note: While it is possible to execute templates directly, it is recommended to always use the TemplateManager. This allows for dynamic template compilation (see below) during development without requiring an application restart each time a template is changed.
package example.mycompany.myapp; import java.io.IOException; import java.io.PrintWriter; import com.aleax.blight.TemplateException; import com.aleax.blight.TemplateManager; import example.mycompany.myapp.templates.MyTemplate; public class MyApp { public static void main(final String[] args) throws TemplateException, IOException { // Create a new template MyTemplate template = new MyTemplate(); // Configure the template to send its output to System.out PrintWriter out = new PrintWriter(System.out); template.setOutput(out); // Compile and execute the template TemplateManager.execute(template); // Ensure the output is written before the app terminates out.flush(); } }
The template extends AbstractTemplate and must implement the execute() method. Any comments within this method are written to the template output when the method is called on the compiled template. The example template also contains a single setter to pass in the customer details to include in the template output.
package example.mycompany.myapp.templates; import java.io.IOException; import com.aleax.blight.AbstractTemplate; public class MyTemplate extends AbstractTemplate { @Override public void execute() throws IOException { /*Hello World!*/ } }
Download and unpack the bLight binary distribution into the lib directory. The lib directory structure should end up with the following:
lib/ `-- blight-dist/ |-- LICENSE.txt `-- doc/ `-- lib/ | |-- compiler-libs/ | |-- blight-compiler.jar | `-- blight-core.jar `-- tools/ |-- blight-ant-task.jar |-- blight-compiler-standalone.jar `-- blight-maven-plugin.jar
For basic use, bLight only requires a single library at runtime. The blight-core.jar will need to be added to the class path which you use to compile and run your project.
bLight templates must be compiled before they can be used. For a production deployment, they should be pre-compiled using the bLight command-line tool. The basic steps are:
An example of how to do this is shown below.
#!/bin/bash javac -cp lib/blight-dist/lib/blight-core.jar -sourcepath src/main/java -d target/classes java -cp tools/blight-compiler-standalone.jar com.aleax.blight.compiler.BatchCompiler -s src/main/java -p example.mycompany.myapp.templates -o target/compiled-templates javac -cp lib/blight-dist/lib/blight-core.jar:target/classes -sourcepath target/compiled-templates -d target/classes
The application can then be run with the following:
#!/bin/bash java -cp lib/blight-dist/lib/blight-core.jar:target/classes example.mycompany.myapp.MyApp
Templates can be compiled at run-time for faster development without requiring an application restart after each change. To enable this functionality, the blight-compiler and template java sources must be added to the classpath, and the templates must not be pre-compiled until the application is packaged.
The compilation script just needs the template compilation steps commented-out:
#!/bin/bash javac -cp lib/blight-dist/lib/blight-core.jar -sourcepath src/main/java -d target/classes #java -cp lib/blight-compiler-1.0.0-jar-with-dependencies.jar com.aleax.blight.compiler.BatchCompiler -s src/main/java -p example.mycompany.myapp.templates -o target/compiled-templates #javac -cp lib/blight-dist/lib/blight-core.jar:target/classes -sourcepath target/compiled-templates -d target/classes
The application can then be run with the following:
#!/bin/bash java -cp lib/blight-dist/lib/blight-core.jar:tools/blight-compiler-standalone.jar:src/main/java:target/classes example.mycompany.myapp.MyApp