JBoss Technology Evangelist - How to create simple, consistent, repeatable demo projects

This is a series of article that give you a glimpse behind the scenes of how JBoss Technology Evangelists do what they do.

It is not a blueprint, but more of a series of tips and theories that have been accumulated through years of telling the JBoss stories we tell.

This first article will tackle the mystery of how JBoss Technology Evangelists are able to consistently create working, easy to use and repeatable demo projects.

When standing on a stage or doing a live demo in an online session, it all looks so easy but of course there is a lot of work that goes on behind the scenes to get a project into that perfect looking state.

It is not only the story you want to tell, but the technology in a project that must support that story without failing. As we often have to setup different JBoss technologies it became a necessity to tune some sort of generic framework or template to put these demo project into.

Over the last three years the goal has always been guided by three principles:

• KISS (keep it simple stupid)
• Consistency
• Repeatability

These stem from our supporting anyone who wants to explore and get started with a JBoss technology. Note that while these are listed in an order that does have some significance as to what is most important, they all have to balance against each other.

If one must be weighed more heavily than any when using technology, it is KISS, so you will find that this is followed almost religiously when deciding how to solve anything within this demo project template.

Simple

They need to have a simple setup taking almost no effort to get them started, or more realistic, the least amount of effort as possible.

Each project requires but three steps to get going:

1. Download and unzip the project.
2. Add products to installs directory in the project.
3. Run init.sh (for Unix) or init.bat (for Windows) to install project.

That is it, just watch the install output to continue with the project as you see fit.

This setup also relies on the very smallest or basic set of dependencies that are physically possible for unix & windows based systems; Java and Maven, nothing more than that.

It is all about learning what the project in front of you does, so it must be clear and offer the possibility to explore how it was setup, configured and runs. Based on your feedback over the years, full automation is not desired as it takes the project out of the learning sphere for the user.

There is a balance offered when installing a project with auto configuration and setup, but there are still some steps that allow you to pause, consider and explore what has been done.

Consistent

The only way to be able to jump between all the various JBoss technologies and products is to have some consistency in our demo projects. A customer, partner or interested party needs to be able to recognize a simple and clear form of project setup.

This is done with a simple and clear project template structure:

• docs/
• project documentation and screenshots.
• installs/
• where you place needed JBoss products.
• projects/
• sources for services, clients, or other project based code.
• support/
• all other configuration, setup or other needed files / utilities.
• init.{sh|bat}
• installation scripts to setup project.

That's it, every single time it will look like this.

Repeatable

Nothing is worse than having to provide a demo project and spending a large amount of time on it to only be able to have it run one time. There is often a factor that rushes the completion of a project so that one has little chance to bring some sort of order into it.

This template allows you to develop your project while saving the repeatability of the project. Note that all setup is done in a new directory called target where you can then throw it all away and just setup the project again (with the initial init script).

This is a golden rule, that every demo project it should be repeatable in minutes, if not less.

JBoss demo template project

You have seen amazing demos done by JBoss Technology Evangelists, but you want to create your own awesome demo to convince your friends, team and boss that your project is exactly what the doctor ordered?

This template will provide the tools to setup simple, consistent and easily repeatable demo projects like those found on JBoss Demo Central.

Getting started with this template

1. Download and unzip.
2. Run init.sh to populate a project, see REAME files that are generated for how to use:

$ ./init.sh PROJECTNAME

This will fully populate a project directory with all you need to get started. Just add you project code, modify the init.{sh|bat} to your needs and launch your project.

Here is a sample run of when creating a new project:

$ ./init.sh newproject

Now you can start by adding your project sources to the projects directory and modifying the rest as needed.

Stay tuned for more in the JBoss Evangelist series.