This section is a step-by-step guide to using Jostraca. Before starting this guide you should download and install Jostraca so that you can follow the examples as you read. However, you can follow this guide without installing Jostraca.

1. What You Will Know After Reading This Guide

In this guide we will walk through the Hello World! example in the distribution. We will use Jostraca to generate the classic Hello World! message. We will also make some minor changes and observe the results. As a result, you will learn the basic mechanics of code generation with Jostraca.

2. The Hello World Message

We want to generate a text file called HelloWorld.txt that contains the following text:

Hello World!

The files for the Hello World! example are located in the example/helloworld folder of the distribution. The contents of these files are shown later in this guide. If you open the example/helloworld folder you will see the HelloWorld.txt file (ignore the other files for the moment). This file contains the Hello World! message, as shown above.

3. The Hello World Template

Take a look at the HelloWorld.jtm template, also in the example/helloworld folder. The contents of this template are shown below. This file is the Jostraca template which we will use to generate the HelloWorld.txt file. (Jostraca templates end with .jtm). Here are the contents of the template file:

<% @conf main.JostracaVersion = 0.4 main.TemplateScript = java %> <% init! _setFullFileName( "HelloWorld.txt" ); String who = "World"; %> Hello <%=who%>!

Here's an explanation of the various parts:

<% and %>

These are the template script markers. Everything inside these markers is template script, that is, instructions for generating the file HelloWorld.txt. Everything outside these markers is template text, which is copied directly to the generated file HelloWorld.txt. This syntax is the same as the syntax for Java Server Pages or Active Server Pages.

<% @conf
main.JostracaVersion = 0.4
main.TemplateScript = java
%>

This is the configuration (conf) directive. Here, you can specify settings that control the code generation process. There must be at least one conf directive in each template. One setting that must always be specified in the conf directive is the main.JostracaVersion setting. This tells Jostraca which version of Jostraca the template expects. This is used for backwards compatibility. The main.TemplateScript setting tells Jostraca that our template scripting language is Java. Other possible values are Perl, Python, Ruby and C.

<% init!
  _setFullFileName( "HelloWorld" );
  String who = "World";
%>

This is the initialisation (init) section. You can use this section to set up data and external resources that are used to create the generated file.

There is a difference between a directive (such as conf), and a section (such as init). Directives are instructions for Jostraca. Sections are places to put template script and text. The default section is called body.

The init section is provided so that you can initialise your code generation process. Template script in the init section is executed only once, for all generated files, so it is the best place to tell Jostraca what files you want to generate.

The statement _setFullFileName( "HelloWorld.txt" ); tells Jostraca that you want to generate a file called HelloWorld.txt. The function or method _setFullFileName is known as a template service method. There are a number of template service methods; they all begin with underscore ("_") and are primarily used to tell Jostraca what files to generate and where to save them.

The statement String who = "World"; sets up a String variable containing the text "World" so that we can use it later.

Notice that these are perfectly normal Java statements.

Hello <%=who%>!

This is the actual text that we want to generate. The Hello text is copied directly to the generated file HelloWorld.txt. The <%=who%> part inserts the value of the variable who into the text of the generated file. The exclamation mark at the end ("!") is just template text and is also copied directly to the generated file. Only characters inside the markers <% and %> are considered to be template script.

4. Generating HelloWorld.txt

Let's generate the file HelloWorld.txt from the HelloWorld.jtm template. At the shell terminal or command prompt, execute the following command (you should be in the example/helloworld folder of the distribution):

jostraca HelloWorld.jtm

Template:         HelloWorld.jtm
Saved file:       ./HelloWorld.txt

Jostraca used the template to create a text file called HelloWorld.txt, and saved this text file to the current folder. Open the HelloWorld.txt file to verify that the code generation succeeded.

NOTE: if you run the command jostraca HelloWorld.jtm again, you will not see the line Saved file: ./HelloWorld.txt. Jostraca only generates files when the template has changed. If the template has not changed, then the generated file will be the same, so that there is no need to run the code generation process. If you make a change to HelloWorld.jtm, then a new HelloWorld.txt will be created.

To summarise: the general approach taken by Jostraca is: you write a template which then generates a text file. The template consists of two types of content: template text which is copied directly to the final text file, and template script which is executed by Jostraca to produce more template text. The template text can be anything you like. It is just pure plain text. The template script is written in the language you have chosen to use for code generation. This can also be any language you like, as long as you have configured Jostraca properly.

5. Making Some Changes

Now let's try something a bit more ambitious. We'll generate two text files: HelloAlice.txt and HelloBob.txt. We want to do this from the same template because we are lazy programmers and we don't want to have to type "Hello" twice!

We want to create two text files:

HelloAlice.txt:

Hello Alice!

and HelloBob.txt:

Hello Bob!

To generate both text files from the same template using Jostraca, let's identify the metadata. The metadata is the data about the files that we are trying to create. In this case, it's the names "Alice" and "Bob". The different names define the different files. Let's store this metadata in a String array.

To bring this together, we'll create a new template called HelloPeople.jtm (you can do this in the example/helloworld folder, if you like):

<% @conf main.JostracaVersion = 0.4 main.TemplateScript = java %> <% init! String[] names = new String[] { "Alice", "Bob" }; _setFileNamePrefix( "Hello" ); _setFileNameRoots( names ); _setFileNameSuffix( ".txt" ); %> Hello <%=names[ _getFileIndex() ]%>!

We can now execute the command:

jostraca HelloPeople.jtm

This time, Jostraca outputs:

Template:         HelloPeople.jtm
Saved file:       ./HelloAlice.txt
Saved file:       ./HelloBob.txt

First we created an array of names:

  String[] names = new String[] { "Alice", "Bob" };

Then we used _setFileNameRoots instead of _setFullFileName. This tells Jostraca that we are going to generate more than one file, by giving Jostraca a list of file names. The root is the most important part of the file name, as it is the part that is different for each file generated. In this case, the part that is different is the person's name; "Alice" or "Bob". We also used _setFileNamePrefix( "Hello" ) to specify that we want the word "Hello" placed in front of the names. And we used _setFileNameSuffix( ".txt" ) to tell Jostraca to put ".txt" after the names. The result is that Jostraca generates the files HelloAlice.txt and HelloBob.txt. Again, the init section executes only once, before any files are generated. This ensures that our metadata is set up safely.

The template content is

Hello <%=names[ _getFileIndex() ]%>!

This inserts the person's name after the Hello text. How do we get the correct name? The method _getFileIndex() returns the index of the current file being generated. This always starts at 0. In our case, the file index for Alice is 0 and the file index for Bob is 1. Why? Because this was the order we specified in the array passed to the _setFileNameRoots template service method. We can use this index to access the array of names we set up in the init section: names[0] has the value: "Alice" and names[1] has the value: "Bob".

6. Final Points

Although this example was very simple it introduced almost everything you need to know about Jostraca. In the real world you probably won't want to hard code your metadata into the template - it will come from a database or from an XML file. You might be asking "How do I get hold of this metadata?" The answer is: any way you like! You can access external resources from the init section just as you would in any other program written in the scripting language for your template.

You might also be wondering about the special methods like _setFileNameRoots(). Don't worry, there aren't that many - the number has been kept deliberately low. The same goes for configuration options. In fact, most of the time you won't need to use them since the defaults are what you would expect. For more detailed information you can use the reference documentation.

Jostraca has to be configured correctly to use a given language as the template script language. The following languages are supported out of the box: Java, Perl, Python, Ruby and C. Of course, you will need to install the compilers and runtimes for these languages first.

7. Further Information

To find out more about Jostraca, work through the tutorials and the examples. If you really want to know the gory details, refer to the manual and the reference section.

If you have any problems with this tutorial please let us know: info@jostraca.org.