Introduction
Seam Forge is a tool that looks to lower the barrier to entry for starting projects, automate repetitive tasks (e.g. boilerplate project setup), and provide incremental technology additions to your project. The latest release is Alpha 3 and you can read what Lincoln has to say about it here:
While there has been quite a bit of interest in using and creating plugins for Forge, (e.g. Paul Bakker's Arquillian plugin), there have also been questions like "Where's the templating support?" (Rob Williams) or "Isn't Maven Archetype good enough?". In answering the second question, the current version of Archetype makes it difficult to make choices and once you've run the archetype, you're done (i.e. you cannot further enhance your project). The answer to the first question is the subject of this first of a two part blog. Fpak (Forge Package) is a plugin created by Mike Brock that provides a framework for processing templates to be used with Forge. In part 1, we'll look at what Fpak is and what it does. In part 2, I'll try to re-create the jboss-javaee6-webapp archetype structure with Fpak. (Note: The default templating support is based on MVEL 2, but anyone can add support for their favorite templating engine. Taking a deeper look at how to do this could be the subject of a subsequent blog post if there's interest.)
Getting Fpak
To start, let's take a look at how you can currently get a hold of Fpak. Since there hasn't been a release yet of Fpak, you'll have to build it yourself. Have no fear, it's a fairly painless process.
- prerequisites are git (I have 1.7.2), Maven (I have 3.0.3), and Java 6
- cd into the directory where you will "install" the source code
- clone the Fpak repository with: git clone https://github.com/mikebrock/fpak.git
- cd int the fpak directory
- run: mvn clean package
- in the target directory you will find fpak-1.0-SNAPSHOT.jar
- this jar has all the needed dependencies in it given it used shade. Note: there is a debate going on in Seam Forge about how to best handle dependencies that you can follow on the forge-dev mailing list if you're interested.
First look
Now that you have Fpak downloaded and built, let's take a look at the structure of a .fpk file. A test file can be found in the src/test/resources directory called test1.fpk. The file looks like this:
@inputs:{
String name : "Fully qualified class name",
boolean help : "Prints help"
}
@init:{
if (help) {
System.out.println(" --name <fullyQulifiedClassName>");
}
if (name == null) {
fail("You must specify a class name");
return;
}
package = name.substring(0, name.lastIndexOf('.'));
packageDir = package.replaceAll('\\\\.', '/');
classname = name.substring(package.length() + 1);
}
++@{packageDir}/@{classname}.java:{
package @{package};
public class @{classname} {
}
}
++@{packageDir}/@{classname}Entity.java:{
package @{package};
public class @{classname}Entity {
}
}
There are three primary sections to this file: 2 named blocks (@inputs and @init) and the file creation section. The @inputs block is where your inputs can be defined. You define the type and name along with an optional description. The format looks like this:
(String|boolean) <input_name> : "<short description here>"
In processing the inputs, a String will pull what comes after the input and place it into a variable that matches the input name. For example, when test1.fpk is processed with --name foobar, then value foobar gets placed into the name variable. booleans are just tested for there presence. Again, in the test1.fpk example, if it is processed with --help, then a variable called help will be set to true.
The next named section is the @init section. This section is processed after the @inputs section but before the file creation section. Given that the default templating language is MVEL 2, you can place any valid MVEL 2 syntax into this section. This includes conditionals and variable definitions. Taking a look at test1.fpk, you can see that the variables defined in the @inputs section are available to the @init section and that variables being defined in the @init section will be referenced in the file creation section. For more information on what can be defined in the @init section, take a look at the MVEL 2 documentation.
Last, but certainly not least is the file creation section. Each file that will be created is prefaced by a ++ operator followed by the fully qualified file name. The contents of the file are defined between the :{ and } delimiters. Remember that variables defined in the @init section can be referenced by these file templates via the @{variable_name} format. In this simple example, you'll notice that 2 files are created, <Classname>.java and <Classname>Entity.java.
Let's try this
Let's run Fpak on test1.fpk to see how this all works. Now, Fpak was created in order to run within Forge to allow for further Forge commands to be executed on the created project. But, when you defining a .fpk script, you probably don't want to have to bootstrap Forge to test the script. That's where the Runner for Fpak comes into play. Runner allows you to execute the .fpk script and see the results before wrapping it and making it available as a Forge plugin. So, here is how you can use Runner to run the test1.fpk script:
- create a tmp directory in the fpak root directory
- cd to tmp
- run: java -cp ../target/fpak-1.0-SNAPSHOT.jar org.jboss.fpak.Runner ../src/test/resources/test1.fpk --name org.test.Foo
- here's a sample of the output:
$ java -cp ../target/fpak-1.0-SNAPSHOT.jar org.jboss.fpak.Runner ../src/test/resources/test1.fpkWorking in: /Users/rruss/work/fpak/tmp/. You must specify a class name $ java -cp ../target/fpak-1.0-SNAPSHOT.jar org.jboss.fpak.Runner ../src/test/resources/test1.fpk --help Working in: /Users/rruss/work/fpak/tmp/. --name <fullyQulifiedClassName> You must specify a class name $ java -cp ../target/fpak-1.0-SNAPSHOT.jar org.jboss.fpak.Runner ../src/test/resources/test1.fpk --name org.test.Foo Working in: /Users/rruss/work/fpak/tmp/. created: /Users/rruss/work/fpak/tmp/./org/test/Foo.java created: /Users/rruss/work/fpak/tmp/./org/test/FooEntity.java $ find . . ./org ./org/test ./org/test/Foo.java ./org/test/FooEntity.java
And there you have it. This was a quick introduction to Fpak and what it can do. In part 2, I'll show my attempt at trying to mimic the jboss-javaee6-webapp Maven Archetype using Fpak.