JBoss Forge Hands on Lab

Extract the distribution archive, to the directory you wish to install Forge.
Add the FORGE_HOME environment variable.

In the same dialog, add %FORGE_HOME%\bin to the system path.

Now open a system cmd or command prompt and run JBoss Forge by typing the forge command.

The easiest way to install Forge is to extract the distribution archive, to the directory you wish to install Forge. In a command terminal, add the FORGE_HOME environment variable, e.g:

Add FORGE_HOME/bin environment variable to your path, e.g:

You can also install Forge via cURL

or use Homebrew to install Forge natively, via:

Run JBoss Forge by typing the forge command in your system terminal.

The project-new command is what we will use to quick start a project :

This will create an empty Maven project structure and a pom.xml file. The default groupId is org.cdbookstore, artifactId is cdbookstore and version number 1.0.0-SNAPSHOT. Also, the default project created is a web application, that’s why you can see a packaging of type war and maven-war-plugin defined. The stack command option will automatically install the JavaEE 7 dependencies in your pom.xml. If you want to change any of these options, just press TAB after a command and you will get all the command options:

If you run Forge from JBDS, open the Forge wizard (Ctrl + 4 or CMD + 4 on Mac) then select Project: New and specify cdbookstore as project name, com.example as top level package, enter project location per your preference:

To set up JPA and create a new JPA entity, let’s use the jpa-new-entity command :

This command has several effects. First of all, it has created a persistence.xml file in the right place (under the META-INF directory) with all the default configuration for Hibernate. Then, it has created a Book entity under the subpackage model. Notice that this entity already has an id and version with its getters/setters. As you can see, the good thing with Forge is that with only one command all is setup and ready to go.

If you do not wish to use the Java EE container default data-source, you can also specify additional connection options such as JNDI data-source names, JDBC connection information, and data-source types. Note, however, that this means you will probably need to configure your application server to provide this new data-source and/or database connection.

If you have executed the jpa-setup command, you’ve noticed that the prompt has changed: you went from [cdbookstore] to [persistence.xml]. In Forge, the prompt always tells you where you are. You can even enter the command pwd or ls. For now, let’s go back into the Book entity: enter cd~~ brings you to the root directory, and then cd src/main/java/org/cdbookstore/model/Book.java.

So, let’s create a few fields in the Book entity. Again, one single command and Forge will do its best to simplify our lives:

This creates an attribute called title of type String with get/set methods. Notice that Forge has also updated the toString method. Let’s add more commands with different options (remember to press TAB to get the options) :

As you can see, Forge has a set of options to quickly create attributes and customize their JPA mappings. Now let’s say we want to specify that a book is written in a certain language. We can use Forge to quickly create a Java enum and then have it as a JPA Enumerated in the Book entity :

This creates a Java enum, but notice the path on the left side : Forge CLI was set on the Book class (that’s why you could read [Book.java]$). When we created the enum, the path changed to [Language.java]$. Like any other shell script, Forge has a certain number of commands to navigate between directories, classes or files (you will find the full list of commands in the Appendix). So, to go back to the Book entity we just use the cd command :

Now that we are in the Book entity, we can create a new enum field with the following command :

By default, a JPA field is of type String. With the --type option we can choose from basic datatypes (int, byte, char…), enum, or from other entities and entity cardinality (One-to-One, One-to-Many, Many-to-One, Many-to-Many). So let’s create a new Author entity, and add a Many-to-One relationship with Book :

Forge takes care of all the JPA relational mapping between both entities. Now, on an entity, we can add Bean Validation constraints on properties with the constraint-add command.

Behind the scenes Forge has created a validation.xml file, added the Bean Validation dependency and the needed constraints. If you want to take a glance at the code, and see a summary of progress, you can use the more command or even ls your class :

While working from JBoss Developer Studio (JBDS), after opening the Forge wizard (Ctrl + 4 or CMD + 4 on Mac), you should choose JPA: New Entity and you’ll see a JPA configuration window. This window provides default values for the Java EE container default data-source, but if you not do wish to use it, you can change your configuration as specified before with CLI.

In the first step you need to setup JPA in your project:

The next step you need to configure your connection settings:

After the configuration step, you can create your first entity.
Enter Book as Entity name, org.cdbookstore.model in Target package and click Finish.

Then you need add fields to your Entity. After opening the Forge wizard (Ctrl + 4 or CMD + 4 on Mac), you should choose JPA: New Field and select the Book as Target entity, title as Field Name, String as Type and click Finish:

Repeat these steps to create the following fields in the Book class:

Now you need to specify that a book is written in a certain language. We’ll create a Java enum and then have it as a JPA Enumerated in the Book entity. After opening the Forge wizard (Ctrl + 4 or CMD + 4 on Mac), you should choose Java: New Enum and enter org.cdbookstore.model in Package name and Language in Type Name:

Now you need to add new constants to it. After opening the Forge wizard (Ctrl + 4 or CMD + 4 on Mac) you should choose Java: New Enum Const and add all constants, in this case:

and click Finish:

Now, you need add this enum as a field in Book. After opening the Forge wizard (Ctrl + 4 or CMD + 4 on Mac) you should choose JPA: New Field and select the Book as Target Entity, enter language as Field name and select org.cdbookstore.model.Language as Field Type:

Now you need to create a new Entity (Same that you did with Book):

and create a new field to it (Same that you did in Book):

Now you need to add a Many-to-One relationship with Book.

Open the Forge wizard (Ctrl + 4 or CMD + 4 on Mac) and choose JPA: New Field, select the Book as Target Entity. Enter author as Field name, select org.cdbookstore.model.Author as Field Type and mark Many-to-One as Relationship Type and click Finish (or Next):

If you choose Next instead of Finish, You can configure your relationship:

Forge takes care of all the JPA relational mapping between both entities.

Now, on an entity, we can add Bean Validation constraints. Open the Forge wizard (Ctrl + 4 or CMD + 4 on Mac) and choose Constrait: Add. You’ll see a configuration window, just like first step of the JPA: New Entity that you executed before:

You should choose the Generic Java EE as Bean Validation provider and check "Provided by Application Server?". If you don’t want the default configuration provided by Application Server you are free to change your configurations. Click Next, and choose org.cdbookstore.model.Book as Class:

In the next step you need to specify the property Property and the Constraint to configure. In this case, let’s add @NotNull on the title property:

Once the constraint is selected, you can also specify if you want the constraint to appear on the property itself, or on the property accessor (getter method).

Click Next to configure payload, groups and message:

Click Finish.

Now add two more constraints to the Book class:

Now that we have created fields in the entities, it’s time to scaffold web pages for these entities. We can either scaffold per entity, or use a wildcard to let Forge know it can generate a UI for each entity

This has the same effect of scaffolding per entity :

In a single command Forge has generated configurations files (web.xml, faces-config.xml, …​), JSF pages for both Book and Author, images, CSS and added Bootstrap for the layout.

By default Forge scaffolds a web application with JSF 2.0 but you can change this configuration by executing the faces-setup command. In fact, most of the Forge commands can be setup (e.g. jpa-setup, servlet-setup…​)

In JBDS it’s simple too. After opening the Forge wizard (Ctrl + 4 or CMD + 4 on Mac) you should choose Scaffold: Generate, choose Faces as Scaffold Type:

If you haven’t selected the Java EE 7 stack when creating the project, click Next to configure the Faces Scaffold:

By default Forge scaffolds set suggested values for Java EE specification versions, but you can change this configuration as well.

Click Next to continue to select entities for which you want to generate scaffolding. In this case we’ll generate for all entities:

Click Finish and JBoss Forge will create your user interface.

Now that we have a few entities (Book and Author), it’s time to generate REST endpoints. Like for JSF, it is just a matter of executing one single command:

This is the easiest command to generate the REST endpoints, but like most Forge commands, you can customize a few options if you want, such as package name and so on.

While "holding" most files as the current resource, you may inspect them using ls. This also works on REST endpoints. So, if you cd BookEndpoint.java (if you have not selected it already) and execute the command ls, this is what you get :

Open the Forge wizard (Ctrl + 4 or CMD + 4 on Mac) and choose REST: Generate Endpoints from Entities, the first step, you need to configure the REST in your application, enter all information such as:

Click next to select the entities for which endpoints should be generated, select all, and click Finish (or click Next for more options):

You can customize some options if you prefer, such as Configuration Strategy, Class Name, Content Type and so on.

The beauty of JBoss Forge is that it’s extensible. In fact, Forge is a add-on container (called Furnace) and everything is seen as an extension (as a matter of fact, the CLI itself is an add-on!). To see the list of add-ons, visit the Forge documentation(http://forge.jboss.org/addons). And if you want to see all the already installed add-ons, execute the following command :

Enough, talking, let’s install the WildFly add-on. For that, in the Forge console just type the following commands (and wait for Maven to download the Internet) :

Now that you installed these new add-on, you get new as-setup command :

Wait a bit until WildFly is downloaded…​. (in the meantime you can go to ~/.forge/addons and have a look at what’s happening…​ you can even check the logs under ~/.forge/log/forge.log)…​ ok, now that Wildfly is downloaded into your local Maven directory…​ there it is…​. just type as, press TAB and you will see new commands :

So let’s build the application, start JBoss with as-start and deploy our application with as-deploy :

WildFly is started, the application is deployed, you can now go to http://localhost:8080/cdbookstore and create new books and authors.

Open the Forge wizard (Ctrl + 4 or CMD + 4 on Mac) and choose Install an Addon from GIT, enter https://github.com/forge/jboss-addon as GIT Repository URL and org.jboss.forge.addon:as as Coordinate:

Open the Forge wizard again (Ctrl + 4 or CMD + 4 on Mac) and choose Install an Addon from GIT, enter https://github.com/forge/jboss-as-addon as GIT Repository URL and org.jboss.forge.addon:jboss-as-wf as Coordinate:

It’s now time to set up your server. Open the Forge wizard (Ctrl + 4 or CMD + 4 on Mac) and choose AS: Setup, then select wildfly8:

Click next to configure the Install directory, Port and so on:

Now let’s build the application:

Open the Forge wizard (Ctrl + 4 or CMD + 4 on Mac) and choose Build:

Now start server with the AS: Start command and deploy application with AS: Deploy:

Click Finish, and your application will be deployed on WildFly.

Like the WildFly add-on we just installed and used, bringing Arquillian capabilities to Forge is just a matter of installing one add-on. The easiest installation method is to install directly from a Git repository by executing the following command in the Forge console:

To make sure the add-on is properly installed, enter arq and press TAB, you should see the command arquillian-setup. Now, let’s use it.

The first thing to do is to setup Arquillian for WildFly by executing the following command:

This command adds all the needed dependencies in our pom.xml (JUnit, Arquillian core, Arquillian extension for WildFly) and Maven Profile (arquillian-wildfly-remote) to run the Arquillian tests. This command has also created an arquillian.xml file where all the Arquillian configuration goes. As you can see, with a single command, JBoss Forge has dealt with all the plumbing configuration.

To create an Arquillian tests, it is as easy: we use the arquillian-create-test command and target a specific bean. For example, in our example we can create a test for the BookBean as follow:

This creates the BookBeanTest under src/test/java. The way to run this test is first, make sure WildFly is up and running, second, open a command prompt (outside Forge) and run Maven using the right profile:

The test might not work and you should look at the stack trace on the server side. If you get any java.lang.ClassNotFoundException (example org.cdbookstore.model.Book) that’s because you need to fix the Shrinkwrap packaging by adding the missing class. And if the persistent unit is unknown, you need to package it explicitly under the META-INF directory. For example, in the code below, Shrinkwrap wraps the BookBean and its dependent classes into a single deployment:

The test should be green. Isn’t it?

Again, with a few Forge commands you manage to setup Arquillian, generate a test and execute it. You have no more excuse for not testing.

The good thing about the Java Petstore is that we don’t have to explain it much: most of us have heard about it. Haven’t You?

The Java Petstore was a sample application created by Sun for its Java BluePrints program. The Java Petstore was designed to illustrate how J2EE (and then Java EE) could be used to develop an eCommerce web application. Yes, the point of the Petstore is to sell pets online. The Petstore had a huge momentum and we started to see plenty of Petstore-like applications flourish. The idea was to build an application with a certain technology. Let’s face it, the J2EE version was far too complex using plenty of (today outdated) design patterns.

With a single Forge script, you will generate a CRUD application that will let you manage the Pet’s back-end catalog.

First of all, download the script from https://github.com/forge/docs/blob/master/tutorials/forge-hol/scripts/generate.fsh. You can have a look into it. As you can see, the script:

Now execute the script with :

Depending on the location of the script file, you can also run :

You will see hundreds of lines of code scrolling. Once the project is successfully created, have a look at the thousands of lines of code (Java, XML, HTML, CSS…​) that Forge generated. The only missing feature today in Forge is the ability to generate methods. That’s why some classes are just empty (e.g. the service tier). But adding method is in the roadmap.

And the best of all, is that it works! To build the application, just do it in Forge :

Before deploying the application on WildFly you can grab the SQL script https://github.com/forge/docs/blob/master/tutorials/forge-hol/scripts/import.sql and copy it to petstore/src/main/resources. This will add data to the database.

Then, just deploy the war file into WildFly, go to the URL http://localhost:8080/petstore and you should see the following homepage :

Do not hesitate to browse the database content, create new items, remove customers, filter addresses, update categories…​ JBoss Forge has just created an entire CRUD web application for our domain model dealing with all the many-to-one, one-to-one…​ relationships.

Also check the REST interfaces. You can use any REST client (such as Postman for example) to GET/POST/PUT/DELETE data to the database. Go to the following URLs to get a peek at the REST data:

Now that you’ve seen it running, it’s time to take a break, fill up a cup of coffee and have a look at the code. This is what you will find in the following packages :

Now that you have a real application up and running, let’s use JBoss Forge to extend it by developping a few add-ons and applying them to the Petstore application.

Creating a new Forge addon is similar to creating any new project. You can do it manually, copying and modifying an existing project of the same type, or you can use a Forge wizard to do it for you. We would certainly recommend using Forge to help you bootstrap everything for several reasons. It knows exactly which dependencies and artifacts you need as a starting point, so you will not miss anything. Forge will also not create any garbage in your new project.

Before creating the Envers addon, you need to start Forge. Before you continue, please make sure that you have followed the instructions in the Section: [installing-forge]. You can create a new addon if you run the following command in the Forge CLI:

If you run Forge from JBDS, open the Forge wizard (Ctrl + 4 or CMD + 4 on Mac) then select Project: New and specify envers as project name, org.jboss.forge.addon as top level package, enter project location per your preference and as a Project type select Forge Addon:

This will create a skeleton Maven project that has the following artifacts:

The first command that we are going to create will set up Envers for a project. This basically means that the command will add the Envers library dependency to the current project POM (but will not actually directly edit the file, because Forge supports multiple build systems!). As with the new Forge addon, we can manually write the command class, copy and modify an existing command or let Forge itself generated it for us. Here we will go for the third option.

If you are running from the command line interface, type in:

In JBDS, open the Forge wizard (Ctrl + 4 or CMD + 4 on Mac), then choose Addon: New UI Command and enter EnversSetupCommand in the Type Name field, Envers: Setup in the Command Name field and add Auditing to the Categories list box:

This will generate the EnversSetupCommand class in the org.jboss.forge.addon.commands package (unless you specify a different package). Forge makes this new command class extend AbstractUICommand, which provides some basic functionality like configuring the command name, the command dialog and the command execution. We will go through these in this and the next few sections.

The getMetadata() method is where basic information about your command is defined, and should be already implemented by Forge (using the values you specified in the New UI Command wizard):

This will basically create a command that can be called envers-setup from the CLI (note the substitution of colons and spaces by hyphens) and as Envers: Setup in the Auditing category in the Forge wizard

As the newly created command will not require any input from the user, we will leave the initializeUI method empty. However, in order to implement the command execution behavior, we will need to change a little bit our class. More precisely we will have to extend from another abstract command class. The rationale behind this is that we want to update the current project POM, so extending org.jboss.forge.addon.projects.ui.AbstractProjectCommand instead of AbstractUICommand will give us some handy methods to access and manipulate the Project itself:

We now have to implement two more abstract methods coming from this parent class. Take a moment to review the JavaDoc for these new methods, and understand their behavior. If you are confused, ask for help!:

The org.jboss.forge.addon.projects.ProjectFactory interface is used to create new or obtain references to existing project.

+ After having specified Envers: Setup as a "project command", we can now proceed to implementing the execute method. Usually this is called when the user clicks Finish on the command dialog or in our case, when the command has no inputs, and will be executed as soon as it is selected from the Forge quick start menu.

+ As we mentioned earlier, the command needs to add the Hibernate Envers dependency to the project. So first, let’s create a representation of this dependency using the org.jboss.forge.addon.dependencies.builder.DependencyBuilder utility class:

Speaking in Maven terms, this is a dependency on an artifact with ID hibernate-envers, coming from the org.hibernate group, having version 4.3.6.Final and going into the project’s provided scope.

After we have specified our dependency, we will have to add it to the project model. For that purpose we will use the org.jboss.forge.addon.projects.dependencies.DependencyInstaller utility, responsible for installing a given dependency into the project :

Forge 2.0 is based on modular runtime called Furnace. The core of Furnace itself is not bound to any development model, so addons can decide which of the Furnace container implementations it wants to use. We created our addon with the default configuration which enables the CDI container and development model. That is why we were able to use @Inject in the code snippet above. Forge will provide us with the dependency installer service, which we can use to add dependencies to selected Project when our command is executed.+

Now it is time to install our dependency:

We are using here one of the helper methods provided by the AbstractProjectCommand: getSelectedProject().

Now our job is done, so it is time to report what we did. We do it by returning the result:

This will result in a SUCCESS: message in the command line interface and a green popup in the JDBS after our command is executed.

Now that we have a command the enables Hibernate Envers, it is time to add another command that will turn on auditing for a given JPA entity.

We will create the class for the new command in the same way that we created the one for "Envers: Setup": with the help of Forge. If you are running the CLI, then simply type:

Or alternatively in the JBDS choose Addon: New UI Command, enter EnversAuditEntityCommand in the Type Name field, Envers: Audit entity in the Command name field and add Auditing to the Categories list box:

Then open the newly created class and make it extend AbstractProjectCommand instead of AbstractUICommand and also add the unimplemented methods the way you did it in the setup command.

This command will have to receive as input the entity class that has to be audited. To achieve this, we need to do two things:

Starting from number one, we should add the following member field to our command class:

Here we call our field auditEntity. This automatically will add a --auditEntity option to our command in the CLI. The type of the field is UIInput<JavaResource>, which means a few things:

We have also specified some additional attributes with the @WithAttributes annotation:

After we define the input field, it is time to add it to the command dialog. In order to do that, we need to edit the initializeUI method:

We can tell now Forge to show a Browse button to the right of the input field, which will open the well known type picker of Eclipse. This is done by setting an InputType hint in our input. There are several input types to choose from, but we will need JAVA_CLASS_PICKER:

In Forge you can also set default values for inputs. This way you can omit specifying its value on the command line and in the IDE it will be pre-filled in the command dialog. You can do that with the setDefaultValue method of the UIInput. In our case the UIInput is generified over the org.jboss.forge.addon.parser.java.resources.JavaResource class, so we’ll have to check whether the current selection in the UI (being the CLI or JBDS) is a file that represents a Java type. If yes, we will set it as the default value of the text field:

Now that the command interface is ready, we can go on and implement the execute method. First, we should get the value entered in the text field and convert it to a JavaResource, then we will extract the JavaClassSource out of it so that we can manipulate things like annotations:

Next we will check whether the chosen class has already the Audited annotation and if not, will add it to that. At the end we’ll save the new content and will return successful result:

But what if the user enters invalid input? This could be a file that does not exist, or is not a class or is not a JPA entity. We’ll implement the validate(UIValidationContext validator) method to handle such situations. Whenever it finds illegal input, it will add a validation error to the validator parameter. This will raise an error message if the command executes in the CLI; JBDS will show an error message and disable the Finish button of the dialog until the illegal value is corrected. This is how we implement the method:

Finally, we want to avoid some compilation errors in the project where we will run this command. So it should be only available for execution if the user has called the setup command first, i.e. if the current project has dependency to Hibernate Envers. You can implement this enabling and disabling in several ways. We will show one of these: by implementing the isEnabled method. There we will again obtain the DependencyFacet and will ask it whether the desired dependency is installed. If this method returns false, the Forge commands wizard will not list the Audit entity command and it will not be available in the command completion in CLI. This is the implementation:

Our first addon is ready. We can now build it, deploy it and run it on the Java EE project that we created in the beginning of this chapter.

Once we have our basic functionality, we can build and install our new addon. For that we should use Forge’s addons addon. It has a very handy command: Addon: Build and install. You can run it from the command line, or the IDE:

If you don’t specify the project-root parameter, Forge will look for the sources of your addon in the current folder. If this is not the intended behavior, in the CLI run the command like that:

In JBDS, either select the addon project before running the command, or specify the correct path in the command dialog:

This will trigger a build of the addon, and if it is successful, Forge will install it in its addon repository. You don’t have to restart the tool; Forge it will automatically load the new software once it is deployed. After you see the success message, you can re-run the Forge quick access menu and will see the new command in the command list:

Now you can set up Hibernate Envers and open one of the JPA entities that you generated before starting to develop this addon, e.g. Country. You should be able to call now the other command. In the CLI:

Or in JBDS press Ctrl + 4 (or CMD + 4 on Mac) and then pick the Envers: Audit entity from the command menu. Notice that the class that you opened in the editor (org.jboss.forge.hol.petstore.model.Country) was selected automatically for you:

Just hit Enter and the entity will get the @Audited annotation.

Voila! :)

In this final section of this chapter we will show you some more features that you could use when developing Forge addons. In order to showcase those, we will add a new requirement to the envers addon. Suppose that we want when we set it up to state that we want every new JPA entity that we create to be automatically audited. This means that the Envers: Setup command should be executable more than once, but it should add the Hibernate Envers dependency in the POM only the first time it was executed.

So, our first job is to enhance our setup command with UI in the form of a checkbox that asks the user whether they want their JPA entities to be automatically auditable. We’ll use again the familiar UIInput class, but this time we’ll generify it with Boolean. This will tell the IDE integration of Forge to automatically create a checkbox:

Let’s now add the checkbox to the command dialog using the UIBuilder:

Next, we are going to make it possible running the setup command numerous times without polluting our POM file with as many dependencies to Hibernate Envers. For that we are going to use something as familiar - the DependencyFacet:

Finally we want to tell potentially other addons and commands whether the user wants or not to automatically add auditing to newly created JPA entities. For that we can use Forge’s configuration. It is file based key-value-pair API, which can be used for storing project or Forge settings. The pairs are stored in .forge_settings file in the project root directory (this is the only non-project artifact that Forge creates) or in ~/.forge/forge.xml directory if it is the global Forge configuration.

In order to get hold of the project configuration, you need to ask the ConfigurationFacet for it:

Using the configuration API is straightforward. We can add this line in the execute method just before the return statement and it will add the boolean value of the checkbox to the project configuration file:

Now, whenever and wherever we want to find whether the user has decided to automatically audit new JPA entities, we’ll just need to lookup the autoAudit entry in the project configuration.

We can furthermore enhance the UI of our command by reading the configuration upon building it and finding out what is the current value of autoAudit. Based on that we can change the default value of our checkbox. For example, if the user has already run the setup command and has checked the checkbox, the next time when they run it, we want it checked rather than unchecked. As usually we want to take care of the situation when the entry is not available at all, i.e. the property is null, by providing a default value to the getBoolean method:

Now it is time for the final step in our journey: implementing automatic auditing of JPA entities. What we want now is every time the user creates a new entity class using Forge’s JPA: New Entity command, to instrument that class with the @Audited annotation.

If you want to react on the execution of a Forge command, you should implement the CommandExecutionListener interface. Its methods give you hooks to the point before a certain command is executed as well as after the execution completes. There are a couple of methods for the latter: once for successful and another one for erroneous outcome:

In our case we’ll just want to implement the postCommandExecuted method. We want it to do its work only if the current command is JPA: New Entity

Next we want to get hold of the project configuration to check whether automatic auditing was selected by the user. It was easy in the AbstractProjectCommand descendants to get the selected project with the respective utility method and then to obtain the configuration facet from there. Now we have to go through the Projects.getSelectedProject static factory method for that. It needs to get a project factory, which luckily we can inject. It would be also safe to check whether it is null and only then proceed to the entity instrumentation:

Now with the Configuration instance at hand we can go on and check what the user preference is:

We’ll finally take advantage of the fact that Forge automatically selects a newly created class as the current resource. So, we’ll get the current selection, we’ll cast it to JavaResource and we’ll basically do the same thing we did in the Envers: Audit entity command:

That’s it. You can now try what you have done.

For your reference, the full source code of the Forge Envers addon can be download from here.