Wisdom Framework

Wisdom is a lightweight framework enforcing a stateless, web-friendly architecture. It’s modular, and dynamic.

Wisdom is based on the NIO and asynchronous framework VertX. It is integrally built on top of OSGi, to enable modularity, and iPOJO, to make dynamism easy as pie.

With Wisdom, you web application is not monolithic anymore, but divided into a set of components deployable on the fly, and enabled / disabled dynamically, remotely or locally.

Wisdom proposes a very simple development model where you focus on your application logic and not on how things are working.

When developing an application, don’t spend you time to re-package and re-deploy your app. Save your files, hit refresh in your browser. Everything is done for you.

Wisdom relies on the Apache Maven build tool. Don’t run away. We made it very easy. It integrates everything you need from testing, to packaging and obviously natural continuous integration.

You may say: ‘well, what’s the difference with Grails or Play Framework’. Wisdom is intrinsically modular and dynamic. That means:

A full web stack for Java

Wisdom proposes a full web stack:

Wisdom runs on the Java Virtual Machine. Wisdom applications can run on any Cloud provider supporting Java.

We developed dozens of web applications in the past five years, using lots of different technologies: JavaEE, Grails, Lift, Play Framework (1 and 2), pure-JavaScript… We learned a lot from all these great frameworks, but for us, something was missing: the dynamism.

Our applications live in ever-changing (and expanding) environments, face ever-shifting (and increasing) demands, and must live up to ever-escalating expectations. As Niels Bohr said: “Prediction is very difficult, especially if it’s about the future”.

To face this situation, we need modularity and dynamism. Modularity to decompose applications into well-defined autonomous blocks, managed individually. Dynamism to manage the bindings between these components, their runtime environment and others services.

You don’t need to install anything ? The Wisdom build process will download everything.

Wisdom is based on the Apache Maven build tools. However don’t worry, Wisdom makes it easy. However, first, be sure you have Maven installed.

Once installed, you can create your first Wisdom project by launching:

On Windows use:

Once generated, you can already run your wisdom application. Navigate to the generated folder, and launch:

Then, open your browser to: http://localhost:9000.

That’s it you have your first Wisdom application.

This section is only for Maven users willing to use an archetype. The very same project can be generated using the wisdom-default-project-archetype:

The archetype can be used from your IDE to generate a new project directly.

The previous commands have generated a set of folders. Following the Maven conventions, all files are placed in the src directory, while the generated artifacts are in target.

The src/main directory is structured as follows:

The src/test directory contains the tests (unit and integration tests).

The generated application contains a controller. A controller is a Wisdom component containing actions, i.e. methods called using HTTP requests.

In the previous example, the controller is using a template (welcome), but things can be much simpler:

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

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

However notice two important rules:

Unfortunately, you may want to use a library that is not a bundle. When facing this situation, you have 3 choices:

You may want to check the bundles available on:

Unfortunately, not all libraries are OSGi bundles. Fortunately, Wisdom supports non-bundle dependencies. These dependencies are copied to the libs directory of the Wisdom server and are called libraries. These dependencies does not need to be OSGi bundles, and can be used by the Wisdom applications.

First add your Maven dependency as usual such as:

Then, you need to select explicitly the libraries from the set of dependencies. Only selected dependencies are copied. This selection is made as follows:

The libraries element configure the selection and behavior. It must contains an includes element with at least one include sub-element. If none are set, no dependencies are considered as libraries.

Using libraries allows you to rely on non-bundle dependencies, but it comes with a couple of limitations:

In other word, libraries are very useful when you can’t find a suitable OSGi bundle, but need to be used carefully to not break the modularity and dynamism of your applications.

If you want to create your own OSGi bundle, here are some rules:

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..

Unit tests are also executed in watch mode. It re-executes the unit tests when you change either a Java class or a test. By default, all test are re-executed. However, to reduce the amount of test, use:

With the SELECTIVE policy, only related tests are executed. Notice that, test failures are reported in the browser. You can skip tests adding the -DskipTests flag to the Maven command line.

To run the application while developing, launch:

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.

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:

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

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

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

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

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

The provided shell is OW2 Shelbie.

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.

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

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:

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:

When used, the osgi.bnd file is merged with the default instructions used by Wisdom (Import-Package, Export-Package (based on the package name), Private-Package, and Include-Resource). In other words, every instructions specified in the osgi.bnd replaces default value provided by Wisdom for this instruction. For example, if your osgi.bnd file contains Export-Package: my.package.to.be.exported, it won’t compute the default exported packages, but use your value (and only your value).

You can completely disable the Wisdom defaults, by adding the following instruction in the osgi.bnd file:

You can declare a set of (Maven) dependency to be packaged within the application bundle. The Wisdom Maven Plugin supports embedding of selected project dependencies inside the bundle by using the Embed-Dependency instruction:

where:

The plugin uses the Embed-Dependency instruction to transform the project dependencies into Include-Resource and Bundle-ClassPath clauses, which are then appended to the current set of instructions and passed onto BND.

Let’s see some examples:

Normally the plugin only checks direct dependencies, but this can be changed to include the complete set of transitive dependencies with the following option:

It can also be enabled using the transitive=true attribute.

By default, Wisdom compiles your code using Java 1.7. This convention was made to stick with the Maven convention. However you can override these settings by adding the following properties in your pom.xml:

You can add cfg file into the src/main/instances directory to add them to the wisdom/application directory. cfg files let you configure iPOJO instances (instantiation, configuration and reconfiguration). This directory is watched so changes are reflected immediately.

The file are filtered, so can rely on Maven properties.

The cfg file format is defined in the Configuration deployment section.

These files are packaged in the distribution but not in the bundle. So, if an application relies on a component requiring a specific instance configuration, this configuration need to be copied. If the configuration is static, you should use the @Configuration support of iPOJO.

The @Route annotation contains two attributes: the HTTP method and the URI pattern determining on which URLs the action is associated.

Let’s see a couple of examples:

The HTTP method can be any of the valid methods supported by HTTP (mainly GET, POST, PUT, DELETE). They are defined in org.wisdom.api.http.HttpMethod.

The URI pattern defines the route’s request path. Some parts of the request path can be dynamic.

Often the actions of one controller starts with a common prefix, such as /photos. To avoid the repetition, you can use the @Path annotation indicating the common prefix prepended to all uris from the @Route.

Action methods can receive parameters. Several types of parameters are supported:

All action method parameters must be annotated with one of the above annotations.

The action method parameter can be validated using the Bean Validation Annotations. It lets you express constraints on object models via annotations.

Here are some examples:

Thanks to these annotation, you don’t have to validate your parameter manually. If the constraints a violated, Wisdom returns a bad request JSON answer:

or

If for some reasons, the @Route annotation does not meet your requirements, you can override the routes() method. This method lets you define a set of routes. These routes are not prefixed by the @Path prefix, and can target other controllers.

Wisdom provides a RouteBuilder that lets you define Route easily.

Because there is no central location where routes are defined (as it breaks modularity), conflict may happen. Wisdom tries to detect them when the application is deployed, however, the detection algorithm is limited. We recommend using different prefixes (one per application) to avoid conflicts.

The Wisdom router is exposed as an OSGi service. Don’t worry it does not bite. Your controller can access it as follows:

The router lets you find routes by yourself, invoke them, check their parameters…​ In addition, it supports reverse routing.

The router can be used to generate a URL from within your code. Thus, refactoring is made easier.

Invoking the defined action returns:

Reverse routing can let you generate redirect results on actions you don’t know the url:

The result content type is automatically inferred from the value you specify in the body of the produced result.

For example, in:

Wisdom automatically sets the Content-Type header to text/plain, while in:

it sets the Content-Type header to application/json.

This is pretty useful, but sometimes you want to change it. Just use the as(newContentType) method on a result to create a new similar result with a different Content-Type header:

You can also use the methods html() and json() to set the content type respectively to HTML and JSON.

You can add (or update) any HTTP response header:

The previous action returns a result with the header set to the expected values:

Cookies are just a special form of HTTP headers, but Wisdom provides a set method to manipulate them easily. You can easily add a Cookie to the HTTP response:

Also, to discard a Cookie previously stored on the Web browser:

For a text-based HTTP response it is very important to handle the character encoding correctly. Wisdom handles that for you and uses UTF-8 by default. The encoding is used to both convert the text response to the corresponding bytes to send over the network socket, and to add the proper ;charset=xxx extension to the Content-Type header.

The encoding can be specified when you are generating the Result value:

Wisdom used to have a "highly sophisticated" in-build mechanism to encode response content. We now rely on the engine to handle this task. Thus all previously used annotations and configurations have been removed. This change has reduced the flexibility, but the benefits in performance justify it. Let us know if this feature was critical for you.

Wisdom can automatically encode response content according to the client Accept-Encoding header.

You can get the list of acceptable languages for a request using the request().languages() method that retrieves them from the Accept-Language header and sorts them according to their quality value. The return array of locale is sorted from the most 'wanted' language to the less 'wanted' one.

Similarly, the request().mediaTypes() method gives the list of acceptable result’s MIME types for a request. It retrieves them from the Accept request header and sorts them according to their quality factor.

The most preferred type can be retrieved using request().mediaType(). In addition, you can test if a given MIME type is acceptable for the current request using the request().accepts() method:

If you don’t specify the content type of your result, Wisdom tries to serialize your result to an ACCEPT-ed content type. For instance, in the following example, the result form depends on the ACCEPT header value of the request. If it’s application/json, result is serialized to JSON, if it’s application/xml, then the XML serializer is applied.

Each route can specifies the media type is accepts and the media types it produces. These metadata are used by the router to select the right route to invoke for a specific request.

The following snippet shows how routes can specify the media types it produces:

The route is selected according to the client’s ACCEPT header. If none matches, a NOT ACCEPTABLE result is returned.

Routes can also specify the mime types it can consume:

The route is selected according to the client’s CONTENT-TYPE header. If none matches, an UNSUPPORTED MEDIA TYPE result is returned.

Routes can combine both parameters and provides several values to each of them:

Notice that the accepts parameter can receive wildcards such as text/*.

Negotiation can become very complex if you have more than two possibilities. Fortunately, Wisdom provides helper methods to ease the development of action methods producing several results. The following example shows how to produce different types of results depending on the Accept HTTP header from the request.

Notice that the accept method generates a 406 response if the are no suitable possibilities.

Just to makes you understand how the template system works, you should read these small paragraphs.

Wisdom allows the integration of any template engine. By default, Thymeleaf is provided. Each template is exposed as a service and can be injected into a controller using the @View annotation. This pattern is used regardless of the template engine you use.

The View annotation is looking for a template with the specified name. It is equivalent to a regular @Requires with a filter.

Thymeleaf is an XML / XHTML / HTML5 template engine (extensible to other formats) that can work both in web and non-web environments. It is really well suited for serving XHTML/HTML5 at the view layer of web applications, but it can also process any XML file even in offline environments.

The main goal of Thymeleaf is to provide an elegant and well-formed way of creating templates. It allows you to create powerful natural templates, that can be correctly displayed by browsers and therefore work also as static prototypes. One of the main interests of Thymeleaf is a smooth collaboration with a Web Designer. By using specific attributes on HTML elements, you never interfere with the work of the web designers. They create the HTML page with whatever structure, and CSS tricks, and you just identify the parts where you inject the data.

It looks like this. As you can see, it’s a pretty straightforward syntax supporting all the features you expect from a template engine: variables, internationalization, iterations, layouts, fragments, object navigation, and much more.

The complete documentation of Thymeleaf is available here.

As in the Play Framework, Wisdom makes a distinction between the session and flash scope. If you have to keep data across multiple HTTP requests, you can save them in the Session or the Flash scope. Data stored in the Session is available during the whole user session, and data stored in the flash scope is only available to the next request.

It’s important to understand that Session and Flash data are not stored in the server but are added to each subsequent HTTP Request, using Cookies. This means that the data size is very limited (up to 4 KB) and that you can only store string values.

Cookies are signed with a secret key so the client can’t modify the cookie data (or it will be invalidated). The Wisdom session is not intended to be used as a cache. If you need to cache some data related to a specific session, you can use the Wisdom Cache Service and use the session to store a unique ID to associate the cached data with a specific user.

There is no technical timeout for the session, which expires when the user closes the web browser. If you need a functional timeout for a specific application, just store a timestamp into the user Session and use it however your application needs (e.g. for a maximum session duration, maximum inactivity duration, etc.).

You can retrieve the incoming Session from the HTTP request:

As the Session is just a Cookie, it is also just an HTTP header, but Wisdom provides a helper method to store a session value:

The same way, you can remove any value from the incoming session:

If you want to discard the whole session, there is special operation:

The Flash scope works exactly like the Session, but with two differences:

Here are a few examples using the Flash scope:

A JSON request is an HTTP request using a valid JSON payload as request body. Its Content-Type header must specify the text/json or application/json MIME type.

An action can retrieve the raw body content, or can ask Wisdom to convert it to an object, such as a JSON Node object in the following example:

Of course, it’s much better to use the @Body annotation:

In this example, the body is automatically mapped to a JsonNode. The @NotNull annotation manages the case where the body is empty. A bad request result will be sent back.

A third, even better, way to receive Json content is to use a validated bean/structure instead of a JsonNode:

The structure contains validation annotation, constraining the received data. For any non compliant content, a bad request will be returned. In addition, this way also accepts requests with other types of content (such as form input).

In our previous examples we handled requests with a JSON body, but replied with a text/plain response. Let’s change that to send back a valid JSON HTTP response:

Invoked with the {"name":"wisdom"} payload, the action returns:

However, building your own Json object can be very annoying and cumbersome. Fortunately, Wisdom builds a Json representation from an object:

Wisdom relies on Jackson to handle the JSON requests and responses. Despite the provided default serialization and de-serialization processes, you may need to extend it with your own mapping. Wisdom lets you extend Jackson by registering Jackson’s modules containing serializers and deserializers.

To achieve this, you have two ways:

JSON with Padding (JSONP) is a communication technique to request data from a server in a different domain, something prohibited by typical web browsers because of the same-origin policy. To use JSONP, the server must be able to generate a JSONP response, and you know what ? Wisdom knows how to do that.

Basically a JSONP response is a JavaScript code fragment structure as follows: padding({the data});. The padding is the name of the method (callback) that will be called in the JavaScript code having requested this response.

There are several ways to generate a JSONP response:

The previous snippet uses the first way to get a JSONP response. It builds a JSON Node and creates a JSONP result object. The mime type of the response is set to text/javascript. The previous code generates callback({"foo":"bar"});.

JSONP responses can be generated from the JSON service too:

The json.toJSONP method generates the JSONP response from the given callback name (padding) and the given content. This approach is convenient as you can map business objects into JSON directly (as shown in the second example). However it requires setting the JavaScript mime type explicitly.

Wisdom JSON feature relies on Jackson. You can enable or disable Jackson features from the application.conf file. Jackson features are listed on https://github.com/FasterXML/jackson-databind/wiki/JacksonFeatures. By default, the FAIL_ON_UNKNOWN_PROPERTIES is disabled.

Here is an example of configuration:

The standard way to upload files in a web application is to use a form with a special multipart/form-data encoding, which allows to mix standard form data with file attachments.

Start by writing an HTML form:

Now let’s define the upload action:

The uploaded file is accessed using the @Attribute("upload") FileItem uploaded. upload is the name of the field used in the upload form. From the file item, you can:

Another way to send files to the server is to use Ajax to upload files asynchronously from a form. In this case, the request body will not be encoded as multipart/form-data, but will just contain the plain file contents.

The context().getReader() method lets you access the raw content of the request. content().body() returns the raw content as a String.

Until now, we have been able to compute the result to send to the web client directly. This is not always the case: the result may depend on an expensive computation or on a long web service call.

Because of the way Wisdom works, action code must be as fast as possible (i.e. non blocking). So what should we return from our action if we are not yet able to compute the result? We should return an asynchronous result, i.e. a result that will be computed in the background and sent to the client when it’s done!

An asynchronous result will eventually be redeemed with a value of type Result. By using a AsyncResult instead of a normal Result, we are able to return from our action quickly without blocking anything. Wisdom will then serve the result as soon as the promise is redeemed.

The web client will be blocked while waiting for the response but nothing will be blocked on the server, and server resources can be used to serve other clients.

NOTE:*Why is it important to not block the server?* Wisdom is based on a NIO model and uses very few threads. Blocking one of them drastically reduces the velocity of the server.

To create an AsyncResult, you just need to write the heavy computation in a Callable<Result> object:

You can also use the @Async annotation to make a regular action method as an asynchronous method:

Since HTTP 1.1, to keep a single connection open to serve several HTTP requests and responses, the server must send the appropriate Content-Length HTTP header along with the response.

By default, when you send a simple result, such as:

You are not specifying a Content-Length header. Of course, because the content you are sending is well known, Wisdom is able to compute the content size for you and to generate the appropriate header.

Note that for text-based content this is not as simple as it looks, since the Content-Length header must be computed according the encoding used to translate characters to bytes.

To be able to compute the Content-Length header properly, Wisdom must consume the whole response data and load its content into memory. Obviously it has some drastic limitations.

If it’s not a problem to load the whole content into memory for simple content what about a large data set? Let’s say we want to send back a large file to the web client.

Wisdom provides methods to ease the manipulation of file:

Additionally this helper will also compute the Content-Type header from the file name.

If you want to force the browser to download the file (and not just display it), use the following version to set the Content-Disposition header.

When you passe true as second argument, Wisdom sets the Content-Disposition header to Content-Disposition: attachment; filename=wisdom.pdf.

Wisdom also supports serving urls directly. Handling URLs is a bit more complicated as the size in unknown, and so chunk transfer is required. Don’t worry Wisdom handles everything for you:

Serving URLs is useful when loading resources packaged with the application:

As for files, Wisdom tries to deduce the Content-Type from the URL. However, as shown, it can be overridden.

You can also return input streams directly. As for URLs, the content length is unknown and so it will be transferred chunk by chunk. Unlike URLs and Files, Wisdom does not try to determine the Content-Type so, you must set it explicitly:

If you don’t want to transfer the data using chunks, you can use the following variants:

WebSocket is a protocol providing full-duplex communication channels over a single TCP connection. The WebSocket protocol was standardized by the IETF as RFC 6455 in 2011, and the WebSocket API in Web IDL is being standardized by the W3C.

When a client (Browser) wants to establish a connection with a server using a web socket, it starts by a handshake. Once done, a tunnel connects the client and the server. So, the server can push data to the client and vice-versa. Such a mechanism paves the way to more reactive web applications, where notifications and up to date data are pushed to the client without having to rely on ajax or long polling.

WebSocket are identified using urls. These urls starts either by ws:// or wss://.

A controller willing to listen for data sent by clients on a specific web socket has to use the @onMessage annotation:

Every time a client sends data on ws:///localhost:9000/socket, the callback is called. Notice the @Body annotation parsing the message to the parameter’s type (here as String). The @Body annotation works the same way as in action methods:

The web socket URI provided in the @OnMessage annotation’s parameter can contain a dynamic part as for action methods:

The @Parameter annotation let you retrieve the dynamic parts.

Finally, you can identify the client sending the data using a special parameter named client:

Now that we can receive data from the client, it would be nice to push data to it.

Two important things here:

So, the previous snippet would produce such a kind of conversation:

The previous example sends data specifically to one client. However, data can be broadcast to all clients connected to a specific web socket:

The main difference is the usage of the publish method instead of send.

In addition to OnMessage, there are two other annotations useful to know when clients connect and disconnect from the listened socket:

@Opened and @Closed callbacks can also use URI with dynamic parts too. To retrieve the identifier of the client, just use @Parameter("client").

Wisdom proposes two types of interceptors:

Both filters and interceptors are services. Filters are services independent from the running application. They intercept all requests matching a regex (provided by the filter). On the other hand, interceptors are configured by the controllers. The set of interceptors called for an action is specified by the action itself or by the controller using the annotations bound to interceptors. When several interceptors are declared, a chain is computed and is called sequentially:

Both filters and interceptors are enqueued in the interception chain. Filters are executed first, and then interceptors. When several filters match the incoming requests, the order is determined using their priority (highest first).

Filters can intercept unbound requests, i.e. requests that do not have a matching action method, or all actions having thrown an exception. Such interceptions are not feasible using interceptors.

A filter is a component implementing org.wisdom.api.interception.Filter and exposing it as a service. Here is an example of a filter measuring the time spent to compute the response to a request:

The call method is the method intercepting the request. It should, in the very high majority of the cases, call the proceed method to continue the chain. If it does not, the chain is cut, and no other filters or interceptors will be called.

The uri method returns the regex selecting the intercepted urls. In the example, all requests pointing to "/documentation" are intercepted.

The priority method allows configuring the position of the filters in the chain if there are several matching filters. Filters with the highest priorities are first. Notice that the default error page filter from Wisdom (displaying the error pages and route not found pages) has a priority of 1000.

Filters can come and go at anytime, promoting a very dynamic model. So, you can intercept requests targeting controllers not developed by you (such as the asset controller), or deploy a temporary filter to understand a specific issue.

Developing an interceptor requires an annotation and the interceptor itself. Interceptors are configured using an annotation bound to the interceptor. This annotation uses the @Interception meta-annotation specifying that an interceptor is consuming the annotation:

The previous snippet shows an interceptor annotation that will be handled by an interceptor. The annotation must be visible at runtime, and can target both types and methods (this means they can be used either on classes or on methods).

Interceptors are Wisdom components registered as OSGi services. Don’t worry, Wisdom makes that easy:

First, the class is annotated with three annotations:

This instructs the framework to expose the OSGi service.

Then, the class contains two main methods:

The annotation method is straightforward. It just returns the class of the handled annotation.

The call method is intercepting the action invocation. It invokes the context.proceed() method to call the next interceptor. It can also return a Result object immediately, shortcutting the chain. The call method receives the RequestContext object and the actual interceptor configuration. The RequestContext let the interceptor to:

As said, interceptor annotation can target either classes or methods:

Filters and interceptors can share data when they are on the same chain (i.e. intercepting the same request). The RequestContext object hold the shared data:

This data can be consumed by the filters and interceptors invoked after the entity having set the data.

We strongly recommend that you use the following conventions to organize your assets:

The assets from src/main/resources/assets are packaged in the application’s jar file (don’t forget it’s an OSGi bundle).The assets from src/main/assets are placed in the wisdom/assets directory and packaged in the distribution zip file. Despite this difference, both types of assets are accessible from the /assets/ path.

Let’s see some examples:

Wisdom contains a built-in controller to serve the assets. By default, this controller provides caching, ETag, and gzip compression.

The Assets controller automatically manages ETag HTTP Headers. The ETag value is generated from the file’s last modification date. (If the resource file is embedded into a file, the JAR file’s last modification date is used.)

When a web browser makes a request specifying this Etag, the server can respond with 304 NotModified, without body. By this method, bandwidth is saved.

You can disable the Etag support by setting http.useETag to false in the application configuration:

By default, Etag is enabled.

In addition to the Etag support, Wisdom lets you configure the asset cache time. More precisely the value set by Wisdom in the Cache-Control HTTP header. By setting the http.cache_control_max_age configuration property in the application configuration, you can set the amount of time (in seconds) the browser can keep the resource in its own cache:

To disable the cache, set this value to 0:

This configuration instructs Wisdom to use the no-cache value, forbidding the browser and other proxies to use caching facilities.

By default, the cache age is set to 3600 seconds.

Before being packaged, assets are processed. For example, CoffeeScript files are compiled to JavaScript, while Less files are compiled to CSS. This processing is done during the build process (and not at runtime).

CoffeeScript is a little language that compiles into JavaScript. Underneath that awkward Java-esque patina, JavaScript has always had a gorgeous heart. CoffeeScript is an attempt to expose the good parts of JavaScript in a simple way. Any .coffee files from your assets are compiled to Javascript automatically. The source map is also generated. For example, the file src/main/assets/javascripts/some-coffee.coffee:

is accessible from /assets/javascripts/some-coffee.js:

The CoffeeScript compilation relies on the original compiler executed on top of the node.js runtime.

TypeScript lets you write JavaScript the way you really want to. TypeScript is a typed superset of JavaScript that compiles to plain JavaScript.

Any .ts files from your assets are compiled to Javascript automatically. The source maps are also generated. For example, the file src/main/assets/typescript/Animal.ts:

is accessible from /assets/javascripts/Animal.js:

The TypeScript compilation relies on the original compiler executed on top of the node.js runtime. The compilation process is configured from the typescript element in your pom.xml file such as:

Are supported:

LESS extends CSS with dynamic behavior such as variables, mixins, operations and functions. Wisdom automatically compiles any .less files from your assets to CSS. For example, the file src/main/assets/stylesheets/site.less:

is accessible from /assets/stylesheets/site.css:

The Less version compilation relies on the original less compiler executed on top of the node.js runtime.

Wisdom integrates Clean-CSS to aggregate and minify stylesheets. By default, it minifies all .css file into a -min.css file. However this behavior can be configured to aggregate the files and minify the result.

In your pom.xml, in the wisdom-maven-plugin configuration section, add:

The stylesheets element let you configure the aggregation and minification. You can have several aggregation element under the aggregations element. Each aggregation must list the set of files it aggregates. Only internal assets (i.e. from src/main/resources/assets) can be aggregated. Each files is looked up from the target/classes/assets directory (containing the compiles assets). The extension can be omitted (for example, style instead of style.css). The aggregation can optionally defined the output file, also related to target/classes/assets. By default it builds the name as follows: artifactid-min.css (or just artifactid.css if minification is disabled).

Aggregation also supports a removeIncludedFiles attribute (disabled by default) to remove the individual aggregated files after processing.

If you don’t want to list all the file one by one, you can use FileSets instead of <files>:

Be aware that wildcards can introduce ordering issue as the order of the selected files may depend on the file system you are using.

Using a file set let you exclude files too, as well as set the base directory. By default, the directory is the location of internal assets (target/classes/assets):

Wisdom integrates Google Closure to check, aggregate and minify JavaScript files. For any JavaScript file (even the one generated by the CoffeeScript compiler), a minified version is generated. The minified file name ends with -min.js. For example, my-script.js will be minified into my-script-min.js.

To use the minified version, add the -min suffix to your script tags in your templates or HTML files.

You can configure the optimization level of the Closure Compiler and the pretty print option from your pom.xml file:

The value of the compilation level can be WHITESPACE_ONLY (default), SIMPLE_OPTIMIZATIONS or ADVANCED_OPTIMIZATIONS.

The pretty print option lets you configure how the minified file is formatted . Enabling pretty print impacts the final file size but is much more readable.

Aggregation is configured inside the <javascript> element:

You can have several aggregation element under the aggregations element. Each aggregation must list the set of files it aggregates. Only internal assets (i.e. from src/main/resources/assets) can be aggregated. Each files is looked up from the target/classes/assets directory (containing the compiles assets). The extension can be omitted (for example, coffee/math instead of coffee/math.js). The aggregation can optionally defined the output file, also related to target/classes/assets. By default it builds the name as follows: artifactid-min.js.

Aggregation also supports a removeIncludedFiles attribute (disabled by default) to remove the individual aggregated files after processing.

If you don’t want to list all the file one by one, you can use FileSets instead of <files>:

Be aware that wildcards can introduce ordering issue as the order of the selected files may depend on the file system you are using.

Using a file set let you exclude files too, as well as set the base directory. By default, the directory is the location of internal assets (target/classes/assets):

You can also disable the Google Closure support with:

In watch mode, you can disable Google Closure support with: mvn wisdom:run -DskipGoogleClosure=true

Images from your assets are automatically optimize to reduce their sizes. The optimization uses ImageMin and process jpg, png, gif and svg.

You can skip the image optimization using <skipImageOptimization>true</skipImageOptimization> or in the command line using -DskipImageOptimization=true.

You can configure the optimization using the <imageMinification> element in your pom.xml file:

The internal assets from your project can be packaged into a webjar. This WebJar will contained the process versions of your assets and has a structure conform to the webjar specification. WebJars are really useful to share assets.

WebJar packaging is disabled by default, but can be easily enabled using:

By default, all the internal resources of your project are packaged into a webjar. This webjar use the project’s artifact id as name, and project’s version as version. The created artifact use the webjar classifier.

The webjar can be customized using the webjar element in the pom.xml file:

You extend the location where Wisdom is looking for assets.

First create the src/main/instances directory and add the following snippet to your pom.xml file:

Then create a org.wisdom.resources.AssetController-A_NAME.cfg in the instances directory you just created. Change A_NAME by an identifier that you can understand. In this file you can set:

Let’s see two examples. In this first example, it extends assets locations with an in bundle lookup looking for assets in the /interns directory (inside the jar file). These assets are served from the /internal url. As the path property is not set, it does not support assets located on the file system.

This second example extends the asset lookup with an external location (public) served from the /public url:

Web Jars are plain Jars embedding web assets (such as javascript and css files). The list of WebJars is listed on http://www.webjars.org/.

Search for the library you need and copy the dependency to your project pom file. For example, to use jquery, add:

When building your Wisdom project, it unpacks your dependencies to wisdom/assets/libs. So you can quickly check what files are available, the different libraries and their versions.

Assets embedded in Web Jars are available under "/libs". Let’s see some examples:

The path to the file depends on how the library is structured.

You can also specify the library name to be sure you get the file from the right library (useful when file names conflict):

Finally, you can also use the library name and version, to be even more specific:

The cache is available as a service, so accessible using:

Using this simple API you can store data in the cache:

You can retrieve the data later:

To remove an item from the cache use the remove method:

You can easily create an augmented cached action using standard action interception. Wisdom provides a default built-in interceptor for the standard case:

If you provide your own implementation of the Cache service, you may want to disabled the ehcache implementation. To achieve this, add the following snippet to your application.conf:

The first step is to implement a service checking if the current session is 'authenticated'. Such a class must implement the Authenticator interface.

The following snippet is a basic implementation checking if the property username is contained in the session ( and if it’s 'admin'):

The implementation provides three methods:

Once you have your authenticator service, you can annotate your action method or controller (this is equivalent to annotating all methods) with the @Authenticated annotation:

Once annotated, access to your method invokes the authenticator service to check if the current context / session / request is 'authenticated'. If not the onUnauthorized method is called and its result is used as the response.

You can have several authenticator services at the same time. To select the authenticator to use:

The 'id' is the String returned by the getName() method. If the specified authenticator is not available, an unauthorized response is returned.

Wisdom lets you externalize your messages by creating properties files (containing your messages as explained on this page) in the src/main/resources/i18n folder. The name of the file lets you configure the locale/languages of the messages contained in the file. Let’s see some examples:

The default locale (empty locale) is used when there is no locale matching the request. Generally we use this locale for English messages (but you can configure it using the application.locale property in the application.conf file).

You can retrieve messages using the org.wisdom.api.i18n.InternationalizationService service:

Notice that you need to specify the language explicitly.

HTTP Requests can specify the expected languages using the Accept-Language header. Wisdom parses this header and lets you provide the messages in the most suitable language.

To retrieve the messages using the request accepted languages, just use:

Wisdom determines what’s the best language to use for the request. For example, for a request specifying an Accept-Language with en-US,en;q=0.8,de;q=0.6,fr;q=0.4, Wisdom tries to provide the message in American English, then English, then German, then French. If none of them are provided, the default locale is used.

Using internationalized messages in a template is pretty simple. It relies on the Thymeleaf syntax:

A utext instructs Wisdom to use an internationalized message specified using #{key}. For example, the following template uses two internationalized messages:

Notice that the second message is parameterized.

Messages can be formatted using the java.text.MessageFormat format. For example, if you have defined a message like this:

You can then specify parameters as:

The internationalization service can be requested using simple HTTP Requests to retrieve the messages. This lets you retrieve the messages from a JavaScript client or anything able to emit a HTTP GET request.

Except if specified otherwise, Wisdom computes the language to use according to the request (so according to the ACCEPT-LANGUAGE header). When retrieving all messages, the JSON structure is composed as follows:

To use the JQuery i18n Properties Plugin, just use the last URL form: http://localhost:9000/bundles/Messages_fr.properties:

jQuery.i18n.properties({ name:'Messages', path:'/i18n/bundles/', mode:'both', language:'fr', callback: function() { // We specified mode: 'both' so translated values will be // available as JS vars/functions and as a map

Wisdom also provide the support of i18next.

var option = { resGetPath: '/i18n/bundles/messages.json?locales=lng', dynamicLoad: true }; i18n.init(option, function(t) { // translate nav $(".translation").i18n();

}); ---

The internationalization support computes ETAG based on the latest modifications of the message for a specific locale. That means that requests to retrieve resource bundles (JQuery i18n plugin), messages as JSON format (i18next) and the list of all messages (/i18n) support client side caching. == Application configuration

Wisdom configuration system uses the HOCON syntax. This section presents a brief introduction to HOCON and how you application can read its configuration from the application.conf file.

the application.conf file contains all the configuration data. In your project it’s located in the src/main/configuration directory. At runtime, this file is copied to the conf directory.

HOCON stands for "Human-Optimized Config Object Notation". It’s a easy to read, structured syntax that avoid some of the ambiguity of the Java Properties files.

Instead of explaining in details what HOCON is, let’s look at some examples:

This first example introduces the "structure" syntax using "{}". As you can see, HOCON is very close to JSON. To retrieve a property, you can use`path` such as:

HOCON also support the "Flat" format:

However, be aware that it’s not compatible with the Java Properties format, even if it’s very close. Differences are mostly about quoted / unquoted values:

HOCON supports substitution:

It also supports includes

That’s mostly all you need to know about HOCON.

Your application can retrieve the configuration using the org.wisdom.api.configuration.ApplicationConfiguration service. Let’s look at a sample.

Let’s imagine we have the following configuration in the application.conf file:

To retrieve the "my value" data, just require the ApplicationConfiguration file and retrieve the data:

There are other useful methods you can use:

By default, when an exception is thrown by a controller, an internal server error is returned to the client (status 500). If the request accepts HTML and if the error template is available, the exception is presented as a web page.

org.wisdom.api.exceptions.HttpException lets us customize the error returned when such an exception is thrown. When a controller throws an exception of type org.wisdom.api.exceptions.HttpException (or a subclass of it), a specific result is built and returned to the client.

In other cases it may not be appropriate to throw instances of HttpException, or classes that extend HttpException, and instead it may be preferable to map an existing exception to a result. For such cases it is possible to use a custom exception mapping provider. The provider must implement the ExceptionMapper<E extends Exception> interface and exposes it as a service.

The above class is annotated with @Service, so it will be exposed as an OSGi service. When an application throws an NoSuchElementException the toResult method of the NoSuchElementExceptionMapper instance will be invoked.

The unit test support lets you write Junit tests to check the behavior of your classes. These tests cases are written in Java classes in the src/test/java folder. Notice that test case classes must start or end with Test (this is a Surefire convention).

Unit tests should extend the WisdomUnitTest class to access utility methods.

The first test is a really simple test just checking that 1+1=2. Notice the AssertJ syntax.

The second test checks the behavior of one of your action methods. As your action method can access the HTTP method, the call is wrapped into an Invocation call:

Such a pattern lets you call your action directly, and retrieve the HTTP result. You can also configure the HTTP headers, parameters, form attributes, cookies, session…​. The chain must end with invoke()

The ActionResult contains the HTTP Context (that may have been modified by your action method, and the HTTP result.

In-container tests let you check the behavior of your controller and services running in the server. The server is automatically launched. These tests cases are written in Java classes in the src/test/java folder. Notice that test case classes must start or end with "IT" (this is a Surefire/Failsafe convention).

In-container tests must extend WisdomTest, and follow the same rules as unit tests. However, @Inject annotated fields are injected.

The @Inject annotation lets you access the real instance of your controller, service or template:

Once injected your test can invoke them either directly or in an invocation block to configure the HTTP context.

Black box tests are emitting HTTP requests and retrieving the result. Such tests are not executed in the server. Your application is deployed within the server (it reuses the launched one by in-container tests if it’s already running).

As for in-container tests, a black box test class must start or end with "IT". These classes must extend org.wisdom.test.parents.WisdomBlackBoxTest.

The test API lets you emit any type of HTTP requests and configure headers, payload, cookies…​ In addition, the response can be smoothly wrapped to Json Node, HTML Document (JSoup), String, or input stream.

If your blackbox test requires controllers or services from your test sources (i.e. located in the src/test/java directory), you need to use @BeforeClass and @AfterClass as follows:

Notice that the methods have to be static. The invoked bundles are located in org.wisdom.test.parents .WisdomBlackBoxTest.

UI Tests are loading pages using a browser and check the elements present on the page. Wisdom uses FluentLenium to ease the implementation of UI tests.

As for in-container tests, UI test classes must start or end with "IT". These classes must extend org.wisdom.test.parents.WisdomFluentLeniumTest.

You can select the browser to use by setting the -Dfluentlenium.browser property in the command line. Accepted values are firefox, chrome, ie (Internet Explorer) and safari. If not set it uses the HTML Unit Browser (Fluentlenium’s default) relying on Firefox.

Notice that depending on the browser you choose you may have to install additional software or specify addition values. Check the following links:

When building a Maven multi-module project, the same instance of the server is used for all your tests. This can be annoying. Fortunately, Wisdom provides a test listener to stop the instance once the module build is completed:

The previous configuration is automatically generated when creating a new project.

To test your JavaScript code, Wisdom integrates Karma, a test runner executing the code in a real or emulated browser . Karma test can be executed either during the test phase, or during the integration-test phase. In both case you need a Karma configuration file located in the src/test/javascript directory, in which your JavaScript tests will also be.

Karma relies on a set of plugins that you must configure from your pom.xml file:

This list indicates the name of the plugin and its version (optional).

To build a distribution of your application just use: mvn clean package. A distribution containing the Wisdom runtime, the application dependencies and external assets are created in the target folder as a zip file. Wisdom application deployment is based on this distribution file.

First, unzip the distribution file anywhere. Be aware that the zip file does not include a base directory. To launch a Wisdom application in background, just use the chameleon.sh script provided at the root of the unzipped location:

Stopping is quite similar:

To avoid the output on the console, use:

By default the logged messages are written in logs/wisdom.log.

You can specify any JVM arguments to the JVM_ARGS system variable. Otherwise the default JVM settings will be used:

The default is to load the conf/application.conf file. You can specify an alternative configuration file if needed:

This section explains how to create a system service starting and stopping your application when the machine boots and shutsdown.

The service script used to manage a Wisdom application is very basic and relies on the chameleon.sh script. In addition, most of the configuration is similar to most Wisdom applications. This script can be downloaded from here.

In this script, you must configure some variables:

Once edited, copy the script file to /etc/init.d. Then add the execution flag with chmod +x /etc/init .d/filename. Add the script to the boot and shutdown sequence using: chkconfig --add /etc/init.d/filename. Finally, enable the configuration with chkconfig filename on. So, if your file is named wisdom, the sequence of instructions is the following:

Once done, start the service using /etc/init.d/wisdom start. The service can be stopped using /etc/init.d/wisdom stop.

This example shows you how to configure lighttpd as a front end web server. Note that you can do the same with Apache, but if you only need virtual hosting or load balancing, lighttpd is a very good choice and much easier to configure!

The /etc/lighttpd/lighttpd.conf file should define things like this:

This example shows you how to configure nginx as a front end web server. Note that you can do the same with Apache, but if you only need virtual hosting or load balancing, nginx is a very good choice and much easier to configure!

The /etc/nginx/nginx.conf file should define things like this:

Note Make sure you are using version 1.2 or greater of Nginx otherwise chunked responses won’t work properly.

The example below shows a simple set up with Apache httpd server running in front of a standard Wisdom configuration.

When using an HTTP frontal server, request addresses are seen as coming from the HTTP server. In a usual set-up, where you both have the Wisdom app and the proxy running on the same machine, the Wisdom app will see the requests coming from 127.0.0.1.

Proxy servers can add a specific header to the request to tell the proxied application where the request came from. Most web servers will add an X-Forwarded-For header with the remote client IP address as first argument. If the proxy server is running on localhost and connecting from 127.0.0.1, Wisdom trusts its X-Forwarded-For header. If you are running a reverse proxy on a different machine, you can set the trustxforwarded configuration item to true in the application configuration file, like so:

However, the host header is untouched, it’ll remain issued by the proxy. If you use Apache 2.x, you can add a directive like:

The host: header will be the original host request header issued by the client. By combining theses two techniques, your app will appear to be directly exposed.

If you don’t want this Wisdom app to occupy the whole root, add an exclusion directive to the proxy config (for Apache):

By default, Wisdom generates itself a self signed certificate, however typically this will not be suitable for serving a website in production. Wisdom uses Java key stores to configure SSL certificates and keys.

Signing authorities often provide instructions on how to create a Java keystore (typically with reference to Tomcat configuration). The official Oracle documentation on how to generate keystores using the JDK keytool utility can be found here.

Having created your keystore, the following system properties can be used to configure Wisdom to use it:

Paths are either relative to the server root or absolute.

If https.trustStore if set to noCA, all host are trusted. Be aware to not use this configuration in production.

To disable binding on the HTTP port, set the http.port system property to be -1, eg:

The http.port property can also be written in the application configuration file, and as a consequence, HTTP can be disabled from the application configuration file.

Usually you want to use different logging settings when running in test, dev or on production. The best way to configure Logback is to follow the excellent guide at: http://logback.qos.ch/manual/configuration.html.

There are two main ways how you can configure Logback.

By default Logback will look for a file called logger.xml in the conf directory of your application. Wisdom provides a default logging configuration generated into src/main/configuration.

Logback evaluates a Java system property named logback.configurationFile. This approach is handy when you launch your application in a service file, or a script:

This allows you to use one logging configuration for all your instances. More about that approach here: http://logback.qos.ch/manual/configuration.html.

JUL is the standard logging API provided in Java. You can use JUL logger without requiring any other configuration or additional bundles. JUL loggers are redirected to logback, so messages are written in the logback logs:

Apache Commons Logging is a Log API provided by Apache (http://commons.apache.org/proper/commons-logging/). To transfer the logged entry from commons-logging to logback, you need to deploy the jcl-over-slf4j bundle. Adding the following dependency adds the bundle:

Then, calls to commons-logging is redirected to slf4j and backed using logback:

Apache Log4J is another Log API from Apache (http://logging.apache.org/log4j). As for Apache Commons Logging, Log4J requires an additionnal bundle:

Then, calls to commons-logging is redirected to slf4j and backed using logback:

The complete API of the crypto service is available here

The crypto service can be configured from the application.conf file:

As said above, the validator service is based on Bean Validation 1.1. So it’s API is the Bean Validation API. The main entry point is the Validator service that lets you validate beans or parameters. The Hibernate Validation documentation provides everything you need to know about the usage of the validator.

You can retrieve the Validator service as follows:

The Bean Validation specification defines a set of constraints defined in the javax .validation.constraints package:

The default implementation of the validation service uses Hibernate Bean Validation and proposes additional useful constraints. To have accessed to them you need to add the following dependency to your pom.xml file:

These additional constraints are:

If the set of provided constraints is not enough, you can create your own constraints and validators. To implement such custom constraints, follow the Bean Validation guide. However you should:

Constraints define a message. If this message is wrapped into {}, it is interpreted as a message key and the value is looked into the internationalization service (Check Internationalize your application for more details) as in:

Then the message is looked into the resource bundles:

So, Wisdom is picking the right message according to the request languages (passed into the ACCEPT_LANGUAGE header). As you can see, messages can use variables to make the error more informative. For instance, in English the message is The name 'ts' must contain between 4 and 8 characters, while on a browser using the French language, the message is Le nom 'ts' doit contenir entre 4 et 8 caractères. If the asked language is not available, default (english) is used.

By default, Wisdom has a system pool you can use to run backend / asynchronous tasks. Be aware that Wisdom is relying on it, so, it you plan to submit lots of jobs, you should create your own executor (see below).

Once injected, using the service is very straightforward:

As the system executor, the system scheduler is available as a service. Using it is straightforward:

The configuration of the system executor and scheduler is made from the application.conf file:

The values written above are the default values.

You can create another executor or scheduler by adding its configuration in the application.conf file:

Once configured, you can retrieve them using:

As said above, once of the main difference with the 'regular' Java execution service is the type of future returned by the different methods. Wisdom enhanced the regular feature with administration methods as well as callbacks.

Each executor and schedulers has a 'hung threshold' allowing to detect hung task. The executor or scheduler do not do anything when a hung task is detected. It’s a only for monitoring and administration support.

To retrieve the hung tasks use: executor.getHungTasks(). You can also check on the future returned on submission.

When submitting a task, Wisdom retrieve all org.wisdom.api.concurrent.ExecutionContextService services to build an org.wisdom.api.concurrent.ExecutionContext. This context is captured during the submission (in the caller threads), and applied before the execution of the task. After its completion, the context is un-applied. This mechanism let you migrate data that are thread-sensitive to the thread that is going to execute a task.

You can implement your own org.wisdom.api.concurrent.ExecutionContextService to extend this support.

The Vertx Event Bus is exposed as an OSGi service. To access it, you first need to add the following dependency to your pom.xml file:

Once done, you can access the Event Bus as following:

Once you access the event bus you can send and publish data:

You can also register a handler to receive data transmitted through the bus:

Vertx support distributed Event Bus, and so the creation of clustered configurations. The cluster is managed using Hazelcast, an In-Memory Data Grid is data management software. So, events sent to the event bus can be received by receivers running on a remote machine.

To enable the clustering you first need to configure Vertx. Edit the src/main/configuration/application.conf file and add:

Once done, create the src/main/configuration/cluster.xml containing the Hazelcast configuration. Copy and edit this file is a good start.

When clustering is enabled, you will see a stack trace on startup. Just ignore it:

Vertx is also used as network stack by Wisdom, so you can configure various aspects of HTTP handling and also declare several servers.

The following example depicts how to configure the different aspect of HTTP:

You can also disable the defaults HTTP servers and provides your own:

With such mechanism you can configure as many HTTP server you want with different port, security level and allow/deny policies. These policies are checked for HTTP request and websockets. In the case of HTTP requests if the request is denied, it can either return a FORBIDDEN result or redirect the request to the onDenied url. For websockets the denied messages are just ignored. By default, everything is allowed.

The host value specify on which host / network interface the server is bound. By default all interfaces are bound ("0.0.0.0").

The ssl flag enables or disables HTTPS. The authentication lets you specify whether or not the server require client mutual authentication (see http://docs.oracle.com/cd/E19226-01/820-7627/bncbs/index.html).

The vert.x response encoding (compression) is made for all response having a size between the encoding.max and encoding.min configuration keys (size in bytes such as 1Kb).

By default, Vertx uses a limited number of threads, the number of processor you have. You can configure this number by setting the vertx.pool.eventloop.size system property, or by setting it in the application.conf file:

We are often asked why we want a Watch Mode based on Maven, and not something separated, as most of frameworks do. This is because duplicating the build process creates a strange experience. The result looks the same, but it may not really be the same. Debugging such kind of differences is almost impossible. So in Wisdom, Maven is the reference and the Watch Mode is built on top of it. During the Watch Mode, Wisdom invokes the Maven Mojos directly.

This also means that using your Wisdom Build extension is just like using any other Maven plugin: * add the plugin in the pom.xml file * configure it * you’re done!

The Wisdom Watch Mode is based on the concept of Watcher. A Watcher is an object who is notified when a file, accepted by the watcher, is created, updated or deleted.

So, first, in your Mojo’s project, add the dependency on the Wisdom-Maven-Plugin:

To make your Mojo participate in the Wisdom Watch Mode, it needs to become a Watcher and registers itself in the watch pipeline. In order to do that, the easiest way is to make your Mojo extend AbstractWisdomWatcherMojo instead of AbstractMojo.

By extending AbstractWisdomWatcherMojo, it automatically registers your Mojo to the Pipeline.

As a Watcher your mojo has to implement the following methods:

The accept method let you select the file the watcher handles. For instance, if you want to handle .css files, your accept method will be similar to:

It first checks the location of the file. In this example, it checks that the file is either in the internal assets, i .e. src/main/resources/assets or in the global assets (src/main/assets). Then, it checks for the file’s extension. Notice that you must not check for the existence, as the accept method is also called for deleted file.

Once the accept method is implemented, you need to implement the:

In general, the fileCreated and fileUpdated methods call the Mojo’s main method (execute), while the fileDeleted method cleans up generated files when the input file is deleted.

These methods return a boolean controlling the pipeline execution. If one of the method returns false, the pipeline is interrupted, and none of the following watchers are called. In most cases, you need to return true.

As you may have noticed, the Watcher's methods can throw WatchingException. Watching Exceptions let you indicate an issue in the processing. A default error page is generated from this exception with the message, of the guilty file, and if specified, the line and position of the error.

As your Watcher is a Mojo and the pipeline is reusing the Mojo’s instances, all of the injected parameters from your Mojo are still available. Notice that the execute method is called before the Watcher’s methods, meaning that you can do the required initialization there if required.

Maybe your Mojo is skipped. In that case you need to explicitly unregister it from the pipeline by calling the removeFromWatching method in your execute method.

We provide a Maven Archetype generating the project to develop your Watcher. Executes the following command to generate it:

Most of the Web Tools developed today are available as NPM (i.e. Node’s module). Fortunately, Wisdom provides a set of utility classes to install and execute NPM.

To use a NPM tool, declare a NPM object as follows:

In most cases, declare your NPM object as a field, as both the execute method and watcher’s method will invoke it. If the specified NPM is not install yet, it will install it (from NPM).

It is a good practice to declare the NPM’s version as a parameter, so the user can specify the version:

To execute the NPM, use:

The "exec" argument is the name of the command to launch. Available commands are available from the package.json files of the NPM, in the bin part:

The others arguments are the command’s arguments. In the previous example the input and output paths.

So, for instance, here are the lines invoking the myth processing:

The CoffeeScript invocation is made by:

In this last example, we retrieve the error stream (if any) and parse the error message to build a WatchingException containing the compilation error, the guilty line and position.

So you have made your very own extension for Wisdom and you want the world to see it? Great! You can add it to the Wisdom Extension registry located here.

In order to add your extension to the registry you need to create a Json file. This file will contain the details about your extension such as the name, the project’s homepage and so on.

It may be helpful to have information on your homepage on how to use your extension. Extensions are generally used by either adding the extension as a dependency in a project’s pom file, or as a maven plugin.

Here is a quick overview of the structure for the json file.

Required fields are: name - the name of your extension, this name must be unique; version, description, and homepage. The other fields are optional.

After you have have saved your Json file to a location accessible on the web, you can then enter its url into the text box at the bottom of the registry page. (If you don’t see the input box make sure you’re on the developers view version).

The source code is hosted on GitHub: https://github.com/wisdom-framework/wisdom/.

The Wisdom Project is using the GitHub Issue Tracker: https://github.com/wisdom-framework/wisdom/issues.

The main continuous integration server is provided by Cloudbees (Wisdom adheres to the FOSS program): https://wisdom-framework.ci.cloudbees.com/

To build Wisdom you need Apache Maven 3.2.1+. The Wisdom build is divided in several profiles:

To skip the tests, append the -DskipTests option to the command line.

As tests are being executed in a Wisdom server, you may experience some timing issues. If it’s the case, try setting the TIME_FACTOR to extend the wait durations:

As Wisdom contains a Maven Plugin used by other projects and extending the lifecycle (so called extension), the maven-release-plugin cannot be used. This Maven limitation makes the release process a bit cumbersome.

First, check that your ~/.m2/settings.xml contains you GPG password when the release profile is activated:

Then check that your credential to Sonatype OSS are written in your ~/.m2/settings.xml:

You also need to be sure you have the permission to push to the Wisdom Git repository.

Notice that you will have matches, and that’s normal. You need to verify by yourself.

If everything is fine, continue, else rollback. It’s generally recommended to check that the artifact are correctly signed with GPG.

What you did so far is the equivalent to the mvn release:prepare. It’s now time to perform the release, so building the released artifacts.

If you reach this point, you made it ! Congratulations !

By default Wisdom uses Apache Felix as OSGi framework. You can also use Eclipse Equinox. To switch to Equinox, edit your project’s pom.xml file and add the <wisdomRuntime> parameter of the wisdom-maven-plugin: