Juzu is built on top of a plugin architecture allowing to reduce the number of dependencies to the minimum for the core of the framework.

Juzu leverages an Injection Container (IOC) at runtime for wiring the various objects managed by the framework. Several implementations can be used and you should configure the correct dependencies according to the container you are using:

These implementation jars are never required at compilation time, unless you use specific classes in your project, such as the @Autowire annotation of Spring, or the @Produces annotation of CDI.

At runtime the jars you needs depends on the implementation you use:

The Maven war packaging is a convenient way for building a web application with Maven. In the following examples we will show the Maven configuration for a couple of examples, all the configurations are listed in the appendix of this guide:

Building a Juzu application with Gradle is very easy with the war Gradle plugin, here is an example of build.gradle file:

Eclipse IDE provides the best support for annotation processing among all IDEs. Annotation processing is integrated natively at the heart of Eclipse incremental compiler providing an high level of interaction between the developer and its project.

In this section we will see how to import the Maven based Juzu sample in Eclipse and configure it for annotation processing.

Juzu uses Annotation Processing Tool to perform many tasks at compilation time. APT is a standard extension of a Java compiler. All Java IDE (Eclipse, Intellij and Netbeans) provide good support for APT, we will show in the section how to configure and uses APT within those IDEs.

IDEs provide also Maven support, we will focus in this section on using APT without the Maven support. Indeed the APT support may work differently when using Maven in your project, the Maven and APT support within IDEs has a dedicated section.

In this Intellij walkthrough we will work with project called myapp that was created by the Juzu Maven archetype.

The view phase invokes the application for the purpose of creating markup. This phase is indempotent, it means that repeated invocation of the same phase with the same parameters should produce the same markup (supposing than the application does not depend on some other state, like a database that could change over time).

View parameters are associated with the current URL, it means that they are somehow persistent. For instance you interact with an application to change its view parameters on each request and then you interact with another application on the same page: the view parameters will remain the same accross the invocation of the view phase of the application when the second application is used.

The action phase invokes the application for processing an action. During the invocation, action parameters are provided and their validity is limited to the current action phase being executed, after they will not be anymore available.

The action phase is not idempotent, invoking several times an action phase could have side effects such as inserting several times the same data in a database.

Juzu does not expect markup returned during this phase, however it provides the opportunity to configure the view parameters of the next view phase.

The resource phase allows the application to produce a web resource such as an image or a full page. When this phase is invoked, a set of resources parameters are provided in the URL producing the resource.

View phases are mapped on GET requests:

During a view phase, the application produces URL which can invoke any application phase.

In this example the view phase produce markup parameterized by the color parameter having the red value.

Action phase are created from view phase by processing a link that was found in the markup response. The action phase is mapped on POST requests:

Now let’s update our example and suppose that the application returns markup with a form that invokes an action phase. When the user submits the form it triggers the action phase, which in returns updates the color view parameter of the next view phase to the value blue.

The HTTP redirection will update the browser to show the next view phase with the expected view parameters.

During the action phase, the application configures the parameters of the next view phase. When the invocation of the phase is over, the server redirects the browser (with an HTTP temporary redirection) to the next view phase URL. This URL contains the view parameters. This mechanism is well known as Redirect After Post pattern and is often used to ensure that a POST request is not triggered several times when the refresh button of the browser is used.

Resource phases are trivially mapped on GET request pretty much like a view phase. The main difference is that the resource phase is responsible for managing the entire response instead of just a fragment of the response.

When Juzu handles an http request it routes this request to a controller based on the request path. Request routing is based on a set of route declarations, each declaration binds a route to a controller method.

Unlike the http protocol, the portlet request routing does not require the @Route annotation because portlet requests are managed by the portal and have no concept of path mapping.

To achieve request routing, the portlet uses a special portlet request parameter named juzu.op . This parameter determines which controller should be called during a phase. When the juzu.op parameter is not present, Juzu will look for the index view controller.

A view controller method produces aggregated markup for the application, the invocation of the method should produce markup that will be aggregated in larger page, therefore it should not care about the overall HTML structure.

View parameters describe the current parameters of the view, they are often used for navigation purpose in the application. Juzu supports simple data types such as string and structured data types modelled by Java objects.

View controller method should return a juzu.Response object that is the content produced by the method. To be more precise it should return a Response.Body or Response.Content object (the latter being a subclass of the former) that contains everything Juzu needs to display the application.

During the view phase a controller can generate URLs to other phases (except the event phase) by using controller companion methods. Companion methods returns a juzu.Dispatch object to represent the URL. The final URL is returned by the toString() method of the dispatch object.

Action controller are executed during the action phase of a Juzu application. Usually action methods perform two tasks

In the following example, the controller method createUser creates a user and returns a Response.View object that will tell Juzu to use the showUser view controller during the next view phase:

showUser is a companion view method that creates a +Response.View_ object configured with the controller and arguments to use. Like url companion methods, view companion methods are generated during the compilation of the project by Juzu.

Resource controllers are similar to view controllers, however the resource has full control over the target page. It means that a resource controller must produce the entire resource and it can also chose the mime type returned. Resource controllers have several use cases:

not yet implemented

We will study in this section the complete life cycle of a controller object. Juzu relies on the IOC container for managing the life cycle of controller objects, based on the @javax.inject.Inject annotation. If the controller desires, it can receive life cycle callbacks thanks to the @javax.annotation.PostConstruct and @javax.annotation.PreDestroy annotations.

Let’s have a look at the complete life cycle of a controller object during a Juzu request:

The bare minimum Juzu will do when dispatching to a controller method is to invoke this method with the proper arguments and use the optionally returned object as a response for the request.

When the controller wants to deal with the dispatch in a generic manner (i.e detyped), it can implement the juzu.request.RequestLifeCycle interface that allows to:

The first step for using the servlet bridge is to configure the juzu.bridge.servlet.JuzuServlet servlet for the application. There is a one to one mapping between a Juzu application and a Juzu servlet. Therefore if you project contains several applications, you should configure a Juzu servlet for each.

Declaring a Juzu servlet is done in the web.xml file of the web application or using annotations. Annotation based is described in the Servlet chapter.

The juzu.app_name init parameter tells Juzu the package of the application to use. The servlet is bound on the / pattern as the default servlet of the web application.

In case of several applications, each can be configured with a path mapping in addition of the default servlet:

The first step for using the portlet bridge is to configure the juzu.bridge.portlet.JuzuPortlet portlet for the application. There is a one to one mapping between a Juzu application and a Juzu portlet. Therefore if you project contains several applications, you should configure a Juzu portlet for each.

Declaring a Juzu portlet is done in the portlet.xml file of the portlet application:

The juzu.app_name init parameter tells Juzu the package of the application to use.

Beans are simply object managed by the IOC container, any bean can be injected other beans:

Scopes define how a instances of a bean are managed by the IOC container: for a given bean, shall it be instantiated only one time and shared or shall it instantiated everty time it is required ? that’s the kind of question that scope answers.

Juzu provides 4 scopes to use within your application:

Qualifier are designed to distinguish several instances of a same bean. How does a bean differ from another bean ? it’s not really possible to tell, qualifiers simply answer this question, allowing to:

The JSR-330 specification provides the @Named qualifier whose purpose is to give a name to a bean, for instance

Every template has a corresponding juzu.template.Template class at runtime. The template class allows applications to interact with templates, most of the time for creating a controller ok response:

A template bean is always qualified by the @Path qualifier. The path qualifier is simply the value of the path relative to the templates package, for instance index.gtmpl is a valid qualifier value. The qualifier allows to have several Template instances and distinguish them.

Templates have the @Singleton scope: a single instance of the template object is created and shared in the IOC container.

Each controller class is turned into a bean, that’s how controllers can be injected with other beans. As soon as Juzu finds a class annotated by @View, @Action or @Resource, it is automatically turned into a bean.

Controller have the Request scope by default: every time a controller instance is required it will be created for the duration of the request. It is possible to change the scope of a controller by annotating it with another scope annotation managed by Juzu:

Application beans model the custom logic of an application, they are normally injected in controller beans that use them when they process requests. The binding plugin allows an application to declare custom beans that can be used in the application.

A Juzu application can reuse an existing container scoped to a web application. In this case Juzu will create its own container with the provided container as parent, as a result, all beans available in the provided container will be available in the Juzu application.

During the startup of the application, the web application attribute org.springframework.web.context.WebApplicationContext.ROOT is looked up, this is the provided container when it is not null. Such container is usually created by a Spring servlet or listener, for example:

This usually start the beans declared in the /WEB-INF/applicationContext.xml.

Provided CDI is supported since Juzu 0.7.0, it provides an integration managed by the server:

In both case you need to comply to CDI applications rules such as having a beans.xml file in your WEB-INF directory.

The native template engine extends the Groovy templating system: it can include snippet of Groovy code or resolve Groovy expressions:

The Mustache template engine uses logic-less templates based on Mustache.java the Java port of Mustache. Mustache is very easy to use, you can read the documentation, however we will have a quick overview of how it can be used in Juzu:

Applications use a template by injecting a juzu.template.Template object in its controllers qualified by the juzu.Path annotation:

The @Path declares the template to use, the value is usually a path relative to the templates package. The value can also be absolute like /my/application/templates/index.gtmpl.

The @Inject annotation instructs the injection container the inject the template at runtime, so it can be used by the controller.

The render method of a template returns a juzu.Response.Content response which can also be returned by the controller method.

Template can be shared between applications: one application can reuse the templates of another application by using an absolute path value instead of a relative path value:

There are a few things to keep in mind when using external templates:

Template type safe parameters brings more type safety in your applications. Templates can declare parameters and they are made available on a subclass of the juzu.template.Template class.

Parameters are declared using the taglib support of the native template engine

or the pragma support of the Mustache engine

When the template is declared in a controller, a subclass of juzu.template.Template can be used:

The weather.templates.sky class does not exist in the original source but it is available when the application is compiled because it will be generated by Juzu compiler integration. The sky templates provides a fluent syntax to bind parameters: sky.with().color("blue").ok().

When we studied the templating engine syntax but we did not mentioned exactly how expression are resolved.

Simple tags allow creation of custom tags with templates located in the tags package of your application.

Put this content in the tags/mytag.gtmpl file of the application.

Obviously Juzu needs to be aware of the existence of this tag, this is achieved using the @Tag/@Tags annotations:

Simple tags are templates so most of the tag syntax applies here, however there are a few differences between application templates and simple tags:

Tags can also be implemented with Java code, let’s look at the actual implementation of the title tag:

Finally the tag must be declared as a Java Service Provider API which is achieved by having the following content in the META-INF/services/juzu.template.TagHandler file:

When you provide a resource bundle along with your application, the bundle object is available for injection:

The native template engine supports the resolution of Messages from the resource bundle.

The juzu.impl.template.spi.TemplateProvider is the main entry point when a templating system is integrated. The provider is triggered during the compilation phase by the APT system built into the Java compiler.

The provider must declare the template model <M> generic type, this type must be a serializable as Juzu will sometimes write template models on the disk during the compilation. This usually happens only in Eclipse due its incremental compiler architecture. The type specified by the provider is privately managed (i.e it is opaque for Juzu) and it symbolizes an internal representation of the parsed source (usually an Abstract Syntax Tree), it will be used in various methods of the provider.

Let’s have a review of the methods of this class to have a better understanding.

The getSourceExtension() method is used to determine what file extension the provider can compile. The implementation should return a constant value, for instance the Groovy provide simply returns the gtmpl value.

The parse, process and emit methods care about transforming the template source to its final representation: the compiled template.

Finally the getTemplateStubType() returns the type of a java class that will be used for creating a template stub. For each template, a stub is created, the stub is responsible for loading the template at runtime, i.e the original template or the compiled template that may have been generated during compilation during the emit callback.

Template stubs are java classes created by Juzu for managing a template at runtime on behalf of the provider. Each provider provides its own stub implementation as a juzu.impl.template.spi.TemplateStub subclass.

A stub must provide a public constructor accepting a java.lang.String argument: the template id. The template id if the class name of the generated template. In addition, a stub must implement two abstract methods:

The doInit method loads the template using the provided ClassLoader, it will be call only once before the template is rendered. Usually it uses the template id provided during the construction of the template to locate the template on the disk, in its original form or in its compiled form.

The doRender method renders the template using the provided TemplateRenderContext. The render context provides the necessary hooks such as:

Assets are identified by a unique id within the application, this value is however optional. When no id is declared , the asset value is used for creating an id from the asset file name:

Applications assets can be located anywhere on the application classpath, they can be either absolute or relatives. Relative assets declared by the asset plugin must be located in the assets package of the application, for instance an application packaged under my.application will have its relative assets located under my.application.assets.

The location AssetLocation.APPLICATION is not declared because it is the default one.

Server assets are served by the webserver in which the application is deployed. Relative server assets are served from the war file containing the application.

External assets declares an opaque URL for Juzu.

The WithAssets annotation tells Juzu to add an asset to a content response, it takes asset ids as arguments:

The annotation can be declared on controller methods, classes or packages. such declarations are cascaded to the nested controllers:

Those rules apply where the @WithAssets annotation occurs, in particular it is also valid for overriden methods. The overriding method will not use the annotations of its current class or packages unless the method redeclares an @WithAssets annotation (possibly empty).

Annotating the application package with #WithAsset will serve all assets declared in the application for all controllers. If you need finer grained serving, remove it and use it on controller directly.

Declarative asset serving is powerful, however is requires you to declare the asset to server at compilation time. When the application does not know the assets to serve at compilation, this behavior can be also dynamic by using the Juzu API.

The withAssets method does exactly the same job than the WithAssets annotation.

File upload can be handled during an action of a portlet or a servlet:

File upload can also be handled in a resource phase.

Handling upload in a resource phase can be used when the file is uploaded via Ajax: the application does not want a view phase to be triggered after the upload.

Add the Less plugin jar to your compilation classpath.

In Maven it can achieved by adding the Less plugin dependency to your POM:

The plugin will copy the content of the foo webjar to the application assets directory, they will be available as any other asset. For this example foo.js file will be located in the myapp.assets package.

If we want this file to be served with the application we simply add the corresponding @Assets annotation:

It can also be used as a JavaScript module with the AMD plugin:

You don’t need to specify the WebJar version because the WebJars plugin will find it automatically (by examining the Maven metadata stored in the jar). However some jars have files that don’t correspond to the WebJar version (usually patch releases), in that case you can specify the version to help the plugin find the files:

For this particular version 0.7.0-1 the effective version to use it 0.7.0. This can be achieved by examining the jar:

In this special case, we need to tell the version to the plugin:

Add the WebJars plugin jar to your compilation classpath.

In Maven it can achieved by adding the WebJars plugin dependency to your POM:

A Juzu servlet application is managed by a JuzuServlet configured with the application name. Since Servlet 3.0, configuration can be easier thanks to servlet annotations. Juzu leverages this capability and is able to generate a servlet for an application with the juzu.plugin.servlet.Servlet annotation:

The @Servlet annotation allows to declare a resource bundle:

The jar of the servlet plugin contains a web-fragment.xml that automatically declares the asset servlet simplifying further more the configuration of the application.

A Juzu portlet application is managed by a JuzuPortlet configured with the application name. The @juzu.plugin.portlet.Portlet annotation can be used to generate a subclass of the JuzuPortlet that configures the application name for you, easing the configuration of the portlet.xml corresponding section.

The plugin will generate the portlet using the application name with the first letter capitalized and the Portlet suffix. In our example the my application generates the MyPortlet class. If you don’t like it you can change the name of the generated class in the application:

During the various phase of an application, the portlet resource bundle for the current locale can be injected:

This is equivalent of doing:

This resource bundle can be configured in the portlet.xml deployment descriptor.

Add the Portlet plugin jar to your compilation classpath.

In Maven it can achieved by adding the Less plugin dependency to your POM: