Errai User Guide

It's important to understand the concept of how messaging works in ErraiBus. Service endpoints are given string-based names that are referenced by message senders. There is no difference between sending a message to a client-based service, or sending a message to a server-based service. In fact, a service of the same name may co-exist on both the client and the server and both will receive all messages bound for that service name, whether they are sent from the client or from the server.

Services are lightweight in ErraiBus, and can be declared liberally and extensively within your application to provide a message-based infrastructure for your web application. It can be tempting to think of ErraiBus simply as a client-server communication platform, but there is a plethora of possibilities for using ErraiBus purely with the GWT client context, such as a way to advertise and expose components dynamically, to get around the lack of reflection in GWT.

In fact, ErraiBus was originally designed to run completely within the client but quickly evolved into having the capabilities it now has today. So keep that in mind when you run up against problems in the client space that could benefit from runtime federation.

The MessageBuilder is the heart of the messaging API in ErraiBus. It provides a fluent / builder API, that is used for constructing messages. All three major message patterns can be constructed from the MessageBuilder.

Components that want to receive messages need to implement the MessageCallback interface.

But before we dive into the details, let look at some use cases first.

In order to send a message from a client you need to create a Message and send it through an instance of MessageBus. In this simple example we send it to the subject 'HelloWorldService'.

public class HelloWorld implements EntryPoint {

    // Get an instance of the RequestDispatcher
    private RequestDispatcher dispatcher = ErraiBus.getDispatcher();

    public void onModuleLoad() {
        Button button = new Button("Send message");

        button.addClickHandler(new ClickHandler() {

        public void onClick(ClickEvent event) {
            // Send a message to the 'HelloWorldService'.
            MessageBuilder.createMessage()
                .toSubject("HelloWorldService")             // (1)
                .signalling()                               // (2)
                .noErrorHandling()                          // (3)
                .sendNowWith(dispatcher);                   // (4)
            });

            [...]
        }
}
                

In the above example we build and send a message every time the button is clicked. Here's an explanation of what's going on as annotated above:

Every message has a sender and at least one receiver. A receiver is as it sounds--it receives the message and does something with it. Implementing a receiver (also referred to as a service) is as simple as implementing our standard MessageCallback interface, which is used pervasively across, both client and server code. Let's begin with server side component that receives messages:

@Service
public class HelloWorldService implements MessageCallback {
    public void callback(Message message) {
        System.out.println("Hello, World!");
    }
}
                

He we declare an extremely simple service. The @Service annotation provides a convenient, meta-data based way of having the bus auto-discover and deploy the service.

In the following example we extend our server side component to reply with a message when the callback method is invoked. It will create a message and address it to the subject 'HelloWorldClient':

@Service
public class HelloWorldService implements MessageCallback {

    private RequestDispatcher dispatcher;

    @Inject
    public HelloWorldService(RequestDispatcher disaptcher) {
        dispatcher = dispatcher;
    }

    public void callback(CommandMessage message) {
        // Send a message to the 'HelloWorldClient'.
        MessageBuilder.createMessage()
            .toSubject("HelloWorldClient")              // (1)
            .signalling()                               // (2)
            .with("text", "Hi There")                   // (3)
            .noErrorHandling()                          // (4)
            .sendNowWith(dispatcher);                   // (5)
        });
    }
}
                

The above example shows a service which sends a message in response to receiving a message. Here's what's going on:

Messages can be received asynchronously and arbitriraily by declaring callback services within the client bus. As ErraiBus maintains an open COMET channel at all times, these messages are delivered in real time to the client as they are sent. This provides built-in push messaging for all client services.

public class HelloWorld implements EntryPoint {

    private MessageBus bus = ErraiBus.get();

    public void onModuleLoad() {
        [...]

        /**
        * Declare a local service to receive messages on the subject
        * "BroadcastReceiver".
        */
        bus.subscribe("BroadcastReceiver", new MessageCallback() {
            public void callback(CommandMessage message) {
                /**
                * When a message arrives, extract the "text" field and
                * do something with it
                */
                String messageText = message.get(String.class, "text");
            }
        });

        [...]
}
                

In the above example, we declare a new client service called "BroadcastReceiver" which can now accept both local messages and remote messages from the server bus. The service will be available in the client to receive messages as long the client bus is connected and the service is not explicitly de-registered.

Conversations are message exchanges which are between a single client and a service. They are a fundmentally important concept in ErraiBus, since by default, a message will be broadcast to all client services listening on a particular channel.

When you create a conversation with an incoming message, you ensure that the message you are sending back is received by the same client which sent the incoming message. A simple example:

@Service
public class HelloWorldService implements MessageCallback {
    public void callback(CommandMessage message) {
        // Send a message to the 'HelloWorldClient' on the client that sent us the
        // the message.
        MessageBuilder.createConversation(message)
            .toSubject("HelloWorldClient")
            .signalling()
            .with("text", "Hi There! We're having a conversation!")
            .noErrorHandling().reply();
        });
    }
}
                

Note that the only difference between the example in the previous section (2.4) and this is the use of the createConversation() method with MessageBuilder.

MessageBuilder.createMessage()
    .toSubject("ConversationalService").signalling()
    .with("SomeField", someValue)
    .noErrorHandling()
    .repliesTo(new MessageCallback() {
        public void callback(Message message) {
            System.out.println("I received a response");
        }
})
                    

MessageBuilder.createMessage()
    .toSubject("ObjectService").signalling()
    .with(MessageParts.ReplyTo, "ClientEndpoint")
    .noErrorHandling().sendNowWith(dispatcher);
                    

MessageBuilder.createConversation(message)
    .subjectProvided().signalling()
    .with("Records", records)
    .noErrorHandling().reply();
                    

Broadcasting messages to all clients listening on a specific subject is quite simple and involves nothing more than forgoing use of the conversation API. For instance:

MessageBuilder.createMessage().
    .toSubject("MessageListener")
    .with("Text", "Hello, from your overlords in the cloud")
    .noErrorHandling().sendGlobalWith(dispatcher);
                

If sent from the server, all clients currently connected, who are listening to the subject "MessageListener" will receive the message. It's as simple as that.

Communication from one client to another client is not directly possible within the bus federation, by design. This isn't to say that it's not possible. But one client cannot see a service within the federation of another client. We institute this limitation as a matter of basic security. But many software engineers will likely find the prospects of such communication appealing, so this section will provide some basic pointers on how to go about accomplishing it.

...
public void callback(Message message) {
    String sessionId = ServerBusUtils.getSessionId(message);

    // Record this sessionId somewhere.
        ...
}
                    

MessageBuilder.createMessage()
    .toSubject("ClientMessageListener")
    .signalling()
    .with(MessageParts.SessionID, sessionId)
    .with("Message", "We're relaying a message!")
    .noErrorHandling().sendNowWith(dispatcher);
    

Asynchronous messaging necessitates the need for asynchronous error handling. Luckily, support for handling errors is built directly into the MessageBuilder API, utilizing the ErrorCallback interface. In the examples shown in previous exceptions, error-handing has been glossed over with a ubiquitous usage of the noErrorHandling() method while building messaging. We chose to require the explicit use of such a method to remind developers of the fact that they are responsible for their own error handling, requiring you to explicitly make the decision to forego handling potential errors.

As a general rule, you should always handle your errors. It will lead to faster and quicker identification of problems with your applications if you have error handlers, and generally help you build more robust code.

MessageBuilder.createMessage()
    .toSubject("HelloWorldService")
    .signalling()
    .with("msg", "Hi there!")
    .errorsHandledBy(new ErrorCallback() {
        public boolean error(Message message, Throwable throwable) {
            throwable.printStackTrace();
            return true;
        }
    })
    .sendNowWith(dispatcher);
                

The addition of error-handling at first may put off developers as it makes code more verbose and less-readable. This is nothing that some good practice can't fix. In fact, you may find cases where the same error-handler can appropriately be shared between multiple different calls.

ErrorCallback error = new ErrorCallback() {
    public boolean error(Message message, Throwable throwable) {
        throwable.printStackTrace();
        return true;
    }
}

MessageBuilder.createMessage()
    .toSubject("HelloWorldService")
    .signalling()
    .with("msg", "Hi there!")
    .errorsHandledBy(error)
    .sendNowWith(dispatcher);
                

A little nicer.

The error handler requires that return a boolean value. This is to indicate whether or not Errai should perform the defautl error handling actions it would normally take during a failure. You will almost always want to return true here, unless you are trying to expicitly supress some undesirably activity by Errai, such as automatic subject-termination in conversations. But this is almost never the case.

In some applications, it may be necessary or desirable to delay transmission of, or continually stream data to a remote client or group of clients (or from a client to the server). In cases like this, you can utilize the replyRepeating(), replyDelayed(), sendRepeating() and sendDelayed() methods in the MessageBuilder.

MessageBuilder.createConversation(msg)
    .toSubject("FunSubject")
    .signalling()
    .noErrorHandling()
    .replyDelayed(TimeUnit.SECONDS, 5); // sends the message after 5 seconds.

                    

MessageBuilder.createMessage()
    .toSubject("FunSubject")
    .signalling()
    .noErrorHandling()
    .sendDelayed(requestDispatcher, TimeUnit.SECONDS, 5); // sends the message after 5 seconds.

MessageBuilder.createMessage()
    .toSubject("FunSubject")
    .signalling()
    .withProvided("time", new ResourceProvider<String>() {
        SimpleDateFormat fmt = new SimpleDateFormat("hh:mm:ss");
        public String get() {
            return fmt.format(new Date(System.currentTimeMillis());
        }
    }
    .noErrorHandling()
    .sendRepeatingWith(requestDispatcher, TimeUnit.SECONDS, 1); //sends a message every 1 second

AsyncTask task = MessageBuilder.createConversation(message)
    .toSubject("TimeChannel").signalling()
    .withProvided(TimeServerParts.TimeString, new ResourceProvider<String>() {
        public String get() {
            return String.valueOf(System.currentTimeMillis());
        }
    }).defaultErrorHandling().replyRepeating(TimeUnit.MILLISECONDS, 100);

    ...

    // cancel the task and interrupt it's thread if necessary.
    task.cancel(true);
                    

RPC services provide a way of creating type-safe mechanisms to make client-to-server calls. Currently, this mechanism only support client-to-server calls, and not vice-versa.

Creating a service is straight forward. It requires the definition of a remote interface, and a service class which implements it. See the following:

@Remote
public interface MyRemoteService {
    public boolean isEveryoneHappy();
}
                

The @Remote annotation tells Errai that we'd like to use this interface as a remote interface. The remote interface must be part of of the GWT client code. It cannot be part of the server-side code, since the interface will need to be referenced from both the client and server side code. That said, the implementation of a service is relatively to the point:

@Service
public class MyRemoteServiceImpl implements MyRemoteService {

    public boolean isEveryoneHappy() {
        // blatently lie and say everyone's happy.
        return true;
    }
}
                

That's all there is to it. You use the same @Service annotation as described in Section 2.4. The presence of the remote interface tips Errai off as to what you want to do with the class.

Calling a remote service involves use of the MessageBuilder API. Since all messages are asynchronous, the actual code for calling the remote service involves the use of a callback, which we use to receive the response from the remote method. Let's see how it works:

MessageBuilder.createCall(new RemoteCallback<Boolean>() {
    public void callback(Boolean isHappy) {
        if (isHappy) Window.alert("Everyone is happy!");
    }
}, MyRemoteService.class).isEveryoneHappy();
                

In the above example, we declare a remote callback that receives a Boolean, to correpond to the return value of the method on the server. We also reference the remote interface we are calling, and directly call the method. However, don't be tempted to write code like this:

boolean bool = MessageBuilder.createCall(..., MyRemoteService.class).isEveryoneHappy();
                

The above code will never return a valid result. In fact, it will always return null, false, or 0 depending on the type. This is due to the fact that the method is dispatched asynchronously, as in, it does not wait for a server response before returning control. The reason we chose to do this, as opposed to emulate the native GWT-approach, which requires the implementation of remote and async interfaces, was purely a function of a tradeoff for simplicity.

One of the things Errai offers is the concept of session and local scopes.

public class TestService implements MessageCallback {
    public void callback(final Message message) {
        // obtain a reference to the local context by referencing the incoming message.
        LocalContext injectionContext = LocalContext.get(message);

        // set an attribute.
        injectionContext.setAttribute("MyAttribute", "Foo");
    }
}
                    

public class TestService implements MessageCallback {
    public void callback(final Message message) {
        // obtain a reference to the session context by referencing the incoming message.
        SessionContext injectionContext = SessionContext.get(message);

        // set an attribute.
        injectionContext.setAttribute("MyAttribute", "Foo");
    }
}
                    

The lifescyle of a session is bound by the underlying HTTP session. It is also bound by activity thresholds. Clients are required to send heartbeat messages every once in a while to maintain their sessions with the server. If a heartbeat message is not received after a certain period of time, the session is terminated and any resources are deallocated.

It may not be possible to annotate certain types you wish to expose to the bus for serialization if the entities are located in a third-party library that you do not maintain. As such, you can explicitly indicate in the configuration that you would like to have this entities made available by declaring them in the ErraiApp.properties of any module.

errai.bus.serializableTypes=org.foo.Foo \
    org.bar.Bar \
    org.foobie.Foobie
                

Depending on what application server you are deploying on, you must provide an appropriate servlet implementation if you wish to use true, asynchronous I/O. See section 6.5 for information on the available servlet implementations.

Here's a sample web.xml file:

<web-app xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
    http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
    version="2.5">

    <servlet>
        <servlet-name>ErraiServlet</servlet-name>
        <servlet-class>org.jboss.errai.bus.server.servlet.DefaultBlockingServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>ErraiServlet</servlet-name>
        <url-pattern>*.erraiBus</url-pattern>
    </servlet-mapping>

    <context-param>
        <param-name>errai.properties</param-name>
        <param-value>/WEB-INF/errai.properties</param-value>
    </context-param>

    <context-param>
        <param-name>login.config</param-name>
        <param-value>/WEB-INF/login.config</param-value>
    </context-param>

    <context-param>
        <param-name>users.properties</param-name>
        <param-value>/WEB-INF/users.properties</param-value>
    </context-param>

</web-app>

The ErraiService.properties file contains basic configuration for the bus itself.

Example Configuration:

##
## Request dispatcher implementation (default is SimpleDispatcher)
##
#errai.dispatcher_implementation=org.jboss.errai.bus.server.SimpleDispatcher
errai.dispatcher_implementation=org.jboss.errai.bus.server.AsyncDispatcher


#
## Worker pool size.  This is the number of threads the asynchronous worker pool should provide for processing
## incoming messages. This option is only valid when using the AsyncDispatcher implementation.
##
errai.async.thread_pool_size=5

##
## Worker timeout (in seconds).  This defines the time that a single asychronous process may run, before the worker pool
## terminates it and reclaims the thread.   This option is only valid when using the AsyncDispatcher implementation.
##
errai.async.worker.timeout=5

##
## Specify the Authentication/Authorization Adapter to use
##
#errai.authentication_adapter=org.jboss.errai.persistence.server.security.HibernateAuthenticationAdapter
#errai.authentication_adapter=org.jboss.errai.bus.server.security.auth.JAASAdapter

##
## This property indicates whether or not authentication is required for all communication with the bus.  Set this
## to 'true' if all access to your application should be secure.
##
#errai.require_authentication_for_all=true

                

The ErraiApp.properties acts as a marker file. When it is detected inside a JAR or at the top of any classpath, the subdirectories are scanned for deployable components. As such, all Errai application modules in a project should contain an ErraiApp.properties at the root of all classpaths that you wish to be scanned.

The file can also include explicitly declared serializable types (such as those from third-party code) that cannot be annotated for serialization. (See the section on serialization for more details)

errai.bus.serializableTypes=org.foo.Foo \
    org.bar.Bar \
    org.foobie.Foobie
                    

Dispatchers encapsulate the strategy for taking messages that need to be delivered somewhere and seeing that they are delivered to where they need to go. There are two primary implementations that are provided with Errai, depending on your needs.

Errai has many several different implementations for HTTP traffic to and from the bus. We provide a universally-compatible blocking implementation that provides fully synchronous communication to/from the server-side bus. Where this introduces scalability problems, we have implemented many webserver-specific implementations that take advantage of the various proprietary APIs to provide true asynchrony.

These inlcuded implementations are packaged at: org.jboss.errai.bus.server.servlet

It's good to start with an explanation of the basic workspace concepts and terminlogy that we chose for it.

A workspace, in our term, is basically a collection of tools. Each tool serves a distinct purpose and can represent anything you like. The workspace manages the tools (or tool sets) and access to them. This includes loading and initialization, history, preferences and authorization amongst other things. Usually tools rely on the message bus for inter component communication as well as backend integration. But they are not tight to that. Workspaces makes no assumption about the implementation of your tool, it merely provides the glue to keep everything together.

Workspaces goes beyond simple API. It's not just another GWT module. It was designed to get you started quickly, without getting in your way. This includes the environment to build, deploy and test your tools. We've decided to use maven to provide these capabilities. It allows you to quickly get started (see Maven archetype), but more importantly, maven repositories are used to share tool implementations across workspace assemblies. This way you can easily combine your own and 3rd party tools as part of a custom workspace compilation.

Tools are declared through the @LoadToolSet annotation. This instructs the workspace to generate all the boiler plate to wire your tools with the workspace. A tool needs to implement the WidgetProvider interface. It's used by the workspace to instruct the tool to create it's UI widget when needed. This widget will then be embedded in the workspace.

@LoadTool(name = "Users", group = "Administration")                          (1)
    public class UserManagement implements WidgetProvider
    {

    public void provideWidget(final ProvisioningCallback callback) {           (2)
        callback.onSuccess(new UserManagementWidget());
    }

    class UserManagementWidget extends LayoutPanel                             (3)
    {
        [...]
    }
}
                    

Workspaces relies on a authentication scheme similiar to JAAS. It ships with different authentication modules (i.e. Hibernate, JAAS) that enable role based access to tools on the client side and services on the server side.

@LoadTool(name = "Inventory", group = "Administration")                (1)
@RequireRoles({"admin"})                                               (2)
public class Inventory implements WidgetProvider
{

    public void provideWidget(final ProvisioningCallback callback)     (3)
    {
        [...]
    }

}
                    

It's common to use the WidgetProvider API in a way that GWT 2.0 code splitting can kick in. This allows true lazy loading of tools upon demand, including all .js and resources necessary to run your tools:

@LoadTool(name = "Group Tasks", group = "Tasks")
public class OpenTasksModule implements WidgetProvider
{
    static OpenTasksView instance = null;

    public void provideWidget(final ProvisioningCallback callback)
    {
        GWT.runAsync(
            new RunAsyncCallback()
            {
                public void onFailure(Throwable err)
                {
                    GWT.log("Failed to load tool", err);
                }

                public void onSuccess()
                {
                    if (instance == null) {
                        instance = new OpenTasksView();  // your tool here
                    }

                    callback.onSuccess(instance);
                }
            }

        );
    }
}
                    

The workspace registry (org.jboss.errai.workspaces.client.framework.Registry) is a simple all purpose lookup for common workspace API that is available to any workspace component:

AuthenticationContext authenticationContext =
    Registry.get(SecurityService.class).getAuthenticationContext();
                    

The workspace itself doesn't provide an authentication component. Instead it relies on the Authentication provided by errai bus. When the workspace is loaded two thing happen: The workspace checks if authentication is required and, after authentication if needed, loads the tool sets.

The bus component in charge is the SecurityService (org.jboss.errai.bus.client.security.SecurityService). It is available through workspace Registry. For people extending the workspace functionality it offers two intersting options:

The later is important of you want to provide your own way of authenticating users, but still use the role based authorization build into workspaces.

The LoginClient is the counter part of the SecurityService. It is instructed by the SecurityService to request the credentials upon demand. This typically happens when the workspace is initialized, but might also occur later on, when a particular service requires a different role set, then the one assigned initially. We call this elevation. Similiar to the operating system of your choice that demands administrator priviledges for certain operations.

After the initial authentication (or lack of) the LoginClient instructs the actual workspace to assemble the tool sets.

History is build into the workspace. It's wired to the main navigation and allows to use the browser navigation to switch between previously selected tools. In addition to that, the same mechanism can be used to perma link tools from external applications. I.e. when notifying users, using an email that contains a link back to a particular tool.

The workspace allows you to store simple key-value pairs as preferences. Like with other common API, you obtain the Preferences through the workspace Registry:

Preferences prefs = Registry.get(Preferences.class);
prefs.set("default_sort_order", "ASC");
                    

The default implementation uses a cookie based approach, but it's easy to replace that one with a custom implementation in the module decriptor:

<module>
[...]
<replace-with class="org.jboss.errai.workspaces.client.framework.CookiePreferences">
<when-type-is class="org.jboss.errai.workspaces.client.framework.Preferences"/>
</replace-with>
</module>

                    

Workspaces inherits GWT Log. It ships with an embedded log message console that records log output, besides the default logging to the browser error console and the GWT hosted mode window. To use the internal logging mechanism, simply write messages to the Logger:

import com.allen_sauer.gwt.log.client.Log;
[...]

Log.warn("some log message");
Log.error("message", throwable);
                    

You need Apache Maven and a JDK to get started.

The most simple (and least error prone) way to get started is using the maven archetype that we ship as part of errai. Simply follow the instructions in the quickstart section and return here when you are done.

Once you've created a project using the maven archetype, make yourself familiar with the directory structure:

 Laika:gwt-app hbraun$ lstree
    | pom.xml
    |-src
    |---main
    |-----java
    |-------foo
    |---------bar
    |-----------client
    |-----------server
    |-war
    |---WEB-INF
                    

It basically follows the default GWT guidelines for breaking up code between client and server. Simply put tools (@LoadToolSet) into the client subpackage and services (@Service) into the server subpackages. Make sure you are familiar with the Workspace API before you continue.

Several configuration files drive a workspace build and the final application. Make sure to include all of them when porting the archetype example to a different GWT application:

./src/main/java/ErraiApp.properties
./src/main/java/ErraiService.properties
./src/main/java/my/app/App.gwt.xml
                    

If you followed the steps above, and did build your application stub using the maven archetype, then you should be launch the GWT hosted mode with the following commands:

mvn gwt:run

(alternatively)
mvn gwt:debug
                    

When chosing RPC style invocations on beans, you basically rely on a typed java interface the CDI managed bean needs to expose. A GWT client component can then create an invocation proxy based on this interface. For more information see chapter on RPC mechanism

If you chose publish/subscribe then your CDI bean needs to implement the MessageCallback interface, as described in chapter 'Messaging'. Any bean exposed in this way can accessed through the MessageBuilder API.

Any CDI managed component may produce and consume events. This allows beans to inertact in a completely decoupled fashion. Beans consume event by registering for a particular event type and qualifier. The Errai CDI extension simply extends this concept into the client tier. A GWT client application can simply register an Observer for a particular event type and thus receive events that are produced on the server side. Likewise GWT clients can produce events that are consumed by a server side component.

Let's take alook at an example.

 public class FraudClient extends LayoutPanel {

  @Inject
  public Event event;                                    (1)

  private HTML responsePanel;

  public FraudClient() {
    super(new BoxLayout(BoxLayout.Orientation.VERTICAL));

    Button button = new Button("Create activity", new ClickHandler() {
      public void onClick(ClickEvent clickEvent) {
        event.fire(new AccountActivity());
      }
    });

    responsePanel = new HTML();

    add(button);
    add(responsePanel);
  }


  public void processFraud(@Observes Fraud fraudEvent) { (2)
    responsePanel.setText("Fraud detected: " + fraudEvent.getTimestamp());
  }
}                       
                    

Two things are notable in this example:

To complete this exercise, let's look at the corrsponding CDI managed bean as well:

@ApplicationScoped
public class AccountService {
    @Inject @Any
    Event<Outbound> event;

    public void watchActivity(@Observes @Inbound AccountActivity activity) {
        Fraud payload = new Fraud(System.currentTimeMillis());
        event.fire(new Outbound(payload));
    }
}
                    

Typically a GWT application lifecycle begins with Hosted Mode development and finally a web application containing the GWT client code will be deployed to a target container (Servlet Engine, Application Server). This is no way different when working with CDI components to back your application.

What's different however is availability of the CDI container across the different runtimes. In GWT hosted mode and in a pure servlet environment you need to provide and bootstrap the CDI environment on your own. While any Java EE 6 Application Server already provides a preconfigured CDI container. To accomodate these differences, we need to do a little trickery when executing the GWT Hosted Mode and packaging our application for deployment.

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>gwt-maven-plugin</artifactId>
    <version>${gwt.maven}</version>
    <configuration>
        [...]
        <server>org.jboss.errai.cdi.server.gwt.JettyLauncher</server>
    </configuration>
        <executions>
         [...]
        </executions>
</plugin>                        
                        

<web-app>

    [...]

    <listener>
        <listener-class>org.jboss.errai.container.DevModeCDIBootstrap</listener-class>
    </listener>

    <resource-env-ref>
        <description>Object factory for the CDI Bean Manager</description>
        <resource-env-ref-name>BeanManager</resource-env-ref-name>
        <resource-env-ref-type>javax.enterprise.inject.spi.BeanManager</resource-env-ref-type>
    </resource-env-ref>

    [...]

</web-app>                            
                        

Laika:errai-<VERSION> hbraun$ lstree
    |-doc
    |-examples
    |-ext
    |---cdi
    |-----lib
    |-----resources
    |-lib
                        

To begin with we'll create a project layout using a maven build structure, which will provide us with bare bone project, including all dependencies, which can later on be imported in eclipse.

mvn archetype:generate  \
 -DarchetypeGroupId=org.jboss.errai \
 -DarchetypeArtifactId=cdi-archetype \
 -DarchetypeVersion=1.1-CR1 \
 -DarchetypeRepository=https://repository.jboss.org/nexus/content/groups/public/
            

Define value for property 'groupId': : foo.bar
Define value for property 'artifactId': : gwt-webapp
Define value for property 'version': 1.0-SNAPSHOT:
Define value for property 'package': foo.bar: com.foo.bar
Confirm properties configuration:
groupId: foo.bar
artifactId: gwt-webapp
version: 1.0-SNAPSHOT
package: com.foo.bar
Y:                 
            

Laika:Desktop hbraun$ cd gwt-webapp/
Laika:gwt-webapp hbraun$ ll
-rw-r--r--  1 hbraun  staff  13119 Jul 21 16:01 pom.xml
drwxr-xr-x  5 hbraun  staff    170 Jul 21 16:01 src
drwxr-xr-x  6 hbraun  staff    204 Jul 21 16:01 war
            

By default the archtype does package the web application for Hosted Mode execution and other servlet environments. If you want to deploy your application to JBoss, you need todo a clean rebuild using the JBoss profile (-Pjboss6).

mvn -Pjboss clean install
cp target/foobr-jboss6.war $JBOSS_HOME/server/default/deploy                    
                

In order to get you going quickly, we've provided a project archetype, that allows you to create a project skeleton similiar to the one we use for building the examples. It's based on the maven archetype plugin ^[1] and needs to be invoked from the command line:

mvn archetype:generate \
    -DarchetypeGroupId=org.jboss.errai \
    -DarchetypeArtifactId=sandbox-archetype \
    -DarchetypeVersion=1.1-CR2 \
    -DarchetypeRepository=https://repository.jboss.org/nexus/content/groups/public/
    

When invoking the archetype build it ask you about the maven groupId, artifactId and package name your GWT application should use:

Define value for groupId: : foo.bar
Define value for artifactId: : gwt-app
Define value for version:  1.0-SNAPSHOT: :
Define value for package:  foo.bar: : foo.bar.ui
Confirm properties configuration:
groupId: foo.bar
artifactId: gwt-app
version: 1.0-SNAPSHOT
package: foo.bar.ui
Y: : Y
                

What will be created for you, is a maven build structure, including references to the GWT SDK and the Errai dependencies necessary to launch a simple application:

Laika:test hbraun$ cd gwt-app/
Laika:gwt-app hbraun$ lstree
|-src
|---main
|-----java
|-------foo
|---------bar
|-----------client
|-----------server
|-war
|---WEB-INF
                

In order launch the GWT hosted mode, change into the project directory and type:

mvn gwt:run
                

The default project includes both a HelloWorld client (GWT), and a HelloWorld service.

By default the archtype does package the web application for Hosted Mode execution and other servlet environments. If you want to deploy your application to JBoss, you need todo a clean rebuild using the JBoss profile (-Pjboss6).

mvn -Pjboss clean install
cp target/foobar.war $JBOSS_HOME/server/default/deploy