Jolorun

Jolorun is a project that facilitates the start of Java EE 6 applications. It follows all the Java EE 6 specifications, as well as its profiles. Jolorun is like a two-sided coin.

First, it eliminates the ramp-up time when creating Java EE 6 applications. By using a GUI, a command line or an XML file, Jolorun generates the skeleton of your project with the specifications that you want. Need JSF + Stateless EJBs ? Swing + WebService ? JSF + Stateless + RESTful services ? Jolorun creates it all, with a defined directory structure, some business code, unit tests, a Maven project… ready to deploy and run on an application server and a database.

Second, it brings several business applications that you can use in your own projects. Do you want to add user/role management to your application ? Or the possibility to send an email ? Just let Jolorun know. Some ready-made applications are also available. Download the code, add some inspiration and create your own. By the way, if you want to develop an application with Jolorun, and want to give it to the Community in an open source manner, feel free to do so.

For the first version of Jolorun, the following business applications will be available :

• User management : a web application to manage users and roles
• Store : a web application that allows you to buy CDs and books
• TV Show : a web application showing your TV programs

News

FAQ

General

What is Jolorun ?

Jolorun is an open source project that has two sides :

1. Helps you to start-up a Java EE 6 project. Jolorun gives you a wizard to choose between the Java EE 6 specifications that your project needs and creates a directory skeleton with business and unit test classes, a Maven pom.xml file, all that up and running to an application server
2. Gives you a library of ready-made Java EE 6 projects. There are some ready-made projects that you can choose from, get the source, install and run. These projects all follow the Jolorun structure.

Is it a round-trip engineering tool ?

No, Jolorun is a one-shot, code generator.

What does Jolorun mean ?

In traditional Yoruba religion, Olorun is the creator of the universe. In the Java universe, Jolorun is the creator of Java EE 6 projects.

How is Jolorun related to AppFuse ?

AppFuse enables you to choose between several technologies to kick off a project. Jolorun allows you to choose between specifications, not technologies. It focuses on Java EE 6. For example, AppFuse allows you to choose between JSF and Struts, Hibernate and iBatis… Jolorun uses JSF and JPA.

Is Jolorun Open Source ?

Yes and it is developed under an Apache 2 license.

How can I contribute ?

There are several ways to contribute : adding code to Jolorun or developing new applications and giving them back to the Community.

Jolorun

In which programming language is Jolorun written ?

Groovy and Java. Groovy for the scripting and templating and Java for the end result (a Java EE 6 application).

What JDK version is needed to run Jolorun ?

Java SE 6 (JDK 1.6).

Does Jolorun use Spring ?

Jolorun doesn't use Spring, it uses the EJB 3.1 model instead.

Does Jolorun use Hibernate ?

Not exactly. Jolorun uses EclipseLink which is the JPA reference implementation. Because Hibernate implements JPA, Jolorun will allow you to choose implementations in the future.

Which version of Java EE does Jolorun support ?

Jolorun 6 supports Java EE 6. Jolorun 7 will support Java EE 7 and so on.

How does the versioning work ?

Jolorun uses a composed versioning number :

• Version of the Java EE specification it relates to
• A number with format : major.minor.revision

• Jolorun 6_0.1 : first beta version of Jolorun 6 (read Java EE 6)
• Jolorun 6_1.0 : first version of Jolorun 6
• Jolorun 6_11.2.4 : 11th version of Jolorun 6 with a second minor version and revision 4
• Jolorun 7_1.0 : first version of Jolorun 7

Which application server does it run on ?

At the moment GlassFish v3.

Why doesn't Jolorun use Log4j ?

The main idea of Jolorun is to use Java SE/Java EE specifications. To do this, Jolorun uses the java.logging.* package. Later, it's possible it may allow you to choose between the Java Logging API and Log4j but not at the moment.

Does Jolorun come with unit tests ?

Yes. In J2EE it was really difficult to unit test your code. With Java EE 6 it's very easy because most of the components are just Pojos. Unit testing these components has also become standard because there is now a standard API to interact (start, deploy, stop...) with application servers. JUnit classes are developed for each Jolorun project.

How do I compile my code ?

By using Maven and the command mvn install.

Can I use continuous integration ?

Yes. Thanks to Maven you can easily use tools such as Hudson or Bamboo.

Java EE 6

What is Java EE ?

Java Enterprise Edition or Java EE is a platform for server side programming. The Enterprise Edition (EE) differs from the Standard Edition (SE) of Java in that it adds libraries which provide functionality to deploy fault-tolerant, distributed, multi-tier Java software, based largely on modular components running on an application server.

What is profile ?

The Java EE 6 specification introduces the notion of profiles. A profile is a configuration of the Java EE platform, targeted at a specific class of applications. It is either a subset of the platform, or a superset of it. For example, the Web Profile is a subset of Java EE 6 specification and focuses on the web part (no JMS, no MDB, no Remote interfaces...).

Does Jolorun supports all the Java EE 6 specifications ?

Yes, at least many of the new ones. However, Jolorun does not support pruned specifications such as JAX-RPC or EJBs 2.x. Jolorun does support :

• JAX-WS 2.2 (Java API for XML-Based Web Services)
• JAXB 2.2 (Java Architecture for XML Binding)
• JAX-RS 1.0 (Java API for RESTful Web Services)
• JSF 2.0 (JavaServer Faces)
• JSP 2.2 (JavaServer Pages)
• Servlet 3.0
• Web Beans 1.0
• EJB 3.1 (Enterprise JavaBeans)
• JavaMail 1.4
• JMS 1.1 (Java Message Service)
• JPA 2.0 (Java Persistence API)

What does prunning mean ?

When a specification is marked as prunned, it means that it will disappear in its next version. For example, JAX-RPC and Entity Bean CMP 2.x are prunned in Java EE 6, they will then disappear from Java EE 7.

Can I unit test a Java EE 6 application ?

Yes, and in a standard way. Java EE 6 components (EJBs, Web Services, RESTful services...) are just Pojos and can be unit tested as is. Since Java EE 6, most of these components can be deployed into an embedded lightweight container (running on the same JVM that your unit tests) through a standard API.

Other

What is Maven ?

Maven is a software tool for Java project management and build automation.

What is Groovy ?

Groovy is a dynamic, object-oriented programming language for the Java Platform. It can also be used as a scripting language.

Road Map

Jolorun is a work in progress. Its first version will be available after the Java EE 6 specification is out. That means somewhere around Q1 2009.

Jolorun 6.0.1 : Q1 2009

• Possibility to create a project with Swing, JSF 2.0, Servlet 3.0, Web Beans 1.0, EJB 3.1, JPA 2.0, Web Services 2.0 and Rest Services 1.0
• Unit testing (JUnit and DBUnit)
• User and role management

Jolorun 6.0.2 : Q2 2009

• Add PMD/Checkstyle/findbug
• Choice of applications :
  • Store : a CD and book store
  • TV program : an application allowing you to check TV programs

Jolorun 6.0.3 : Q2 2009

• Java FX client
• Flex client
• Grails client
• Cluster aware

Jolorun 6.0.4 : Q3 2009

• i18n
• Choose between EclipseLink or Hibernate
• Add Oracle support
• Add PDF creation component

Jolorun 6.0.5 : Q3 2009

• add caching
• add captcha for loging

Contribute

There are two ways to contribute to Jolorun :

• Get involved in the project, report some bugs, provide some patches or commit some code.
• Give your application to the Community. Jolorun is an application start-up. Use it to develop your own business application. Then if you want, give your code to the Community. This way people will have the opportunity to download your code and use it.

Java EE 6

No, Java EE is not J2EE ! Java EE has suffered from its previous versions and some words have become evil. EJB for example. No matter how much easier EJB 3.1 is, it's still called an EJB and that has some bad memories because we remember Home/Remote interfaces, Bean classes with empty methods, XML files and JNDI lookups with narrowing, difficult to test… Another word issue is the Entity Bean. We all remember the Entity Bean 2.1 nightmare (heavyweight and overly complicated). JPA 2.0 has simplified the model and brings a huge power with it. JAX-RPC vs JAX-WS… and so on.

Compared to J2EE 1.4, Java EE 6 has a completely different flavor : reduced complexity, less XML file descriptors, less code, injection, coding by exception… Despite all these positive aspects, Java EE projects are not taking off. This is where Jolorun comes in the play; to show you how easy it is to develop an application with Java EE 6.

Don't believe it ? Well, nothing is better than a bit of code to convince you. Here's the code for a servlet that calls an EJB stateless that persists a Customer object into a database.

import javax.servlet.http.annotation.*;
import javax.ejb.*;

@Servlet(urlMappings={"/createcustomer"})
public class CustomerServlet {

    @EJB
    private CustomerService customerService;

    @GET
    public void handleGet(HttpServletRequest req, HttpServletResponse res) {
        Customer c = new Customer();
        c.setFirstname("Olodumare"); 
        c.setLastname("Olorun"); 
        c.setTelephone("666 777 888"); 
        c.setEmail("exu@yoruba.org"); 
        customerService.createCustomer(c);
    }
}

import javax.ejb.*;
import javax.persistence.*;

@Stateless
public class CustomerService  {

    @PersistenceContext(unitName = "jolorunPU")
    private EntityManager em;

    public Customer createCustomer(Customer customer) {
        em.persist(customer);
        return customer;
    }
}

import javax.persistence.*;

@Entity
public class Customer {

    @Id
    @GeneratedValue
    private Long id;
    private String firstname;
    private String lastname;
    private String telephone;
    private String email;

    public Customer() {
    }

    public Long getId() {return id;}

    public String getFirstname() {return firstname;}
    public void setFirstname(String firstname) {
      this.firstname = firstname;
    }

    public String getLastname() {return lastname;}
    public void setLastname(String lastname) {
        this.lastname = lastname;
    }

    public String getTelephone() {return telephone;}
    public void setTelephone(String telephone) {
        this.telephone = telephone;
    }

    public String getEmail() {return email;}

    public void setEmail(String email) {
        this.email = email;
    }
}

No local interface for the EJB, no ejb-jar.xml, no web.xml, no application.xml, no database mapping (just a persistence.xml file)… This same simplicity is used with Web Services, RESTful services, JSF and so on. Give it a try, ask Jolorun to create an application for you, customize it the way you want, check the code and make up your own mind. Java EE 6 is definitely the right platform if you want to develop a web or enterprise application.

TODO : unit testing class

Architecture

What is an architecture ? Wikipedia defines it as beeing the structure or structures of the system. What I like about this definition is the plural on structures.

Too many companies see the Architecture with a upper A instead of seeing architectureS with a upper S. It's dangerous to try to homogenise all the projects of a company into a single defined architecture. Each project is different, each project has it's own needs. If you need to develop a simple web administration console used by one person twice a week, JSPs + SQL statements are fine. You would loose time, money and effort trying to homogenise this application into a defined 3-tier architecture.

Java EE 6 is rich and simple enough to be used by any kind of application. Need simple ? Do simple ! Need rich ? Add layers and components.

Structure

Any architecture has one or many layers. Each layer has a certain amount of components that could be used.

• View : On the view layer, you can have any kind of graphical user interface. It goes from basic JSP, JSF pages or Swing. You could also think of others non-Java EE 6 technologies such as GWT, JavaFX or Flex
• Controller : Web controllers have been implemented through Servlets, but with JSF, a Managed Bean can also be seen as a controller
• Service : A service is a component that gives you a service. In Java EE 6 it is primarely a stateless session bean, but it's anything from a simple POJO, a Web Service, a Restful Service, a Stateful EJB, a Message driven bean...
• Domain : Layer of business classes.
• Database Access : For database access and Object/Relational mapping, JPA is the preferred persistent model in Java EE 6. But you can still use pure JDBC access or even DAOs.
• Interoperability : Your system can either use external services or expose a set of services.

JSP and JDBC application

Some people would call that a quick and dirty application. They might be right, but they also might be wrong. In certain cases you just need a set of JSP pages with direct database access using JDBC result sets. It can be used for prototyping, but also for some non-critical non-concurrent application.

A simple MVC Web application

If you don't want to use JSF for your web application, you still have the choice to use the good old MVC I model : JSPs talking to Servlets that use DAOs for accessing the database and POJOs as the model. Servlets also manage the flow of your application.

The preferred simple web application

To write a simple but robust web application in Java EE 6, nothing easier than JSF, EJBs and JPA.

A back-end Restful application

Distributed enterprise application

Getting Started Guide

TThe best way to get started with Jolorun is to create your first project. Jolorun has an advanced mode, but let's stick with the defaults to see how easy it is to create a Java EE 6 application.

First of all, download Jolorun, set the JOLORUN_HOME variable and add the $JOLORUN_HOME/bin directory to your path. To check if Jolorun is up and running, just type :

C:\> jolorun version
jolorun version 6.0.1

Create a project

Jolorun is now set up. To create a new project, just type jolorun create-project. A GUI editor will show up, asking you to provide some information :

• Project name : the name of your project
• Package name : the root package of your code
• Java EE 6 Profile : choose from web or enterprise profile
• Output source : the directory where you want your code generated (let's call it PROJECT_HOME)
• Application server : the target application server (choices are GlassFish V3)
• Clusterable : will the application be clustered ?
• Database : the database you want to store you data in (choices are Derby and MySQL)
• Database URL, user name and password

At any time you can click on the Help menu for information about each field and its effects on your project. For example, by clicking on Clusterable, the stateless bean layer will have a remote interface.

Click on Create project (that's all for now).

Browsing the source code

Now go to the output directory where the code was generated ($PROJECT_HOME). At the root you can see a Maven pom.xml file. This file allows you to compile, build your code, as well as run the tests.

The generated code follows Maven conventions, you'll find :

• $PROJECT_HOME/main/src/java : where the code of the application is. It is mostly structured in clientapp (a Swing application), webapp (a JSF web application), a layer of service, the data model, and some util classes.
• $PROJECT_HOME/test/src/java : where the unit test classes are (following the same structure).

Compile the code

Make sure that Maven is set up, open a command window and type $PROJECT_HOME> mvn install.

The compiled classes and the jar files are located under the $PROJECT_HOME/target directory. In this case Maven has created a MyProject.ear file.

Run the application

Make sure GlassFish V3 is installed, as well as Derby, and type mvn glassfish:deploy.

Use your browser to go to http://localhost/application_name

Advanced Guide

The power of Jolorun is that you can create a full Java EE 6 application very easily just by adding some information, and you can also customize it to fit your needs.

Create a customized project

As seen in the Getting Started Guide, you need to set up Jolorun and enter the jolorun create-project command line. This will pop up a form that will let you customize your application.

Complete all the basic information and, instead of creating your project by clicking on Create Project, click on >> to go to the next form. A second screen will show up.

Here you can select the client technologies you want to use and customize your EJB layer:

• Rich client : your application can have a JSF front end as well as a rich client one. That means Jolorun will generate a graphical user interface in Swing, Java FX or Flex that will communicate with the EJB service layer. When you choose to have a rich client, all the Remote check boxes are automatically checked.
• Web tier : if you need a web application, check the JSP and/or JSF boxes, you can then add :
  • WebBeans : uses WebBeans to glue JSF and EJB
  • Servlet : to have row Servlet 3.0
• EJB tier : select the kind of EJBs you want to have. Remember that in Java EE 6 local interfaces are optional.
  • Stateless EJBs : with local and/or remote interfaces
  • Stateful EJBs : with local and/or remote interfaces
  • Singleton EJBs : with local and/or remote interfaces
  • Timer service : generates an EJB using Timer Service
  • Interceptors : adds logging and audit interceptors to the EJBs
  • Asynchronous calls : if you need an EJB with asynchronous calls

On this screen you can add a messaging layer, web services or choose common components :

• JMS & MDB : will generate a JMS producer and an MDB as a consumer on Topics and/or Queues
• Web Services : will generate a WebService client and service
• RESTful service : will generate a REST client and service
• Common components that are part of Jolorun :
  • User management : for secured applications this allows to manage users and roles
  • Email : adds a component to send emails with JavaMail

Jolorun projects are described in an XML format. This XML is stored in the jolorun.xml file once you've clicked on Create Project (or if you use the File -> Save As menu). This file contains all the necessary information to create the same project again. This is very handy when you want to share project skeletons between teams and you want to use the command line. In this case just type the following command :

C:\> jolorun create-project -xml jolorun.xml
Project MyProject generated at C:\Tools\Project

At any time during the customization of your project, you can save the XML file, get some help or quit Jolorun user interface by using the menu.

User Guide

Jolorun command line

Jolorun uses a command line to perform several actions. Here is a list of possible parameters :

Developer Guide