DIF Tutorial - Creating the project structure

Back to Installing the SDK

Web projects are always a complex set of source files, scripts and resources files. Assembling correctly these elements usually requires some knowledge of the underlying framework and all the libraries they dependend on.

All who have done it know that this is not a trivial task. For a framework's proficient user it may become trivial (with lots of copy-pasting from previous projects), but for the majority of newcomers and green programmers this sure means trouble.

DIF2 is not without its share of complexity. Otherwise it would not be a rich and complete framework. But this inner complexity does not mean that it will have to present difficulties to the users.

For building a new project, as well as to execute many other project management tasks, we rely on Maven.

Maven provides a feature called archetype which is a project template for a specific case.

DIF2 has such a template, or Maven archetype. It is named "dif-webapp" and can be accessed through maven repositories like any other maven plugin.

Creating the project through Maven archetype

Setting up access to the Digitalis Maven Repository

At the moment, since the DIF framework's development is very active and SNAPSHOTs are delivered daily we have not yet deployed DIF's resources to the Central Maven Repository.

So to access them you'll need to configure your maven installation to access the Digitalis Maven Repository.

See this section on how to do it.

Creating the project

Our project will be named Surveys and will be part of the domain/group pt.digitalis.

To create the project all you need to do is type the following command on a command line/shell in the folder where you want to create the project:

mvn archetype:create
  -DarchetypeGroupId=pt.digitalis
  -DarchetypeArtifactId=dif-webapp
  -DarchetypeVersion=2.0.0-Beta1
  -DgroupId=pt.digitalis
  -DartifactId=surveys
If the process fails!

Maven has released a new major version of the maven-archetype-plugin. This new version (2.0-alpha) is buggy and does not read the settings.xml custom providers.

This results in Maven not finding the archetypes we provide since they are not present in Maven's default central repository.

To use the previous functioning version of the maven-archetype-plugin, use the following command instead:

mvn org.apache.maven.plugins:maven-archetype-plugin:1.0-alpha-7:create
  -DarchetypeGroupId=pt.digitalis
  -DarchetypeArtifactId=dif-webapp
  -DarchetypeVersion=2.0.0-Beta1
  -DgroupId=pt.digitalis
  -DartifactId=surveys

This will force the use of 1.0-alpha-7 version of the plugin. Witch is the last known functioning version.

Another workaround is to install the archetypes in your local repository.

Download the archetypes here

After downloading the file above unpack it into your maven local repository. Normally this is in your user home directory "~/.m2/reposotory".

Be warned that, even with the locally installed archetypes the process may fail. First tests with the last released 2.0-alpha-3 fail. It appears to be broken.

We strongly advice to keep away from the 2.0-alpha version for know. Use the 1.0-alpha-7 until the new version becomes stable.

Other options

There is another Maven archetype available. This one focused on web applications with a database backend required.

It's name is dif-webapp-ear.

This archetype creates a structured similar to the one above, but adds another module that uses the ORM Generator plugin to create the database ORM model.

This is very handy since it completely configures a default setup module that builds the model layer. All you have to do is specify witch database it will connect to and how your generated code will be organized.

See the ORM Generator project User Guide for instructions on how to do this.

What does the project template provide?

This will create the following project structure (it may change slightly over time):

.
|-- pom.xml
`-- src
    |-- main
    |   |-- java
    |   |   `-- pt
    |   |       `-- digitalis
    |   |           |-- entities
    |   |           |   |-- applications
    |   |           |   |   `-- SampleApplication.java
    |   |           |   |-- providers
    |   |           |   |   `-- SampleProvider.java
    |   |           |   |-- services
    |   |           |   |   `-- SampleService.java
    |   |           |   `-- stages
    |   |           |       `-- SampleStage.java
    |   |           `-- ioc
    |   |               |-- AppModule.java
    |   |               `-- EntityRegistrator.java
    |   |-- resources
    |   |   `-- modules.properties
    |   `-- webapp
    |       |-- WEB-INF
    |       |   `-- web.xml
    |       `-- sample.jsp
    `-- test
        `-- java
            `-- pt
                `-- digitalis
                    `-- SomeTest.java

This structure provides a Maven-managed DIF-based web project for you to work on.

It contains a sample stage implementation with its companion message file, view and parent service/app/provider entity classes. You will understand what these entities mean further ahead. For now it suffices to know that this is the structure of a DIF2 project, ready to build, deploy and run on any web server.

Integration with an IDE (Eclipse)

For simplicity we provide next the steps on how to integrate this project in the Eclipse IDE. (instructions on how to install it were given in the previous step of this tutorial)

After creating the project we need Maven to integrate it with Eclipse.

Simply place yourself in the project folder (where the pom.xml file is located) and type:

mvn eclipse:eclipse

After this you can import the project in Eclipse like any other eclipse project.

A few glitches in the process

It is not possible to include the Eclipse Maven Plugin configurations on the preceding step. So, when we open the project in Eclipse we will see several errors, all due to classpath issues.

We must now do the following:

  1. Active the Maven plugin for the project

    Right-click on the project and selecct: Maven -> Enable Dependency Management

  2. Parse the project and correct classpath and sources folder through Maven

    Right-click again and this time choose: Maven -> Update Source Folders

Advance to Application definition - What will we build?