Before we fully dive into the code, we need to understand how it is composed and designed. UberFire component design is based on a very useful design pattern used for building user interfaces called Model View Presenter (MVP). MVP is based on a highly used pattern called Model View Controller (MVC), but is devoid of one of its biggest issues, regarding component intercommunication. The idea behind MVP is twofold:

This creates a very distinctive structure of classes that can be easily changed, to provide different representations by allowing them to be completely detached from the business logic and from other visual components. The following diagram of MVP shows the basic interactions that happen with this pattern:

In the preceding figure, we can see how the classes inside one single MVP group interact on the left and how multiple MVP groups interact with each other on the right. We can see how communication is always managed through an event bus that distributes events to their relevant listeners, even with multiple MVP groups. This allows the application to grow exponentially without having to increase the complexity of its already existing components. Each MVP group only has to worry about the events that they care about.

This presents a significant improvement over MVP's predecessor pattern, called MVC. It is similar to MVP, except that it doesn't adopt intercommunication using an event bus. Without said component, each MVC group (as opposed to MVP) should know any other MVC group that requires notification of a particular action, and communication between controllers becomes hard to maintain. In the following figure, we can see an example of this with only five different MVC and MVP groups. Views and models were removed to reduce complexity.

Model View Controller versus Model View Presenter intercommunication channels

As you can see, no matter how many presenters exist, or what events they await, existing presenters that fire said events don't have to change to adjust to a growing component. With controllers, on the other hand, complexity can grow exponentially.

Now that we understand MVP and its advantages, we will make an example component using the UberFire framework and the MVP pattern.

In this section, we will learn how to configure our own visual components inside an UberFire-based application. In order to understand how to build them, we need to understand which types are available, and what are they used for. In the following subsections, we will discuss four of UberFire's most used components for defining user interfaces:

Once we get to know how they work and what they do, we will learn how to build our own user interfaces. Each visual representation in our demonstration will be based on the MVP pattern, and will be marked by annotations added to the Presenter class. All the components we will describe here are going to be implemented in the code files of this book in the appendix/uberfire-demo folder.

@Dependent
@WorkbenchScreen(identifier = "myParticularScreenID")
public class MyParticularScreenPresenter {
    …
    @WorkbenchPartTitle
    public String getTitle() {
        return "My Particular Screen";
    }
    …
    @WorkbenchPartView
    public IsWidget getView() {
        …
    }
    …
    @WorkbenchMenu
    public WorkbenchMenuBar getBar() {
        …
    }
}

@Dependent
@WorkbenchPopup(identifier = "myOwnPopupID")
public class MyOwnPopupPresenter {
    …
    @WorkbenchPartTitle
    public String getTitle() {
        return "My Own Popup";
    }
    …
    @WorkbenchPartView
    public IsWidget getView() {
        …
    }
}

@WorkbenchEditor(identifier = "myEditorForTypeX", supportedTypes = { XClientType.class })
public class MyEditor {
    @WorkbenchPartTitle
    public String getTitle() {
        return "MyEditor";
    }
    @WorkbenchPartView
    public IsWidget getEditorView() {
        …
    }
    @OnStartup
    public void onStart(final Path path) {
        …
    }
    …
}

@ApplicationScoped
@WorkbenchPerspective(
    identifier = "myCustomPerspective",
    isDefault = false)
public class CustomPerspective {

    @Perspective
    public PerspectiveDefinition getPerspective() {
        final PerspectiveDefinition p = 
            new PerspectiveDefinitionImpl(
                PanelType.ROOT_LIST);
        p.setTransient(true);
        p.setName(getClass().getName());
        p.getRoot().addPart(
            new PartDefinitionImpl(
                new DefaultPlaceRequest("myParticularScreenID")
             )
         );
        return p;
    }
}

All the visible UberFire components (perspectives, editors, pop ups, and screens) are defined in a way that makes them very detached from any core UberFire functionality. All you have to do is annotate certain methods to let UberFire connect them for you to all the right places. However, we just started with configuration annotations, and we still have to see a very important group of annotations that are used to define what to do on specific events that the workbench will send to your components.

Whenever a perspective changes, a screen is created, an editor is closed, or when the workbench needs to shut down, we need a way to tell our components how to react or even pass specific information about the event. For events as common as opening, closing, or focusing on a component, UberFire provides us with a series of lifecycle annotations that are visible in the following diagram:

The annotations shown in the preceding diagram are as follows:

Using these annotations, we can define user interactions that are very detached from the actual workbench's final implementation. This helps a lot in making scalable UI components with a lot of embedded functionality.

Now that we have seen all the UberFire annotation components, we can start seeing in detail the components created in the uberfire-demo project provided with the book.

In our example, we create a user interface to show a very simple functionality; a screen that shows us a list of messages with a pop up that allows us to create a new message. Messages are stored as simple String elements. The project is divided into three subprojects:

For this example, uberfire-demo-client is the subproject that will be most useful for us. We have created two components in it, a screen (to display a message list) and a popup (to create a new message). Let's take a look at specific utilities that the Message List screen uses by looking at a code fragment of MessageListPresenter:

@Dependent
@WorkbenchScreen(identifier = "uberFireDemo.MessageListScreen")
public class MessageListPresenter {
    public interface MessageListView extends 
                UberView<MessageListPresenter> {
        void displayNotification(String text);
        DataGrid<String> getDataGrid();
    }
    @Inject
    private PlaceManager placeManager;
    @Inject
    private MessageListView view;
    …
    @WorkbenchMenu
    public Menus getMenus() {
       return MenuFactory
           .newTopLevelMenu(constants.NewMessage())
           .respondsWith(new Command() {
               @Override
               public void execute() {
                   placeManager.goTo(
                       new DefaultPlaceRequest(
                           "uberFireDemo.NewMessagePopup" ) );
               }
           }).endMenu().build();
    }
  }
}

There are a few components in this code fragment that we still haven't seen and are very useful when working with UberFire components:

The code in the view implementation is then only an initialization and exposure of GWT components (in our case, those components are just a table with strings in it).

The other component, the pop up, has a very similar structure. Let's analyze this code fragment of the NewMessagePresenter class:

@Dependent
@WorkbenchPopup(identifier = "uberFireDemo.NewMessagePopup")
public class NewMessagePresenter {

    ...
    @Inject
    private Caller<DemoServiceEntryPoint> demoService;
    @Inject
    private Event<NewMessageEvent> newMsgEvent;
    …
    public void sendMessage(String message) {
        this.demoService.call( new RemoteCallback<Void>() {
            @Override
            public void callback( Void response ) {
                //send event
                newMsgEvent.fire(
                    new NewMessageEvent( view.getMessage() ) );
            }
        } ).sendMessage( message );
    }
}

For brevity's sake, we removed the most similar parts to the previous component. Let's discuss what's new in this class:

Creating a perspective is done exactly as explained before. In our case, we create a perspective to include only our message list screen. Here's the code found in our MessageListPerspective class:

@ApplicationScoped
@WorkbenchPerspective(
    identifier = "uberFireDemo.MessageListPerspective", 
    isDefault = false)
public class MessageListPerspective {
    @Perspective
    public PerspectiveDefinition getPerspective() {
        final PerspectiveDefinition p = 
            new PerspectiveDefinitionImpl(PanelType.ROOT_LIST);
        p.setTransient(true);
        p.setName("My Customized panel of Messages");
        p.getRoot().addPart(new PartDefinitionImpl(
            new DefaultPlaceRequest(
                "uberFireDemo.MessageListScreen")));
        return p;
    }
}

As you can see, all we do is create a method annotated with @Perspective to return a PerspectiveDefinition instance that will have our message list screen in it, and we mark it to not be the default perspective.

Workbenches are Maven-based web projects that depend extensively on UberFire and its internal configurations to work. Due to UberFire being in an alpha state, workbench definition is something that might still change a lot. It is because of this reason that we will not see how to create our own workbenches in detail. Instead, we are going to see the necessary steps to add new components built with UberFire in an already existing workbench. This is less prone to change to keep compatibility with already defined components. If you wish to build your own workbench from scratch, visit http://www.uberfireframework.org for more help with that aspect.

Review the jbpm-console-ng-showcase project inside the uberfire-demo folder. This is one workbench already available in the open source jBPM6 repositories to which we have added uberfire-demo as an extra component.

The steps taken to add new components to an UberFire based workbench are as follows:

As this book is being written, there are three Drools and jBPM6-related workbench applications that you can use to add your own components:

All of them could be extended to add new UberFire components in the way we explained in this section.