Package, Test, Run your application

Wisdom’s build system is based on Apache Maven, so the build process is following the default Maven lifecycle.

Package your application

mvn package creates two files: a jar file containing your application, and a zip file containing the whole distribution, ready to be deployed.

Note
 The jar file is an OSGi bundle.

Adding libraries

To add a library to your application, just add a <dependency> in the pom.xml. Wisdom copies all dependencies from the compile scope (default Maven scope):

<dependency>
	<groupId>asm</groupId>
	<artifactId>asm-all</artifactId>
	<version>3.3.1</version>
</dependency>

However notice two important rules:

  1. It does not copy transitive dependencies, so don’t forget to declare all your dependencies.

  2. Only OSGi bundles are copied, so check that your dependencies are valid OSGi bundles.

Important
 Most libraries are OSGi bundles already.

Run tests

Tests are situated in the src/test/java directory.

mvn test executes all the unit tests following the Surefire convention. So, it executes all tests from classes starting or finishing by Test, such as MyClassTest or TestMyClass.

mvn integration-test executes all the integration tests following the Surefire convention. So, it executes all tests from classes starting or finishing by IT, such as MyComponentIT or ITMyComponent..

Watch mode

To run the application while developing, launch:

mvn wisdom:run

It packages your application and starts the Wisdom server. It also watches changes you make on your files and redeploys things automatically. For instance, if you edit a Java file, it compiles, packages and redeploys the application.

Warning
 Modifying the pom.xml file requires relaunching the watch mode.

The wisdom watch mode allows you to use a remote Wisdom server. Using this feature, you can watch several project at the same time. To enable this feature launch the watch mode with -DwisdomDirectory=location.

So, imagine you have two projects, P1 and P2, and P2 depends on P1. You want to enjoy the watch mode on both P1 and P2 projects, but, as P2 is your final / main project, you also want to immediately copy the P1 output to P2. In this context, just launch the watch mode twice as follows:

# P2 - regular watch mode (it starts the server we are going to use in P1)
mvn wisdom:run
# P1 - watch mode with remote server
mvn wisdom:run -DwisdomDirectory=../p2/target/wisdom
Tip
 Launch the main server first, if not, it may override the copied resources.
Warning
 When you launch the watch mode with the wisdomDirectory, some copy functionality is disabled (configuration and external resources). So in our previous example, modifying the P1 configuration, external resources, or templates do not copy them to P2. However, as P2 is launched without the parameter, all features are provided.

Debugging

In watch mode, you can enable the remote debugging by using the -Ddebug=port:

mvn wisdom:run -Ddebug=5005

Then, just launch the debug mode of your IDE using the set port (5005 in the previous example).

Run the application

The application is assembled in the target/wisdom directory. You can run it without the watch mode using:

./chameleon.sh

TIP:Why Chameleon? Because Chameleon is a kind of OSGi distribution with some additional features on which Wisdom relies.

Accessing the OSGi shell

If you are an OSGi expert and want to access the shell launch the application with:

./chameleon.sh --interactive

The provided shell is OW2 Shelbie.

The distribution

mvn package generates an OSGi bundle (a jar file) and a zip file. The jar file can be deployed into any other wisdom application. The zip file contains the whole distribution and can be run using the same shell script as previously explained.

Customizing applications packaging

Wisdom applications are packaged inside OSGi bundles. By default it:

  • includes all classes (from src/main/java) and resources (from src/main+resources)

  • imports all required packages (deduced by analyzing the classes)

  • exports all packages ending with service or services

However, sometimes you want to customize this default packaging policy. Wisdom relies on BND to build bundles. BND is building the OSGi bundle by following a set of instructions such as:

Import-Package: com.library.*; version = 1.21

To customize the bundle of your application, create a osgi.bnd file in src/main/osgi/, and write the BND instructions there.

For example, the Wisdom Hibernate Validation bundle has the following instructions:

Private-Package: org.wisdom.validation.hibernate;-split-package:=merge-first,  \
    org.jboss.logging.*, \
    com.fasterxml.classmate.*, \
    org.hibernate.validator*, \
    com.sun.el*, \
    javax.el*
Import-Package: javax.validation.*;version="[1.1.0,2.0.0)", \
                !org.apache.log4j, \
                org.jsoup*;resolution:=optional, \
                javax.persistence*;resolution:=optional, \
                org.jboss.logmanager*;resolution:=optional, \
                *
Export-Package: org.hibernate.validator.constraints*