Wazaabi 1.0.0

Wazaabi Tutorial



WAZAABI - An easy way to build rich client applications 
based on Eclipse RCP, XUL and J2EE 

www.wazaabi.org

Copyright (c) 2006, Wazaabi Community (www.wazaabi.org).

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.

A copy of the license is included in the section entitled "GNU Free Documentation License".

Wazaabi and the Wazaabi logo are trademarks of Olivier Moïses in France and other countries.

DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.

This tutorial and other Wazaabi documentations are available through the Wazaabi website : http://wiki.wazaabi.org/index.php/Community:Documentation.

This documentation was produced with OpenOffice.org (www.openoffice.org).

Table of contents

Getting started

The technological and intellectual progress coalescence lead to the emergence of the rich client. The light client, democratized by the Web, seems to run out of user needs and demand of ergonomic software. Nowadays, people increasingly use software in their personal and professional life - mailing, mobility, multi-media applications, text handling, etc. The web is lacking in Desktop applications' richness and responsiveness.

WAZAABI gives a possibility to establish the advantages of two technologies within the same application. It ensures facilitated installation and update of the Web as well as ergonomic richness of desktop application.

Overview

WAZAABI is an open source framework, delivering significant benefits for building Eclipse RCP applications, by reducing development effort and costs. With Wazaabi, Eclipse RCP UIs are not any more developed using SWT but described in XML Files through the XUL standard. Thus, it is easy for designers to create UIs and for developers to create business components. The work is correctly managed.

About this document

This document is the tutorial and getting started guide for release 1.0.x of Wazaabi.

Check http://www.wazaabi.org to know about current release and its associated documentation.

The 1.0.x release will work in Eclipse 3.2.

Installation

At this time, Wazaabi is distributed in one format.

Windows 2000/XP

There are several ways to install Wazaabi in your Eclipse IDE:

Use the Wazaabi remote update site

The easiest way to install the last Wazaabi distribution is to use the remote update site :

In your Eclipse IDE, select “Help > Software Updates > Find and Install...” menu.

Select “Search for new features to install” and click the “New Remote Site...” button.

Fill in the name field with “Wazaabi updates” and the URL field with “http://updates.wazaabi.org”. Click “OK” and “Finish” buttons.

Check the “Wazaabi updates” check box and click “Next >”.

Accept the licence, click “Next >” and “Finish”.

Unzip Wazaabi distribution into Eclipse installation directory.

Download the last Wazaabi distribution.

Unzip the downloaded file into your Eclipse directory.

Restart Eclipse.

Use Wazaabi distribution as an Eclipse local update site

Download the last Wazaabi distribution.

Unzip the downloaded file into a temporary directory.

Use your Eclipse “Help > Software Updates > Find and Install... > Search for new features to install > New Local Site...” option to set this temporary directory as an Eclipse local Update Site.

For Wazaabi developpers: checkout the subversion projects into your Eclipse Workspace

Wazaabi source code is stored on a Subversion repository at http://svn.wazaabi.org/repos/wazaabi.

Use a Subversion client software to checkout Wazaabi project into your Eclipse Workspace.

Subclipse is an Eclipse plug-in that adds Subversion integration to the Eclipse IDE. More informations at : http://subclipse.tigris.org/

Architecture

Overview

A (very) high-level view of the Wazaabi architecture:

This diagram shows Wazaabi using the Eclipse Rich Client Platform and Wazaabi configuration data (wazaabi.properties) to provide services to the rich client application.

Layers components

A more detailed view of the architecture. The next diagram shows the three components of Wazaabi.

The eXtended Widget Toolkit (XWT) is a plug-in named org.wazaabi.xwt. This plug-in holds the XWT widgets used by Wazaabi. It adds XUL functionalities to SWT widgets.

The plug-in LAYOUT named org.wazaabi.layouts holds the SWT implementations of the XUL layouts used by Wazaabi. See SWT documentation for details about SWT layouts.

The GLUE stands for a layer link between visual components and trouble resolved by business Objects. The glue is made up of 7 plug-ins which can be bunch in three sets.

Runtime architecture

A detailed view of the runtime architecture.

Concepts

GUIs described in XML rather than coded in Java

Eclipse allows the construction of rich and user friendly GUIs.

In it's entirety the graphic interface is built in Java using SWT/JFace libraries.

Despite the existence of a Visual Editor, modifying a graphic interface is hard and often brings some bugs in the existing code.

Wazaabi is a solution allowing the description of most of the GUI in XML rather than coding it in Java.

This version is based on XUL, the standard initially created to describe GUIs of the projects of the Mozilla foundation (Firefox, Thunderbird,…).

Full DOM behaviour

XUL document is represented in a tree structure (Document Object Model, aka DOM).

DOM provides a structure that facilitates access to the elements of an XML document by Java with object oriented features (see DOM specifications in w3c web site).

Each interactions of the user are reflected in the DOM tree. That means that, if the user fills a text box, it is possible to read the filled value by getting related DOM element's attribute value.

Reciprocally, to update an attribute modifies something in the display.

Intensive namespace usage

Wazaabi make intensive use of name spaces, by catching only what relates to it, ignoring what is not. That means that, if he need some, the GUI programmer can augment the vocabulary of every document by using their own name spaces.

Factories based extensibility

Wazabi is an engine displaying atomic or complex GUI components described in XML. It is completely extensible by a dynamic mechanism based on factories.

Programmers can, without re-compile Wazaabi, to create bundles which will contain new widgets. Dispatching towards the factories is based on the resolution of the name spaces of XML elements. Factories can be dynamically added or removed.

Pattern based approach

The pattern approach is hugely used in many domains of computer programming.

Patterns are necessary to maintain efficiently applications, knowing that code is more often read than is written. Wazaabi incites programmers to use patterns while building GUIs.

OSGI compliant

Without precisely describing the OSGI standard (see www.osgi.org) , it can be firmly considered as a significant part of the Java's future. Wazaabi is widely integrated in OSGI mechanisms, providing and using many OSGI services. For this reason, Wazaabi is a significant step towards the creation of on demand Java applications.

Limitations

Namespace limitations

Wazaabi makes a intensive use of importations of XML element from a document to another. For this reason, sometimes name spaces declaration are not well imported in GLUEDialog or Viewpart. To prevent this behaviour, we recommend to put declarations of used name spaces by GUI elements in the highest comprised box (the first child of glue:content or glue:dialog-area).

Element insertion/importation

DOM standard supports insertion or importation of XML elements from a document to another one.

While Wazaabi supports also this feature, some elements are not well imported or sometimes behaviour is not the one expected. We recommend importation of containers as often as possible (boxes, grids) rather than 'simple' components.

XUL compatibility

Mozilla gecko engine draws a lot of things while displaying XUL graphical elements. SWT approach delegates most of the underlying drawing to system specific libraries. According to this, SWT (and Wazaabi) is less flexible than gecko. 100 % compatibility is not possible without almost drawing all widgets and in this case, display will be much more slower. For this reasons, Wazaabi is not, and will never be fully compatible with gecko rendering engine.

No CSS support and visual editor

There is actually no CSS support nor visual editor in this version. Both of this features are present in the roadmap, readers are invited to check periodically Wazaabi evolutions.

Lea Store

Lea Store is the Wazaabi reference application. Every code sample of this document comes from this program.

This chapter is a step by step guide for installing Lea Store projects on your eclipse IDE. Thus you will be able to explore the source code and to improve your knowledge and understanding of Wazaabi. You could find in this project the answers of many questions about Wazaabi.

Prerequisites

• Eclipse 3.2 or above

• JRE 1.4 or above

• Wazaabi plugins and prerequisites.

Install Lea Store

Wazaabi and Lea Store source code is stored on a subversion repository. A good way to use subversion in eclipse is to install the subclipse plug-in. Subclipse is an Eclipse plug-in that adds Subversion integration to the Eclipse IDE. Subclipse is licensed under the terms of the Eclipse Public License (EPL) 1.0. More informations at : http://subclipse.tigris.org/

The easiest way to install subclipse is to use the update manager provided by eclipse.

http://subclipse.tigris.org/update_1.2.x

Select “New Remote site” if subclipse update is not already configured.

Then follow the instructions and restart the workbench.

After restart you should be able to select the “SVN repository Exploring” perspective.

Configure the repository location for Wazaabi

Open the “SVN repository Exploring” perspective. Then, right-click on the “SVN Repository view”, select “New > repository location”, and fill in the repository URL field with this URL : http://svn.wazaabi.org/repos/wazaabi

Configure the repository location for Lea Store

Repeat step 2 with the Wazaabi examples repository URL, that holds Lea Store projects :

http://svn.wazaabi.org/repos/examples

You should see something like this:

To get Lea store sources in your Java perspective, checkout the “trunk” folder of every Lea Store projects :

org.wazaabi.examples.lea.store.*

Back in your Java perspective, you will see these projects.

The Lea Store product stands in the org.wazaabi.examples.lea.store.client project :

Run Lea Store

In the plug-in’s Manifest Overview tab of Lea Store, click the <Launch an Eclipse Application> link.

There it is !!!

First Wazaabi Application

Preface

This document was written using Eclipse 3.2 and Wazaabi 1.0.

The resulting project is available in the download area of the www.wazaabi.org website : wazaabi_1.0__FirstApp.zip.

Install Wazaabi

At this time, Wazaabi is distributed in one format.

Windows 2000/XP

Download the last Wazaabi distribution.

Unzip the downloaded file into your Eclipse directory.

Restart Eclipse.

See Installation chapter for other ways to install Wazaabi.

Hello World Program

Here are the steps you should follow to create a rich client application using Wazaabi framework. This application is the well known program “HELLO WORLD”.

Create the Wazaabi project

First create a plug-in project:

From the Eclipse Workbench menu, select 'File > New > Other...'

In the 'New' wizard, select 'Plug-in Project' and click Next.

Fill in the 'Project name' field with the name of your new project. Then click Next.

Do not use spaces or special characters in the project name.

Check the Rich Client Application option to create a rich client application: select Yes, and click Next.

In the 'Available Templates' list, select 'RCP application with a view', and click Next.

Fill in the Application window title field with the title of your future RCP application, and click Finish.

At this step the application is a full RCP application. It is not yet a Wazaabi application. Now you can open the manifest editor overview tab and execute your application by clicking the 'Launch an Eclipse application' link.

Configure the Wazaabi project

Dependencies

It is time to link your RCP project with Wazaabi framework.

In the plug-in's Manifest editor, select the Dependencies tab.

Use the 'Add...' button in the 'Required Plug-ins' section to add the org.wazaabi.glue.client plug-in.

Save the changes - press CTRL+S.

Activator

Open the Activator class of the plug-in, and modify its method as follows:

import org.eclipse.jface.resource.ImageDescriptor;
import org.eclipse.ui.plugin.AbstractUIPlugin;
import org.osgi.framework.BundleContext;
import org.wazaabi.core.config.IActivatorConfig;
import org.wazaabi.glue.client.GLUEClientPlatform;
import org.wazaabi.glue.client.catalogclient.CatalogClient;

public class Activator extends AbstractUIPlugin {

	private static Activator plugin;

	// Added for WAZAABI
	private static IActivatorConfig activatorConfig = null;

	public Activator() {
		plugin = this;
	}

	public void start(BundleContext context) throws Exception {
		// Added for WAZAABI
		activatorConfig = GLUEClientPlatform
				.configAndRegisterDefaultGLUEServices(context);
		super.start(context);
	}

	public void stop(BundleContext context) throws Exception {
		super.stop(context);
		plugin = null;
		// Added for WAZAABI
		activatorConfig = null;
	}

	public static Activator getDefault() {
		return plugin;
	}

	// Added for WAZAABI
	public static CatalogClient getCatalogClient(String catalogClientId) {
		if ((activatorConfig != null) && (catalogClientId != null))
			return (CatalogClient) activatorConfig.getServiceInstance(
					CatalogClient.class, catalogClientId);
		return null;
	}
}

Press CTRL+SHIFT+O to resolve and organize imports, and save pressing CTRL+S.

Chrome

With Wazaabi, views and editors are described in XML files via the XUL format. By convention, we will use the following folder structure in order to store our XUL files:

chrome/xul/views	Holds the XUL view files.
chrome/xul/editors	Holds the XUL editor files.
chrome/images	Holds image files.

Use the 'File > New > Folder' menu to create this structure in the project's root:

In the project root, create a WAZAABI-INF directory. In this directory, create a new file named 'wazaabi.properties' with the following contents :

chrome.authority.sample1=chrome/

In the plug-in's manifest editor, select the Build tab and check the 'chrome' directory in the 'Binary Build' section.

Press CTRL+S to save the changes.

Create a view

In the chrome/xul/views folder, create a file named 'mySampleView.xul' with the following contents:

<?xml version="1.0" encoding="ISO-8859-1"?>
<glue:viewpart part-name="title" 
                id="helloworldViewPart" 
                xmlns:glue="http://www.wazaabi.org/glue/1.0">
  <glue:content>
    <vbox flex="1" 
           id="helloworldBox" 
           xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
      <label value="hello world"/>
    </vbox>
  </glue:content>
</glue:viewpart>

Be careful to remove any space before the first line of this file.

Take notice this file contains our "hello world" label.

Save the changes

At this step, you may wish to refer to http://xulfr.org/xulplanet/xultu/ for improving this interface.

Now, it is necessary to declare this new view. In the plug-in's manifest editor, select the 'Extensions' tab and in the All Extensions section, highlight the node org.eclipse.ui.views

Right-click the org.eclipse.ui.views node and select new > view. Then, fill in the Extention Element Details fields like this :

id	chrome%3A//sample1/xul/views/mySampleView.xul
name	My Sample View
class	org.wazaabi.glue.client.rcp.ui.views.Viewpart

Be careful to write properly, the misspelling is a common error within Wazaabi.

Save the changes.

Now, we must add this view to our application's perspective. Edit the class org.wazaabi.examples.sample1.Perspective, and replace the whole code of the createInitialLayout() method with:

layout.addStandaloneView(
   "chrome%3A//sample1/xul/views/mySampleView.xul",false,
   IPageLayout.LEFT, 1f, IPageLayout.ID_EDITOR_AREA
);

Save the changes.

Run the application

In the plug-in's Manifest Overview tab, click the 'Launch an Eclipse Application' link.

The result is …

Make it a standalone application

At this point, your application is running inside the Eclipse Workbench. There is some more steps to make it a standalone application.

Please, notice this is a standard Eclipse process. We explain it in this document just for convenience.

Create a product

On your workbench, right-click on your project and choose 'New > Product Configuration'.

On the 'Product Configuration' wizard, fill in the 'File name' field with the name of the product file. For instance, sample1.product.

Click Finish.

In the Overview tab of the sample1.product editor, use the 'New...' button to specify the product identifier.

In the 'New Product Definition' dialog, fill in the 'Product Name' field with the name at choice. For example: 'sample1'.

In the 'Product Application' section, select your application: 'org.wazaabi.examples.sample1.application'.

Click Finish.

In the configuration tab of the 'sample1.product' editor, add your 'org.wazaabi.examples.sample1' plug-in and click the 'Add Required Plug-ins' button.

At this point, the product is correctly set up and it contains all the plug-ins required. You can test your product using the 'Launch the product' link of the Overview tab of the product editor. You can finally export it using the 'File > Export > Eclipse Product' menu.

Upgrade first Wazaabi application

Introduction

The Wazaabi Quick Start has shown you how to create a Wazaabi project. In this section, we will see how to upgrade this simple project to make it a real application.

Our target application is Lea-Store, the Wazaabi reference application.

As shown in the screen-shot below, Lea Store displays the list of a company’s offices cities. And for each of them, the list of the office’s employees. Then, a double-click on one employee's name opens an Eclipse view that shows the details about this employee.

Conventions for ease of deployment

Usually, Wazaabi is used for client-server applications, so it is useful to separate your application in 3 plug-ins at least: one for the client side, one for the server side and one for the common components.

Let’s rename our sample1 (hello world) project to org.wazaabi.examples.lea.store.client.

Don’t forget to rename the plug-in ID in the plug-in Manifest editor also.

You should rename the package name in the same way, in order to respect Eclipse RCP plug-ins conventions.

We will create presently two other projects called:

• org.wazaabi.examples.lea.store.service

• org.wazaabi.examples.lea.store.commons

Use your existing domain model

It is essential to understand that Wazaabi does not set any constraints on the domain model. Indeed, it is designed to work with any model, so you will be able to use your own existing model without any modification.

As an example, we will use the Lea Store domain model. The following figure shows a piece of this model:

Download the “wazaabi_1.0__UpgradeFirstAppMaterial.zip” archive in the www.wazaabi.org website download area.

This archive contains

• the Lea Store domain project,

• a light version of the Lea Store service project, that contains only a fake database for practice purpose.

• the Lea Store client project as it should be at this point of the tutorial.

Extract the archive into your Workspace and import the projects into your Eclipse Workbench.

Define the transport method

Wazaabi uses a transport driver to transport objects, or parts of objects through the network, between client application and server. The default transport driver works on HTTP but it is possible to make new drivers which use another protocol.

There are two transport drivers available in Wazaabi.

The “true http transport driver” is composed of two plug-ins: org.wazaabi.glue.client.transport.http for client part and org.wazaabi.glue.service.http for server part.

To use it, add the following instruction in the client “wazaabi.properties” file, located in the “WAZAABI-INF” directory of the client application:

catalogClient.http.transportLayer=org.wazaabi.glue.client.transport.http

#'http' transport layer needs to know the corresponding servlet's url.
catalogClient.http.httpServerUrl= http://host:port/wazaabi-servlet-url-pattern 

The org.wazaabi.glue.client.transport.notransport plug-in is provided for applications that do not need to transport data between client and server. For example:

• heavy weight clients that do not need any server,

• test applications in environments where no server is available.

To use it, add the following instruction in the client “wazaabi.properties” file, located in the “WAZAABI-INF” directory of the client application:

#set the default CatalogClient's transport layer
catalogClient.default.transportLayer=org.wazaabi.glue.client.transport.notransport

#'notransport' transport layer must know the bundle where the CatalogService is.
catalogClient.default.service=org.wazaabi.examples.lea.store.service

In our example, we will use this no-transport driver, because it does not require an http server. See the section “How to use the http transport driver” for details about configuring the true http transport driver.

Add the “no transport” plug-in into the client project dependencies :

Open the “Dependencies” tab of the org.wazaabi.examples.lea.store.client project's Manifest editor. Click the “Add” button to add the org.wazaabi.glue.client.transport.notransport plug-in.

Provide an Id provider for transported objects

The Wazaabi transport process requires an identification mechanism in order to track object instances correctly.

For instance, in Lea Store application we want to display the list of our company’s offices cities. And for each of them, the list of the office’s employees.

We will use a tree view with Offices as first nodes level and Employees as second node level.

In order to get nice performance, we want to display the Offices cities first, and to display the office employees list only if expanding the corresponding office node.

When expanding an office node, we will ask Wazaabi to get THIS office’s employees list on the server. That is to say, when expanding the Paris node, we want the Paris office employees, not the Boston’s employees. That’s why the Id providers are used for.

Id providers are commons objects used by Wazaabi both on client and server side.

Let’s create our new common project named “org.wazaabi.examples.lea.store.commons”. This project will contain our common objects and will be deployed both on the client and server side of the application.

• Open the new Project wizard and select “Plug-in project”.

• Fill-in the Project name field with “org.wazaabi.examples.lea.store.commons”

• In “Target Platform”, choose to target the plug-in to run with “an OSGi framework: standard”

• In “Plug-in Options”, uncheck the “Generate an activator, …” option.

In the “Dependencies” tab of the new plug-in’s Manifest editor, add the next dependencies:

• org.wazaabi.glue.commons

• org.wazaabi.examples.lea.store.domain

In the same way, add the “org.wazaabi.examples.lea.store.commons” plug-in to the dependencies of “client” and “service” plug-ins.

Create LeaStoreIdProvider class:

In the new “commons” project, create a new package named “org.wazaabi.examples.lea.store.commons.ids”.

In this package, create the LeaStoreIdProvider class that extends the Wazaabi IdProvider class:

package org.wazaabi.examples.lea.store.commons.ids;

import org.wazaabi.examples.lea.store.domain.Office;
import org.wazaabi.glue.commons.foundations.ids.IdContributor;
import org.wazaabi.glue.commons.foundations.ids.IdProvider;

public class LeaStoreIdProvider extends IdProvider {

	protected IdContributor[] getIdContributors(Class klass) {
		if(Office.class.isAssignableFrom(klass))
		{
			return new IdContributor[] { getIdContributor("officeCode",
					String.class) };
		}
		return null;
	}
}

The getIdContributors() method is used to define our object instance’s IDs. The implementation above identifies an Office object instance by its “officeCode” JavaBean property. Notice we use a two levels identification: the first level is the object class:

if(Office.class.isAssignableFrom(klass))

the second level is an instance property value:

new IdContributor[] { getIdContributor("officeCode", String.class) };

Notice also the return type is an IdContributor’s array, so that we can easily use several properties to make up our instance identifier.

For example, we could identify a Person instance using its “firstName+lastName+telephoneNumber” properties.

After saving the class, open the “Runtime” tab of the plug-in’s Manifest editor and add the “org.wazaabi.examples.lea.store.commons.ids” to exported packages. This will make it visible to other plug-ins.

Now, let’s configure Wazaabi to use our new IdProvider. This is done by adding this instruction in both client and server side wazaabi.properties files:

#set the default IdProvider
idProvider.default= org.wazaabi.examples.lea.store.commons.ids.LeaStoreIdProvider

The client file is located in the “WAZAABI-INF” directory of org.wazaabi.examples.lea.store.client plug-in. At this point, it should look like this:

chrome.authority.sample1=chrome/

#set the default CatalogClient's transport layer
catalogClient.default.transportLayer=org.wazaabi.glue.client.transport.notransport

#'notransport' transport layer must know the bundle where the CatalogService is.
catalogClient.default.service=org.wazaabi.examples.lea.store.service

#set the default IdProvider
idProvider.default= org.wazaabi.examples.lea.store.commons.ids.LeaStoreIdProvider

The server file has not been created yet. Create it in the “WAZAABI-INF” directory of “org.wazaabi.examples.lea.store.service” plug-in, with the following contents:

#set the default IdProvider
idProvider.default= org.wazaabi.examples.lea.store.commons.ids.LeaStoreIdProvider

Create a viewer

Each Wazaabi viewer encapsulates a JFace viewer and lets you to manage simply the data that will be retrieved and displayed from the server, allowing you to optimize network traffic and performance.

This is done via 2 simple objects associated to the viewer:

• A CatalogAspect, that retrieves model’s object instances that must be displayed in the viewer.

• A Facet, that tells which attributes of those objects must be really sent to the viewer. This is used to optimize network traffic. Notice that the finally displayed data is defined in the XUL file.

Create a CatalogAspect

The viewer uses a CatalogAspect to know which objects are implied in its display.

In our example, we want to display a tree box with the list of our company’s offices, and for each of them the list of the employees.

In order to display the list of Offices, we need a CatalogAspect that retrieves this list from the model.

The CatalogAspect class should be placed on the data side. In our case, the data are supposed to be stored in a server-side database. So we will create our class in our service project. In some case, the CatalogAspect must be in the client side. For example to manage an Internet Shopping Cart.

In the service project, create the next class which implements ICatalogAspect:

package org.wazaabi.examples.lea.store.service.catalogaspects;

import java.util.List;

import org.wazaabi.examples.lea.store.service.database.FakeDatabaseService;
import org.wazaabi.glue.commons.catalogaspects.ICatalogAspect;
import org.wazaabi.glue.commons.facets.IFacet;

public class OfficesCatalogAspect implements ICatalogAspect {

	public boolean hasChildren(Object authenticationContext, Object item) {
		return false;
	}

	public List getChildren(Object authenticationContext, IFacet facet,
			Object item) {
		if (item == null)
			return FakeDatabaseService.getInstance().getOffices();
		return null;
	}

	public Object getId() {
		return getClass().getName();
	}

	public Object getParent(Object authenticationContext, Object item) {
		return null;
	}
}

Take notice that you MUST provide content for the “getId()” method. As we will see, this ID is used to register the CatalogAspect and to identify it in the viewer configuration.

Create a CatalogAspectProvider

The ICatalogAspectProvider interface is used to register CatalogAspects in order Wazaabi to be able to use them.

DefaultCatalogAspectProvider is an ICatalogAspectProvider implementation which makes it easy to use.

Create the LeaStoreAspectProvider in the catalogaspects package …

package org.wazaabi.examples.lea.store.service.catalogaspects;

import org.wazaabi.glue.commons.catalogaspects.DefaultCatalogAspectProvider;

public class LeaStoreAspectProvider extends DefaultCatalogAspectProvider {

	public LeaStoreAspectProvider() {
		registerCatalogAspect(new OfficesCatalogAspect());
	}
}

… and declare it in the wazaabi.properties server file like this:

#set the default IdProvider
idProvider.default= org.wazaabi.examples.lea.store.commons.ids.LeaStoreIdProvider

glueService.catalogAspectProvider=org.wazaabi.examples.lea.store.service.catalogaspects.LeaStoreAspectProvider

Create a Facet

Facets classes are used both on server and client. So they should be placed inside the commons project.

The only thing to do is to declare which attribute you want to display. Create the new OfficesFacet class into the new org.wazaabi.examples.lea.store.commons.facets package:

package org.wazaabi.examples.lea.store.commons.facets;

import org.wazaabi.examples.lea.store.domain.Office;
import org.wazaabi.glue.commons.facets.IFacet;

public class OfficesFacet implements IFacet {

	public String[] getPropertyNames(Class clazz) {
		if (Office.class.getName().equals(clazz.getName()))
			return new String [] {"city", "postalCode"};
		return null;
	}

}

After saving the class, open the “Runtime” tab of the plug-in’s Manifest editor and add the “org.wazaabi.examples.lea.store.commons.facets” to exported packages. This will make it visible to other plug-ins.

See also How to format information and How to define a custom FormattedLabelProvider.

Create the Viewer

Since we have a CatalogAspect and a Facet, we are ready to put it all together inside the viewer’s definition.

Here we will use the Wazaabi DefaultTreeViewer which manages the JFace CheckboxTreeViewer. It is important to notice that we don’t have to know nothing at all about this JFace component, because we will not use its API. Instead, we will use the XUL language which is much easier to understand.

First, create a new org.wazaabi.examples.lea.store.client.viewers package to hold our OfficesViewer class:

package org.wazaabi.examples.lea.store.client.viewers;

import org.wazaabi.examples.lea.store.commons.facets.OfficesFacet;
import org.wazaabi.glue.client.viewers.DefaultTreeViewer;
import org.wazaabi.xwt.xul.trees.Tree;

public class OfficesViewer extends DefaultTreeViewer {

  public OfficesViewer(Tree tree) {
    super(tree);
    attachRemoteCatalogAspect(
    "org.wazaabi.examples.lea.store.service.catalogaspects.OfficesCatalogAspect");
    setFacet(new OfficesFacet());
    setInput(EMPTY_MODEL);
  }
}

Then, update the “chrome/xul/views/mySampleView.xul” XUL file in order to declare our tree widget:

<?xml version="1.0" encoding="ISO-8859-1"?>
<glue:viewpart part-name="title" 
               id="helloworldViewPart" 
               xmlns:glue="http://www.wazaabi.org/glue/1.0">
<glue:content>
  <vbox flex="1" 
        id="helloworldBox" 
        xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
    <label value="hello world"/>
     <tree flex="1" id="demo" 
     viewer="urn:java:org.wazaabi.examples.lea.store.client.viewers.OfficesViewer" 
     linesVisible="true">
      <treecols>
         <treecol flex="1" />
         <treecol flex="1" />
      </treecols>
    </tree>
  </vbox>
</glue:content>
</glue:viewpart>

Run the application

At this point, if you run the application, you will get an error telling that the wazaabi.properties server file has not been found. This is because we didn’t tell Eclipse to load our service plug-in, which is needed because we use the “no transport” plug-in.

Open the “Run > run…” menu and select your “Eclipse Application” launch configuration. Then, select the “Plug-ins” tab and check the “org.wazaabi.examples.lea.store.service” plug-in.

Click the “Apply” and “Run” buttons to save the configuration and run the application.

Add one level to the Tree Viewer

As we said before, we want to list every Office's employees when expanding an Office node of our Tree Viewer.

It's done in four steps :

1. Update the IdProvider

2. Update the CatalogAspect

3. Update the Facet