TechJava» TechJava – Articles on java

Extending Xtext Build Participants

Simon Zambrovski — Thu, 17 Jun 2010 10:41:21 +0000

You’ve definitely heard about Xtext, the famous text modeling framework, community award winner . We are all looking forward to the new project management wonder: the release of Helios, upcoming on June the 23rd, which will include Xtext 1.0.0. In this article, I want do describe some aspects of integration of Xtext-based languages into IDE.

Introduction

Creating your own domain-specific textual languages in Xtext is really easy, and the authors in Northern Germany are doing a good job to make it even easier. Once you have a language, you want to process it and this means usually to transform your model into another representation. The facility responsible for this transformation is called generator and consists of a bunch of transformation templates (e.G. XPand) and some code executing them. On some event, the model is read in and the transformations are applied to produce code. Currently, there are two ways of triggering the transformation: you can put the calling infrastructure in a Modeling Workflow Engine file, which is a kind of batch script or you can write a build-participant, which react on the changes in the model. In this article I want to describe my experiences with the builder approach.

Examining initial builder

The base idea behind the builder approach is the fact, that Xtext provides an project builder, which watches for all Xtext resource changes (Xtext-based DSL models) and notifies the so-called XtextBuilderParticipants. These are registered using Eclipse extension point org.eclipse.xtext.builder.participant and implement the IXtextBuilderParticipant interface:

...
public interface IXtextBuilderParticipant {
    void build(IBuildContext context, IProgressMonitor monitor) throws CoreException;
}

public interface IBuildContext {
    IProject getBuiltProject();
    List getDeltas();
    ResourceSet getResourceSet();
    void needRebuild();
}

In order not to start completely from scratch, let us examine the builder provided in the Domain-Model-Example, delivered with Xtext. In the build method the example builder processes as follows:

checks that the project is a Java project
finds the generation folder
creates an Output
creates an Outlet and registers it in the Output
registers a post-processor managing Java imports on the outlet
creates the Xpand execution context
registers the Java Beans version of the metamodel
processes the changes and analyses if the files have to be deleted or not prior re-generation
for all changed model elements re-generates

Quite a lot of tasks, so there is a good reason, why MWE scripts are used for generation.

Using Project natures

The first improvement I created for the builder is the ability to distinguish DSLs. The problem of triggering all XtextBuildParticipants on the change of any Xtext-based resource is that the entire Workspace gets re-generated. In my scenario, we used three DSLs and a random change caused three builders to run, even if the change has been made in another project of workspace. In order to solve this problem I used the standard Eclipse way to distinguish projects: Project Natures.

The nature I created is used as a marker for the builder and is emtpy:

public class UiNature implements IProjectNature {
	public static final String NATURE_ID = "de.techjava.dsl.uiNature";
	private IProject project;

	public void configure() throws CoreException {
        }

	public void deconfigure() throws CoreException {
	}
	public IProject getProject() {
		return project;
	}
	public void setProject(IProject project) {
		this.project = project;
	}
}

Don’t forget to register it in the plugin.xml:

As the first line in my builder I check the presence of the nature in the current project and stop building if the nature is not present:

if (!context.getBuiltProject().hasNature(UiNature.NATURE_ID)) {
	// skip projects without UI DSL nature
	return;
}

Now, what is missing is the ability to add and remove the nature to/from the project. I liked the way how Xpand/Xtend Natures are configured (using toggle action in configure menu of the project pop-up menu). What you need is a ToggleAction that can be switched on, if the nature is not present and switched off, if the nature is installed.

public class ToggleNatureAction implements IObjectActionDelegate {
	private ISelection selection;
	@SuppressWarnings("unchecked")
	public void run(IAction action) {
		if (selection instanceof IStructuredSelection) {
			for (Iterator it = ((IStructuredSelection) selection).iterator(); it.hasNext();) {
				Object element = it.next();
				IProject project = null;
				if (element instanceof IProject) {
					project = (IProject) element;
				} else if (element instanceof IAdaptable) {
					project = (IProject) ((IAdaptable) element).getAdapter(IProject.class);
				}
				if (project != null) {
					toggleNature(project);
				}
			}
		}
	}

	public void selectionChanged(IAction action, ISelection selection) {
		this.selection = selection;
	}

	public void setActivePart(IAction action, IWorkbenchPart targetPart) {
	}

	/**
	 * Toggles sample nature on a project
	 * @param project to have sample nature added or removed
	 */
	private void toggleNature(IProject project) {
	// implemetation of toggle nature ...
	}
}

In order to make an action to a toggle-action the Eclipse Command Framework, Object Contributions and the Command Core Expressions are needed. The idea is to register two actions as object contributions on the IProject using the org.eclipse.ui.popupMenus extension point and define visibility of those to be complement to each other (if one is visible the other is not) based on the object state, which is the presence of a project nature. The actions used point to the same implementation class but have different labels. The menu path to pop-up menu Project > Configure is org.eclipse.ui.projectConfigure/additions. The visibility is defined based on the objectState:

Please note, that the nature is implemented and registered inside of the generator project and the toggle action is implemented in the UI project. Finally, the code of the toggleNature method, which is the standard code for the project nature installation and removal:

...
	IProjectDescription description = project.getDescription();
	String[] natures = description.getNatureIds();

	// remove the nature
	for (int i = 0; i < natures.length; ++i) {
		// if nature exists
		if (NATURE_ID.equals(natures[i])) {
			// Remove the nature
			String[] newNatures = new String[natures.length - 1];
			System.arraycopy(natures, 0, newNatures, 0, i);
			System.arraycopy(natures, i + 1, newNatures, i, natures.length - i - 1);
			description.setNatureIds(newNatures);
			project.setDescription(description, null);
			return;
		}
	}

	// Add the nature
	String[] newNatures = new String[natures.length + 1];
	System.arraycopy(natures, 0, newNatures, 0, natures.length);
	newNatures[natures.length] = NATURE_ID;
	description.setNatureIds(newNatures);
	project.setDescription(description, null);
...

That’s it, run and right-click on the Project and then go to the Configure Menu (pretty low in the pop-up) and you will see the result:

Parameterizing generator

Domain-specific languages should cover only the real requirements and incorporate the specific decision made in the project. So far the theory, but in fact it is a trade-off and a compromise, what is a part of the language and what is too specific to be covered. The same holds for the generator: on the one hand you want the generator to solve exactly your problem, on the other hand you want to make it generic enough to cover a class of similar problems.

I faced the problem of using the generator for two teams in a big project, where the langage could be reused, but the generation infrastructure need to be slightly modified. For example, the information about the generation target folder, package prefix and the fact which artifact should be generated differred between the teams. In the same time the teams were able to agree on the same language. In order not to develop two generators, I decided to parameterize the generator and the templates.

The Xpand2/Xtend developers provided a way of parameterization of the templates using the so-called Global Variables, using the GLOBALVAR keyword. My favorite way of using it is to create a cached extension for reading the variable:

/*
 * Retrieves the boolean value of the global variable set from outside of the template
 */
cached Boolean generateService() :
    GLOBALVAR generateService == "true"
;

In order to set global variables from the build participant the XPand execution context constructor takes a Map argument. The nice story about the global variables, that you can provide any objects as values. So the advantage over the usage of MWE workflow with property files read-in during processing is the big flexibility in providing the object-graphs or even statefull objects as global variable values. A good example of usage of global variable is provided in Domain-Example with Java Import Tool:

JavaImportsTool importsTool = new JavaImportsTool();
...
ctx = new XpandExecutionContextImpl(output, null,
    Collections.singletonMap(JavaImportsTool.VAR_NAME,
    new Variable(JavaImportsTool.VAR_NAME,importsTool)),
    null, null);
...

In the same time it is important to be able to load simple properties from file in the generation project. For example you could implement your own ModelProperties container, which reads properties from the file located in the generation project. For example:

public class ModelProperties extends Properties {
	/**
	 * Indicates that no timestamp is available
	 */
	private static final long NO_TIMESTAMP = -1;

	private long lastModified = NO_TIMESTAMP;
	private final IFile propertyFile;
	private final HashMap globalVars;

	/**
	 * Creates a valid model properties instance
	 *
	 * @param aProject reference to the current project
	 * @param name of the property file
	 * @throws CoreException on errors
	 */
	public ModelProperties(final IProject aProject, String filename) throws CoreException {
		if (aProject == null) {
			ErrorHelper.throwCoreException("project must be not null");
		}
		if (filename == null) {
			ErrorHelper.throwCoreException("filename must be not null");
		}
		this.globalVars = new HashMap();
		this.propertyFile = (IFile) aProject.findMember(filename);
	}

	public IFile getPropertyFile() {
		return propertyFile;
	}

	/**
	 * Returns the global variables.
	 * @return global variables.
	 */
	public Map getGlobalVars() {
		updateProperties();
		return globalVars;
	}

	@Override
	public String getProperty(String key) {
		updateProperties();
		return super.getProperty(key);
	}

	/**
	 * Updates the properties and the global variables if the property file has
	 * been modified.
	 */
	public void updateProperties() {
		if (this.propertyFile != null && lastModified != this.propertyFile.getModificationStamp()) {
			loadProperties();
			globalVars.clear();
			for (Map.Entry entry : entrySet()) {
				final String propertyName = (String) entry.getKey();
				globalVars.put(propertyName, new Variable(propertyName, entry.getValue()));
			}
		}
	}

	/**
	 * Loads the properties from the model file
	 */
	private void loadProperties() {

		try {
			if (propertyFile != null && propertyFile.exists()) {
				super.load(propertyFile.getContents());
				this.lastModified = propertyFile.getModificationStamp();
				handleSpecialProperties();
			}
		} catch (CoreException e) {
			// no model property file isn't a problem but clear the properties:
			super.clear();
			this.lastModified = NO_TIMESTAMP;
		} catch (IOException e) {
			super.clear();
			this.lastModified = NO_TIMESTAMP;
		}
	}

	protected void handleSpecialProperties() {

	}
}

Using this class you can simple initialize the XPandExecutionContext with properties read from the file system. So in build-Method of your Generator put something like:

         ModelProperties structureProperties = new ModelProperties(context.getBuiltProject(), "structure.properties");
         XpandExecutionContextImpl ctx = new XpandExecutionContextImpl(output, null, structureProperties null, null);

Now you can resolve the values from the property files directly from the Templates and Extensions using the built-in GLOBAL VAR feature.

Parameterized classes, arrays and varargs

Simon Zambrovski — Wed, 02 Jun 2010 14:30:00 +0000

Yesterday, I discovered a funny nuance in Java programming language, which I didn’t know before and decided to share it with you. I was designing an API for transport of changes in relationships between two DTO types. Since I wanted to support batch changes, I created the class for carrying these:

class ManyToManyDelta, T extends BaseDto> {

  List> relationshipsToAdd;
  List> relationshipsToRemove;
  ...
}

class SimpleRelationship, W extends BaseDto> {

  // BaseDto classes are identified by the parameterized Id
  Id left;
  Id right;

  SimpleRelationship(BaseDto one, BaseDto another) {
    left = one.getId();
    right = another.getId();
  }
}

Having this structure, you can model the relationship between two instances of types A and B by an instance of SimpleRelationship. If you want to communicate the creation of a relationship you would put the latter into the relatioshipToAdd list, if you want to model the deletion, you would put it into the relatioshipToRemove list.

Now I it was time to develop methods for access of the relationship lists inside of the ManyToManyDelta:

class ManyToManyDelta~~, T extends BaseDto> { ... public void add(SimpleRelationship toAdd) { if (toAdd == null) { /* react */} this.relatioshipToAdd.add(toAdd); } ... }~~

You could think that you have a batch update (e.g. an Array or List) of SimpleRelatioship objects you would like to add them by one invocation instead of a series of invocation. e.G:

class ManyToManyDelta, T extends BaseDto> { ... public void add(SimpleRelationship[] toAdd) { if (toAdd == null) { /* react */} this.relatioshipToAdd.addAll(Arrays.asList(toAdd)); } public void add(SimpleRelationship toAdd) { if (toAdd == null) { /* react */} this.relatioshipToAdd.add(toAdd); } ... }
Using the varargs feature of Java you could also write equivalent:

class ManyToManyDelta~~, T extends BaseDto> { ... public void add(SimpleRelationship... toAdd) { if (toAdd == null) { /* react */} this.relatioshipToAdd.addAll(Arrays.asList(toAdd)); } ... }~~

That would be nice, right? By the way, it is a good idea, to write some client code, during the development of API. This discovers potential problems:

... A entityA = ...; B entityB = ...; ManyToManyDelta delta = new ManyToManyDelta(); delta.add(new SimpleRelationship(entityA, entityB));

Coding this result in a type safety warning: A generic array of SimpleRelationship is created for a varargs parameter. Which reveals a problem in a Java language: you can not create an array of parameterized types. And resulting from this fact, you can not use that as varargs argument.

Finally, if you want to create convenience methods for one and many items, you have to do it in a old-fashined way, by providing overloaded methods.

JSF 2.0 Reality Check

Simon Zambrovski — Mon, 22 Feb 2010 21:50:42 +0000

Abstract

The JavaServer Faces (JSF) 2.0 is the newest Java presentation technology that is covered in JSR-314 and was publicly released on July 01, 2009. It became a part of the JEE6 standard and can be comfortably used in conjunction with other JEE frameworks, with Spring or just on its own. This article reveals the possible scenarios and shows the required configuration for the usage of JSF 2.0 with EJB 3.1 and with Spring 3.0. It also discusses several auxilary technologies which can be used along with JSF 2.0.

Management Summary

There are many presentation frameworks available, so why JSF 2.0? The short answer is simple: it has an extensible component-oriented presentation layer and event-driven programming model, which both abstract from HTML/JS and leverage the developement. In more detail, the most important features are:

Facelet Support

Validation & Conversion Mechanisms

Resources Support

Templating

Expression Language

Annotation Support

JSF 2.0 makes strong use of the SoC (Separation of Concerns) principle, promoting the MVC (Model View Controller) design pattern. Its declarative view is based on facelets: the view documents can be defined using XHTML. These documents build their own component tree from the core or third-party components. The use of special composition elements allows effective templating. The model or/and the controller are realized using so called backing beans / managed beans. A backing bean is an annotated POJO (Plain Old Java Object). The access from the view to the backing beans is possible using the expression language. The navigation can be influenced directly from the view or from the backing beans, by pointing to the logical names of the pages. JSF offers a flexible validation model, which suports Bean Validation (JSR 303) out of the box.

Presentation with JSF 2.0

This chapter discusses the model of the presentation used in JSF 2.0.

Initial setup

A JSF project is an ordinary Java Web project. The result of it runs inside of a web container, like Tomcat or Jetty. A characteristical descriptor has to contain the servlet definitions/mappings of the JSF servlet and third-party component servlets. Here is an exammple for JSF 2.0 and Prime Faces, an open-source component library.

... com.sun.faces.expressionFactory com.sun.el.ExpressionFactoryImpl Faces Servlet javax.faces.webapp.FacesServlet 1 Resource Servlet org.primefaces.resource.ResourceServlet 1 Faces Servlet *.jsf Resource Servlet /primefaces_resource/* ...

The View

The definition of a JSF presentation is relatevely simple. Just create a simple XHTML document and import the JSF namespaces in the header.

#{msgs.welcomeTitle} ...

Please note, that along with the JSF core components, the PrimeFaces component dataTable is used. At runtime the components will be transformed into the corresponding HTML elements.

The Backing Bean

In the previos example, special strings have been used #{customerProvider.customers} and #{customer.name}. Both of them are expressions specified in the Expression Language. This language allows to address elements known inside the application. The customer.name accesses the property name of the variable defined inside the iteration over the elements delivered from the customerProvider.getCustomers(). The customerProvider is a Java Object that delivers data to the view and is called Backing Bean. A Backing Bean is a serializeable POJO, that is attached to the view. It can be declared using JSF Annotation javax.faces.ManagedBean, using the ManagedBean element of the faces-config.xml or by other mechanisms compatible with the Expression Language resolvers.

@ManagedBean @SessionScope public class CustomerProvider { public List getCustomers() { ... } }

Internationalization

Internationalization is an important requirement for the presentation layer. In the previous example, a special string has been used #{msgs.welcomeTitle} to provide a message. The msgs variable is bound to a resource file, containing the localized messages, so the #{msgs.welcomeTitle} is pointing to the key welcomeTitle inside the property file.

Validation

Input validation is another important requirement for web applications. Especially, the ability to validate parts of the input using technologies like AJAX has to be supported in order to deliver the state-of-the-art technology. JSF fosters numerous different validation approaches. For example:

... ...

Please note, that in the example above, the input of the customer name is mandatory and the minimum length is seven.

Another validation approach is defined in the Bean Validation Standard (JSR 303) and is supported if the components are deployed and available. According to JSR 303, the data container can define format constraints which can be used for purposes of validation. There is a set of predefined constraints available, which can be extended by custom constraints. For example:

public class Customer { @Size(min=2, max=50, message= "Customer name must be at least 2 and at most 50 characters long. ") private String name; // getters and setters ... }

This example shows that the customer name has to be at least two and at most fifty characters long and defines a custom error message which is displayed on violation. Remember the previous section Internationalization? Yes, the validation error message can be localized too, by suppliying EL-expressions instead of the message description:

public class Customer { @Size(min=2, max=50, message= "{customerNameError} ") private String name; // getters and setters ... }

Thus, the value of {customerNameError} (without a #) is a key in the file which must be named ValidationMessages.properties and must be available on classpath.

JSF 2.0 with other frameworks

The use of JSF fosters comfort in implementing the presentation tier. The presentation-tier is usually built on top of the business logic layer. The latter can be implemented using different technolgies.

JSF 2.0 and EJB 3.1

Enterprise Java Beans is a standard way to implement business logic inside JEE applications. The current EJB 3.1 specification fosters the usage of Stateless and Statefull Session Beans for this purpose. Since JEE6-compliant servers support Context and Dependency Injection (CDI) and the EJB and Resource Injection, the session beans can be directly referenced from the backing beans. JSF 2.0 is also a part of the JEE 6, every JEE-compliant server will support JSF out-of-the-box, too.

@ManagedBean public class CustomerProvider { @EJB private CustomerService service; ... }

JSF 2.0 and Spring 3.0

If you don’t want to run a full-blown JEE server, but a web-container only, you have to include some libraries into your application deployment.

JSF 2.0 API and Implementation: e.g. Mojarra 2.0.2 ( mojarra-2.0.2-FCS-binary.zip)

Expression Language 2.2 API and Implementation: el-api-2.2.jar, el-impl-2.2.jar

Content and Dependency Injection (CDI, JSR 330) API and Implementation: javax.inject.zip

Bean Validation (JSR 303) API and Implementation: e.g. Hibernate Validator ( hibernate-validator-4.0.2.GA-dist.zip)

This list will be extended by libraries required to run the Spring framework. In order to activate Spring, the context listeners have to be activated. The application context parameter can be provided as a context parameter.

org.springframework.web.context.ContextLoaderListener org.springframework.web.context.request.RequestContextListener contextConfigLocation /WEB-INF/spring-config.xml

In addition, the Expression Language variable resolvers of JSF should be replaced by those from Spring. This is configured in the faces-config.xml

org.springframework.web.jsf.el.SpringBeanFacesELResolver

In order to enable the Spring’s IoC (Inversion of Control), we need to activate the component scan in the application-context configuration file:

Instead of using JSF for resolving the backing beans, the Spring framework can be used. The backing bean is annotated with the Spring annotation Controller. The controller is a special kind of Spring component, which is used in the presentation layer. The Spring’s way of implementing business logic is to provide Spring services. Spring service has to be annotated with Service annotation.

@Controller @Scope( "session ") public class CustomerProvider implements Serializable { @Inject private CustomerService customerService; ... } @Service @Scope( "singleton ") public class CustomerServiceImpl implements CustomerService { ... }

This is not as elegant as inside the JEE server, but it will work.

References

JSR 303: Bean Validation

JSR 330: Dependency Injection for Java

JSR 330 with Spring (in German)

Mojarra Project

Expression Language API

Expression Language Implementation

Hibernate Validator (JSR 303 Implementation)

AtInject (JSR 330 Implementation)

Real World Java EE Practices – Rethinking Best Practices by Adam Bien

Simon Zambrovski — Tue, 02 Feb 2010 23:21:43 +0000

I just returned from the furious event given by Adam Bien on Real World Java EE Practices. The presentation has been held in Lehmanns Bookstore in Hamburg in co-operation with the JUGHH. It was a full success with no space left in the bookstore. I think, I got the last seat and there were some people standing.

Adam made it in an hour and presented many interesting topics. He started with new subjects introduces in JEE6, like optional local interfaces, cronjob-like Timer Service and other nice goodies. Then he covered new stuff from JEE like REST and CDI (Context and Dependency Injection). Finally, he moved to the best practices, patterns and anti-pattern. As usual, it was quick and precise – Adam answered many questions and gave a good overview of the technology.

After the presentation, JUGHH / Lehmanns offer a glass of sparkling wine for the smaller audience and Adam spoke about the possibility to speak about JavaFX next time. This time I left my camera at home and only had my phone with me, so sorry for the low-resolutioned picture…

Exposing Functionality using Web Services and JEE

Simon Zambrovski — Thu, 07 Jan 2010 11:11:22 +0000

Abstract

About two years ago, I published an article about Exposing the Functionality implemented in Stateless Session Beans (EJB 2.1) using Web Services. J2EE 1.4 times are over and the new version of the Java Enterprise framework, called Java Enterprise Edition 5 (JavaEE 5, or simply JEE) has emerged. In this article the same business scenario is repeated in the new framework.

Requirements

Before we dive into code examples, some software is required. The good news about the software is, that it also evolved over time. Here is what we use:

Sun’s Java 6 SDK

JBoss AS 5.1.0 GA for JDK6

Eclipse Galileo 3.5.1 for JEE development

Some words about the used software. It is important to get the JDK6-compiled version of the JBoss Application Server. There are some issues with running the version compiled with Java 5 on JDK6, since JDK6 has its own JAX-WS implementation which causes problems with JBoss (affected should be all versions of JBoss < 5.2. Currently it seems like version 5.2 will be compiled with JDK6 by default.) If you launch JBoss from Eclipse, make sure to add the -Djava.endorsed.dirs=PATH_TO_JBOSS/jboss-5.1.0.GA/lib/endorsed as a VM argument, if launched from the command line, please add it as an option inside of the run.conf.bat file:

set "JAVA_OPTS=%JAVA_OPTS% -Djava.endorsed.dirs=$JBOSS_HOME/lib/endorsed"

Otherwise you will get the following exception:

java.lang.UnsupportedOperationException: setProperty must be overridden by all subclasses of SOAPMessage

After installation (unpacking) of Eclipse, make sure to configure the JDK (under Preferences > Java > Installed JREs) and the JBoss instance (Preferences > Server > Runtime Environment).

Use Case

In order to demonstrate the technology by example, imagine the following use case. The system under construction is capable of providing measurements of some sensors. The sensors are identified by numbers and can be queried by the user by providing the timespan of measurements. As a result, the systems delivers the set of measurements for the given timespan with one measurement per minute but at most sixty measurements. Every measurement contains the id of sensor from which it has been recorded, the timestamp, the value as a byte array, the measurement unit and finally a flag whether the measurement exceeds the limits or specified alarm values.

Implementation

We start the implementation with the creation of a JEE Session Bean and then expose the functionality using a second Facade bean. In doing so we follow the EJB 3 specification.

Eclipse for Java EE development

The plugins in Eclipse for Java EE provide massive support and foster the development by deep integration withe JEE servers. Instead of a simple Java Project, start with an Enterprise Application Project. Then, create a new EJB Project and add it to the created Enterprise Application Project. In order to deploy the resulting application to the server, right-click on the enterprise project and select Run As > Run on Server .

To check the deployment on the application server, use the JBoss Consoles. These can be accessed via http://localhost:8080/ for the locally installed JBoss. An additional Web Service Console is accessible via http://localhost:8080/jbossws/.

Implementing the Functionality

In order to implement the functionality in a stateless session bean, we start with the creation of the business interface.

/** * Defines the sensor manager functionality */ public interface SensorManager { /** * Retrieve sensor data * @param sensorId id of the sensor * @param timespan the measurement period * @return a list of measurements in the given period * @throws SensorManagerException on any kinds of errors */ public List getSensorData(SensorID sensorId, Timespan timespan) throws SensorManagerException; }

The POJOs Measurement, SensorID and Timespan are used to show the usage of custom user types:

public class Measurement { private SensorID sensorID; private Date timestamp; private boolean critical; private byte[] value; private String unit; ... // getters and setters } .... public class SensorID { private long sensorId; ... // getters and setters } public class Timespan { private Date start; private Date end; ... // getters and setters }

After the creation of the business interface, let us create the actual Session Bean. The class is annotated with the @javax.ejb.Stateless annotation in order to indicate that the bean is a Stateless Session Bean. Since it implements the business interface (and only it), the container will be able to deduce that the given interface is the Local Business interface: this is just one of many examples of the Configurations by Exception in EJB 3. In order to be able to reference the bean from other beans, we annotate the binding of the local interface to a specific JNDI name using the vendor-specific annotation org.jboss.ejb3.LocalBinding.

@Stateless @LocalBinding(jndiBinding="de.techjava.sensor/SensorManager") public class SensorManagerBean implements SensorManager { /** Logging facility */ protected static Logger LOG = Logger.getLogger(SensorManagerBean.class); /** Max number of returned values */ private static final long MAX_DURATION = 60; /** * Implementation of the business method */ public List getSensorData(SensorID sensorId, Timespan timespan) throws SensorManagerException { LOG.debug("Entering getSensorData()"); if (sensorId == null || timespan == null || timespan.getStart() == null || timespan.getStart() == null) { throw new SensorManagerException("Missing a mandatory parameter, that was null (not set)"); } else if (!timespan.getStart().before(timespan.getEnd())) { throw new SensorManagerException("The timespan is defined by the start that should be before end"); } List measurements = new LinkedList(); for (long i = 0; i < getNumberOfElements(timespan); i++) { Date date = new Date(); date.setTime(timespan.getStart().getTime() + i * 1000 * 60); if (date.after(timespan.getEnd())) break; Measurement measurement = createMeasurement(sensorId, date, i); measurements.add(measurement); } LOG.debug("Leaving getSensorData(). Returning " + measurements.size() + " values."); return measurements; } /** * Retrieves the number of measurements in timespan */ private long getNumberOfElements(Timespan timespan) { ... } /** * Creates a measurement instance, a dummy implementation */ private Measurement createMeasurement(SensorID sensorId, Date timestamp, long number) { ... } }

Web Service Definition

The quality of the web service interface is an important design consideration. As described in the previous post, in many cases it is a good idea to create it by hand instead of generation by a tool. In this particular case, we create another annotated Stateless Session Bean, which is used as a Facade and contains all Web Service-specific settings. From this Bean we generate the WSDL and then tune it in order to show the capability of the customization. In doing so we try to match the WSDL from the previous example as close as possible.

Firstly, we create the business interface and the bean class, then annotate it and finally add the code delegating the Web Service request to the SensorManager.

public interface MeasurementProviderFacade { public List getSensorData(SensorID id, Timespan timespan) throws SensorDataOperationFault; } ... @Stateless public class MeasurementProviderFacadeBean implements MeasurementProviderFacade { public List getSensorData(SensorID id, Timespan timespan) throws SensorDataOperationFault { ... // implementation code } }

In order to have a Session Bean exposed as a Web Service, the JAX-WS specification defines a set of annotations. The most important two are @javax.jws.WebMethod and @javax.jws.WebService. The @WebService annotation is used to mark the class to be exposed e.G.

@Stateless @WebService( serviceName = "MeasurementProviderService", name = "MeasurementProviderPortType", portName = "MeasurementProviderPort", targetNamespace = "http://www.techjava.de/2010/ws4jee/measurement/" ) public class MeasurementProviderFacadeBean implements MeasurementProviderFacade { @WebMethod( operationName="GetSensorDataOperation", action="http://www.techjava.de/2010/ws4jee/measurement/GetSensorDataOperation" ) public List getSensorData(SensorID id, Timespan timespan) throws SensorDataOperationFault { ... } }

All the attributes of the annotation are optional and their values will be derived from the classname and the name of the business interface. The default target namespace for the service definition is derived from the package name, the annotated class is located in. By default, all public methods of the annotated class will be exposed as WSDL operations, with operation’s name derived from the method name. Using the @WebMethod annotation, the name of the WSDL operation and the SOAP action can be changed.

The careful reader might have observed that the getSensorData-method is throwing an exception. In order to map the exception to a SOAP-Fault, the javax.xml.ws.WebFault class-level annotation can be used. The faultBean attribute is used to provide the full-qulified class name of the exception.

... @WebFault( name="GetSensorDataFault", targetNamespace="http://www.techjava.de/2010/ws4jee/measurement/", faultBean="de.techjava.sensor.bean.SensorDataOperationFault") public class MeasurementProviderFacadeBean implements MeasurementProviderFacade { ... }

In order to increase the quality of the WSDL further, the method parameters and return type can be annotated with javax.jws.WebParam and javax.jws.WebResult respectively, so the method signature becomes a little unreadable. In order not to copy the long string containing the taget namespace a String constant can be used.

... public final static String TYPES = "http://www.techjava.de/2010/ws4jee/measurement/types/"; ... @WebResult(name="measurement", targetNamespace=TYPES) public List getSensorData( @WebParam(name="sensor-id", targetNamespace=TYPES) SensorID id, @WebParam(name="timespan", targetNamespace=TYPES) Timespan timespan) throws SensorDataOperationFault { ... }

Finally, in order to force the marshaller / unmarshaller to map the custom data types (Measurement, SensorID and Timespan) to belong to the same namespace, the JAX-B class-level annotation javax.xml.bind.annotation.XmlType has to be used. By default, the datatypes will be mapped to XML Schema types according to their package name and class name.

@XmlType(namespace = "http://www.techjava.de/2010/ws4jee/measurement/types/", name = "TimeSpan", propOrder = { "start", "end" }) public class Timespan { private Date start; private Date end;

If deployed to the JBoss, the resulting WSDL looks as following:

Please note, that the domain datatypes are mapped to the different namespace as the target namespace of the Web Service.

After some tuning the WSDL, like changing the cardinality of elements (minOccurs = 1, maxOccurs = 1) or adding comments we can let the container use the changed WSDL file instead of generating a new one. In order to do this, let us package the WSDL together with the source code. A good place for it is for example /META-INF/wsdl/, so we can provide a reference to it in an wsdlLocationattribute of the @WebService annotation:

@WebService( ... wsdlLocation="META-INF/wsdl/MeasurementProviderService.wsdl" )

Putting all together

After the creation of the Facade Bean and its exposure as a Web Service, we need to delegate the call to the SensorManagerBean, providing the actual implementation. In order to do so, add a private member of type SensorManager inside of the facade bean and annotate it with the javax.ejb.EJB annotation. The container will intialize the member using Dependency Injection and provide a valid reference which can be simply used inside of the method.

... public class MeasurementProviderFacadeBean implements MeasurementProviderFacade { @EJB(mappedName="de.techjava.sensor/SensorManager") private SensorManager sensorManager; /** * Simple delegate to the business method of the sensor manager */ @WebMethod( operationName="GetSensorDataOperation", action=TNS + "/GetSensorDataOperation" ) public @WebResult(name="measurement", targetNamespace=TYPES) List getSensorData( @WebParam(name="sensor-id", targetNamespace=TYPES) SensorID id, @WebParam(name="timespan", targetNamespace=TYPES) Timespan timespan) throws SensorDataOperationFault { try { return sensorManager.getSensorData(id, timespan); } catch (SensorManagerException e) { throw new SensorDataOperationFault("Error accessing the Sensor Manager: " + e.getMessage() + ""); } } }

Here is the call in Web Service Explorer:

Outline

In this article we showed how to expose the functionality implemented in an EJB 3 Session Bean using Web Service Technology. In fact, the creation of a FacadeBean was not required since one could annotate the SensorManager-Bean directly, but we separated the implementation Bean from the exposing Bean to make it easier to understand. Even if we didn’t match the WSDL from the J2EE 1.4 example exactly, we came very close. Merely some message-related datatypes have different names. In this example we used the Document/Literal/Wrapped style of Web Services in order to gain maximum interoperability. Even though the creation of the Web Service is a simple task using the annotations. The number of tools and dependencies has dramataically reduced since J2EE 1.4 and the development became less error-prone. Together with other EJB3 improvements it makes the JEE framework suitable for development in the context of enterprise distributed systems.

References and Resources

The example source code is available for download ( ws4jee.zip). Just import the projects from the archive into Eclipse Worskspace. Make sure to set up the JRE and JBoss Server instance for the projecst to work.

[2008,techreport] bibtex

E. Jendrock, J. Ball, D. Carson, I. Evans, S. Fordin, and K. Haase, "The Java EE 5 Tutorial," 2008.

@techreport{JAVAEE, author = {Eric Jendrock and Jennifer Ball and Debbie Carson and Ian Evans and Scott Fordin and Kim Haase}, title = {The Java EE 5 Tutorial}, url = {http://java.sun.com/javaee/5/docs/tutorial/doc/}, month = {Oct}, year = {2008} }

[2007,book] bibtex

O. Ihns, D. Harbeck, S. M. Heldt, H. Koschek, R. Schl�r, J. Ehm, and C. Sahling, EJB 3 professionell. Grundlagen- und Expertenwissen zu Enterprise JavaBeans 3 fr Einsteiger, Umsteiger und Fortgeschrittene , publisher DPunkt Verlag, , 2007.

@Book{IHNS_2003, author = {Oliver Ihns and Dierk Harbeck and Stefan M. Heldt and Holger Koschek and Roman Schl�mmer and Jo Ehm and Carsten Sahling}, title = {EJB 3 professionell. Grundlagen- und Expertenwissen zu Enterprise JavaBeans 3 f�r Einsteiger, Umsteiger und Fortgeschrittene }, publisher {DPunkt Verlag}, year = {2007}, month = {Jul}, url = {Oliver Ihns, Dierk Harbeck, Stefan M. Heldt, Holger Koschek, Roman Schl�mmer, Jo Ehm, Carsten Sahling} }

Configuring JBoss Datasource for Firebird DB

shuron — Mon, 04 Jan 2010 00:33:17 +0000

Accessing a relational database system from Java is a basic step required for many applications. The JEE architecture defines a standard for gaining this access, calls Java Connector Architecture (JCA). This article is a short HOWTO of configuring JCA-compliant datasource to a Firebird 2.x RDBMs using JBoss AS 5.1.0 as example. This tutorial is based on a Windows installation, but can be easily ported to Linux, or other OS.

For the configuration of the datasource two steps are required:

Deployment of the Firebird RAR resource adapter (jaybird-*.rar)

Creation of the firebird-ds.xml configuration

RAR Resource Adapter

The RAR Resource Adapter is a version of RDBMs drivers packaged in a special way, defined by the JCA specifcation. The
latest versions of Type 4 JCA-JDBC Firebird Driver (JayBird) can be downloaded from the IBPhoenix site. Inside of the downloaded archive you will find jaybird-*.rar (The version used during the creation of this tutorial was jaybird-2.1.6.rar). Since deployment in JBoss AS is performed by simple file copy, make sure to put the RAR-adapter-file into the deployment location of the application server. (e.G. ${JBOSS_ROOT}\server\default\deploy\).

After deployment, you can check the status of the resource adapter, by looking on the Administration Console of the JBoss (by default accessing the server URL http://localhost:8080/admin-console/ if run locally).

Datasource Description

After a successful deployment of the Resource RAR, the configuration of the datasource has to be created. The Firebird datasource configuration is supplied in a file, located in the default deployment location. JBoss AS auto-deplyoer will automatically look for the *-ds.xml files, so we name it e.G. firebird-ds.xml.

The following datasource configuration defines a local transactional datasource. You just need to replace placeholders USERNAME, PASSWORD and path to your database-file (In the used installation the file was located in: c:\databses\tesdb.fdb)

DataSourceFirebirdDS jdbc:firebirdsql:localhost/3050:c:${/}databses${/}tesdb.fdb org.firebirdsql.jdbc.FBDriver TRANSACTION_REPEATABLE_READ ISO8859_1 10 USERNAME PASSWORD 0 10 5000 15 SELECT CAST(1 as INTEGER) FROM rdb$database false 0 Firebird

Usage

The datasource in the example above is registered in the java JNDI namespace and is called DataSourceFirebirdDS. In the source code, this resource should be accessible via java:/DataSourceFirebirdDS. Here is the example using Dependency Injection (DI):

@Ressource(mappedName = "java:/DataSourceFirebirdDS") private DataSource firebirdDataSource;

In order to use the datasource in a JPA, the persistence unit has to be configured. For example, for using Hibernate, the following persistence unit can be configured.

... java:/DataSourceFirebirdDS org.hibernate.ejb.HibernatePersistence ... ... ...

Then in the DAO for manipulation of Persistent Entities, the Persistence Context can be injected by:

@Stateless public class TestDAOBean implements TestDAO { @PersistenceContext(unitName = "testunit") private EntityManager manager; ... }

Have fun and please provide some feedback.

Eclipse CNF: Navigator Content Extensions

Simon Zambrovski — Mon, 17 Aug 2009 20:55:11 +0000

Abstract

After providing the basic example of how the Eclipse Common Navigator Framework (CNF) can be used to display custom content, this article focuses on the main feature of the CNF – the contribution of content to the same navigator by several independent plug-ins. First of all, I will explain some minor changes introduced to the CNF in the Gallileo Edition, then I will focus on the content itself and finally provide an overview of how the action contributions can be provided. In the end of the post, some ideas on control of dynamic content are explained.

Gallileo Changes

There are two noticeable changes in the CNF that have been added with Eclipse Galileo. The return type of the method CommonNavigator#getInitialInput() has been changed to Object (which is important for the RCP usage of the CNF) and the call of the method org.eclipse.ui.internal.ide.model.WorkbenchAdapterBuilder#registerAdapters() has been replaced by the org.eclipse.ui.ide.IDE.registerAdapters(); which should be executed in the initialize method of the ApplicationWorkbenchAdvisor of your RCP if you are using resources with the CNF.

public class CommonNavigator ... { /** * Used to provide the initial input for the {@link CommonViewer}. * By default getSite().getPage().getInput() is used. * Subclass this to return your desired input. * @return The initial input for the viewer. * Defaults to getSite().getPage().getInput() * @since 3.4 */ protected Object getInitialInput() {...} }

Content contribution

The main advantage of the use of the CNF over a simple tree view is the ability to contribute content to the view from several plug-ins. Thus, the plug-in that contains the view does not depend on the contributing plug-ins. If you are not familiar with the CNF, please review the previous post, since the example provided there will be extended. The data model used previously will be extended by an additional layer: along with parents and children, the pets are introduced. Let’s assume that pets are owned by children.

/** * Represents a pet * @author Simon Zambrovski */ public class Pet { private String name; private Child owner; public Pet(String name, Child owner) { super(); this.name = name; this.owner = owner; } ... // getter and setter }

First of all create a new plug-in project called de.techjava.rcp.cnf.subcontent, add a plug-in dependency to the de.techjava.rcp.cnf and to the org.eclipse.ui.navigator. Then add two extensions org.eclipse.ui.navigator.navigatorContent and org.eclipse.ui.navigator.viewer. The first extension defines the new Navigator Content Extension (NCE) and the second one is used to bind it to the existing viewer.

The Sub Content is defined following the same scheme as the content in the previous article of this series. Its contentProvider and labelProvider attributes point to the corresponding classes. The label provider implementation is straight forward. The content provider has to be able to return a list of children, if the instance of the Child-class is selected in the Navigator. The enablement is defined in this way respectively. An important thing to understand at this point is that the CNF will join contributions of all NCEs triggered on the element selection. This means, that even if the NCE of the first plug-in does not provide any children for the Child element, there will be children contributed by the second plug-in’s content provider. Here is the example content provider, which returns the number of pets depending on the last digit in a child’s name:

public class CNFSubContentProvider implements ITreeContentProvider { ... public Object[] getChildren(Object parentElement) { if (parentElement instanceof Child && !(parentElement instanceof Parent)) { Child child = ((Child) parentElement); char lastDigit = child.getName().charAt(child.getName().length() - 1); if (Character.isDigit(lastDigit)) { int petCount = Integer.parseInt(String.valueOf(lastDigit)); Pet[] pets = new Pet[petCount]; for (int i = 0; i > petCount; i++) { pets[i] = new Pet(child.getName() + "'s pet " + (i + 1), child); } return pets; } return EMPTY_ARRAY; } else { return EMPTY_ARRAY; } } ... }

After this trivial configuration and the inclusion of the new plug-in into the example product, the resulting Navigator should show pets as sub-elements of the child-elements.

Shared commands

If the Navigator displays content from several plug-ins, the contributed commands should be handled carefully. The commands (contributed to the pop-up menu shown upon right-click on the corresponding item) should appear only on items they belong to. In order to achieve this, let us first look at the standard way of the command contribution. The CNF developer is strongly recommend to use the declarative contribution techniques instead of the Action Contribution Provider. For this purpose, the extension point org.eclipse.ui.navigator.viewer allows to contribute a popupMenu element as a child element of the viewer. The pop-up menu element defines the structure (in terms of separators) of the pop-up menu. There is a standard pop-up menu structure defined, which is default if a user-specific definition is ommited. In the example, the user-specific pop-up menu is defined:

... ...

Using the Eclipse Command Framework, the commands can be contributed to the defined pop-up menu in the following way. Using the org.eclipse.ui.menus extension point one or several menuContribution elements can be defined. Each menu contribution defines a set of commands, controls, menus, tool bars or dynamic contributions (or any combination) which are added to a specific separator addressed in a special way (see Command Framework Documentation). In this example the set of commands is contributed:

....

Please note that the commandId must point to an existing command, which is either user-defined, or defined by the Eclipse platform. A command is an abstraction of a user command which is referenced from the User Interface on one hand and has assigned handlers (which execute the command) on the other hand. The representation of the command is shown in the UI only if a handler is assigned to it. The idea of using shared commands is to have multiple handlers for the same command, which are activated depending on the selected element.

In order to enable and disable handlers in a declarative way, the Eclipse Core Expressions are used. Core expressions can be written in the enabledWhen and activeWhen child elements of the handler definition. The core expressions can also be defined and referenced externally using the org.eclipse.core.expressions.definitions extension point. Here is an example definition of the handler assigned to the Rename command:

The handler is enabled and active if the expression de.techjava.rcp.cnf.elementSelected is triggered. The definition of the expression is as follows. It defines the with-scope on the current selection, iterates over the elements and applies the instance of operator on the elements using the OR-conjunction. In doing so, the expression will trigger if among the currently selected elements is at least one Child element.

In order to use the same action (the Rename item of the pop-up menu) in the Pet plug-in, the handler enabled on the Pet element has to be provided. The code is analogous to the code before:

This should enable the Rename action on the Pet elements, too.

Dynamic content change

Finally, the last topic, which is covered in this article is the control of which content is shown in the Common Navigator. The developer can define the initial behaviour by setting the activeByDefault attribute of the NavigatorContent element. The user can customize the visible NCEs in the special dialog:

Of course there is a way to change the content shown in the Common Navigator at run-time. The following section describes how this can be done.

Responsible for loading the NCEs is the NavigatorContentService, which can be retrieved from the running Navigator instance. Using it is straight forward.

/** * Sets the status of a NCE of the current viewer if any */ public static void setToolboxNCEActive(final String extensionId, final boolean active) { CommonNavigator instance = findCommonNavigator(CNFNavigator.VIEW_ID); if (instance != null) { INavigatorContentService contentService = instance.getNavigatorContentService(); boolean isActive = contentService.getActivationService().isNavigatorExtensionActive(extensionId); if (active && !isActive) { contentService.getActivationService().activateExtensions(new String[] { extensionId }, false); } else if (!active && isActive) { contentService.getActivationService().deactivateExtensions(new String[] { extensionId }, false); } else { // do nothing, just quit return; } contentService.getActivationService().persistExtensionActivations(); contentService.update(); } }

The method findCommonNavigator(String viewId) is responsible for delivering the instance of the CNF. For example it could query the view for visible viewers and compare them with the requested Id:

public static CommonNavigator findCommonNavigator(String navigatorViewId) { IWorkbenchPage page = PlatformUI.getWorkbench().getActiveWorkbenchWindow().getActivePage(); if (page != null) { IViewPart view = page.findView(navigatorViewId); if (view != null && view instanceof CommonNavigator) return ((CommonNavigator) view); } return null; }

After the NCE status is changed the viewer has to be updated. Please note, that retrieving the instance of the INavigatorContentService via the Factory (NavigatorContentServiceFactory) will not work for this scenario (see Bug 284650).

Making a step back and thinking about the usage of the method above, I realized that it can be reduced to the usage of core expressions instead of the simple boolean activeByDefault attribute. Maybe this enhancement could be contributed to the CNF at some point…

The source code to this post is available for download. It includes two plug-in projects (the CNF and the child content) which are packaged into a small RCP application. Just launch the product included in the CNF plug-in.

References

http://wiki.eclipse.org/index.php/Common_Navigator_Framework

http://wiki.eclipse.org/Command_Core_Expressions

http://wiki.eclipse.org/index.php/Platform_Command_Framework

The compass image used in the post is taken from the FlickR gallery of Jean Franco Castro.

Passing Data between Plug-ins

Simon Zambrovski — Wed, 22 Jul 2009 20:57:12 +0000

Abstract

The Eclipse Platform provides a very rich API for the development and configuration of plug-ins and RCPs. It does this in two ways: by providing the corresponding classes and interfaces or by using the extension point mechanism. During the development the question arises, how to develop own extension points and how those plug-in interfaces look like. This article summarizes some of my experiences with developing plug-ins extension points.

Introduction

The extensive use of extension points is the standard approach during the development of own plug-ins and Eclipse-based applications. Especially, in the 3.x branch, the Eclipse Developers introduced tons of new extension points, primarily for the user interface, moving towards the declarative definition of the UI. Even if the the topic of the definition of extension points is covered in several books and articles, it is a bit challenging to come up with a clean extension point design for a particular scenarios, especially for beginners. This has to do with the specific way, how the Eclipse platform handles extensions.

In order to have a concrete scenario, lets assume that a small RCP application consisting of two plug-ins is being developed. The application prints out the time every ten seconds. One plug-in is responsible for the functionality of the time generation (lets call it the Core plug-in) and another, for the presentation of the results of the first one (lets call it UI plug-in). The separation of code in UI and non-UI plug-ins is a common practice and the standard question is, how to to pass data between the two. In general we assume, that the UI plug-in depends on the Core plug-in.

In the following the different alternatives are discussed.

Call me synchronously

One of the most simple and common cases is the situation, in which the UI plug-in has the control and needs to call a method on some instance of the Core plug-in. This happens particularly in cases, in which a command handler or an action implemented in the UI plug-in is invoked on behalf of user interaction and the functionality of the Core plug-in is called. The only thing to do is to add the classes to the exported by the Core plug-in. Since the UI plug-in depends on Core, the classes will become visible (in terms of OSGi) and can be imported and used directly. If the method is synchronous, the result can be received upon the completion of the method and displayed by the UI plug-in. In this case the plug-in boundary disappears.

Call me asynchronously

The things get more complicated, if the call is not synchronous, but is invoked inside of a IWorkspaceRunnable or a Job. This situation is common in enterprise scenarios, when the invoked functionality is a long running operation, like loading data from a database or accessing a resource over the network. The signatures of the methods for those operations do not provide a possibility to get the invocation result.

public interface IWorkspaceRunnable { public void run(IProgressMonitor monitor) throws CoreException; }

public abstract class Job extends InternalJob implements IAdaptable { protected abstract IStatus run(IProgressMonitor monitor); }

In fact the method invocation of asynchronous calls can be performed from any plug-in (so not only UI) and it does not play any role for the result. Thus, this case can be discussed together with the case, in which the Core plug-in broadcasts the data change.

Don’t call us, we will call you

Another case, which can be seen as a general extension of the asynchronous case is if the state changes, and consequently the UI change originates from the Core plug-in. This use case is possible if there are several UI plug-ins working with one Core plug-in, and the changes inside of the Core plug-in have to be propagated to the views, following the well-known Model-View-Controller Design Pattern. Then, a common approach is the implementation of the Listener-Broadcaster Design Pattern. The UI plug-ins (Views) should register themselves as listeners by the Core plug-ins and will be notified on changes of its (Model) state. In this case the extension point mechanism of Eclipse can be used as discussed in the following. It is also a good idea, to hide the code dealing with Eclipse Extension Registry and extensions, so a simple implementation of the broadcaster is provided, too.

Definition of the extension point (Core plug-in side)

The definition of extension point for the listener/broadcaster case involves four steps:

Creation of the listener interface

Registration of the extension point

Creation of the extension point schema

Implementation of the broadcaster

The so defined extension point can be used by plug-ins, which then provide implementations of the listener interface. The broadcaster, located in the Core plug-in is responsible for sending the data to them. Note, that providing the implementation of the listener via extension point is logically equivalent to the creation of a factory which is responsible for the production of listeners. The Core plug-in has the control of how this factory is used, how many listeners (from each extension) are created, and when these are notified.

Creation of the listener interface

The interface for the listener is usually very simple. It provides a method, which is called by the broadcaster, e.G:

public interface ISimpleListener { public void eventOccured(); }

Sometimes the method takes parameters, like public void eventOccured(String message) or public void eventOccured(ISimpleEvent event) and sometimes it returns a value. In general, the signature of the notification method is application-specific and will not be discussed further. Since the implementers of the listener does not have control over the way, how and when this method is used, it is advised to add two life-cycle methods to the interface initialize() and terminate():

package de.techjava.rcp.plugins.core.listener; /** * A simple listener * @author Simon Zambrovski, TechJava Group */ public interface ISimpleListener { /** * Initialization life-cycle method */ public void initialize(Object source); /** * Signals the event occurrence * @param event */ public void eventOccured(SimpleEvent event); /** * Termination life-cycle method */ public void terminate(); }

The life-cycle of the listener is then defined as follows: first, its parameter-less constructor is called, then the initialize method is invoked, providing the ability to hook into some infrastructure inside of the implementing plug-in. After the initialization, the eventOccured method is called multiple times. Finally, the listener is informed about the fact that the source will not send any information by the invocation of the terminate method. The source parameter of the ISimpleListener#initialize(Object) method again is application specific and should be chosen that way, that the listener is able to determine the source of events. Alternatively, the method ISimpleListener#eventOccured(SimpleEvent) can carry this information on every invocation, either in the SimpleEvent object or as additional parameter.

Registration of the extension point

After the Java interface of the listener has been created, the extension point can be defined. The easiest way to this, is to use the Plug-In Manifest Editor > Extension Points, but you can edit the plugin.xml directly. Basically, three values are required: id, name and schema location.

The corresponding plugin.xml code looks like this:

Since the dependent plug-ins should implement the ISimpleListener interface, the containing package has to be exposed. This can be done either by adding the package to the list of exported packages using the Plug-In Manifest Editor > Runtime > Exported Packages or by simple editing of the MANIFEST.MF file and adding the following line to it:

Export-Package: de.techjava.rcp.plugins.core.listener

Creation of the extension point schema

The definition of the extension point is performed by creation of the XML-Schema document, describing the structure and the data of the extension point. The Eclipse IDE provides a convenient Extension Point Schema Editor for this task, implemented as multi-page editor with master-detail page for schema definition. The creation wizard already creates the extension element. What has to be done is this:

Create New Element

Provide an adequate Name for it (listener in our case)

Add an Attribute to this element

Provide an adequate Name for it (class in our case)

Change the Use to required

Change the Type to java

Fill the Implements with the full-qualified name of the listener interface (de.techjava.rcp.plugins.core.listener.ISimpleListener)

Optionally, fill the description

Add a Sequence to the extension

Add a reference to the listener to the Sequence

Optionally, adjust the multiplicity of the listener element, to allow multiple listeners to be registered using one extension point

In the Extension Point Schema Editor the corresponding changes should look like this:

Implementation of the broadcaster

After the interface is created and the corresponding extension point is defined, a broadcaster can be implemented. Its purpose is to hide the code related to the use of the Extension Point Registry. For convenience, the broadcaster can implement the same interface as the listeners do (ISimpleListener).

/** * Simple broadcaster implementing the listener interface * @author Simon Zambrovski, TechJava Group */ public class SimpleBroadcaster implements ISimpleListener { private static final String POINT_ID = "de.techjava.rcp.plugins.core.listener"; private static final String CLASS_ATTRIBUTE = "class"; private List listeners = null; /** * Construct the broadcaster and initializes the listeners registered * using {@link de.techjava.rcp.plugins.core.listener} extension * point */ public SimpleBroadcaster(Object source) { // initialize on creation initialize(source); } public void eventOccured(SimpleEvent event) { // broadcast the events for (ISimpleListener listener : this.listeners) { if (listener != null) { listener.eventOccured(event); } } } public void initialize(Object source) { // retrieve the registered listeners this.listeners = getRegisteredListeners(); // initialize for (ISimpleListener listener : this.listeners) { if (listener != null) { listener.initialize(source); } } } public void terminate() { // terminate for (ISimpleListener listener : this.listeners) { if (listener != null) { listener.terminate(); } } this.listeners = null; } ... }

The broadcaster holds the list of registered ISimpleListener instances. Its own implementation of the ISimpleListener is trivial and just delegates the calls to the elements of this list. The static method SimpleBroadcaster#getRegisteredListeners() is responsible for querying the registry for the registered extension and looks as follows:

/** * Retrieves all registered listeners */ public static List getRegisteredListeners() { IConfigurationElement[] decls = Platform.getExtensionRegistry().getConfigurationElementsFor(POINT_ID); Vector validExtensions = new Vector(); for (int i = 0; i < decls.length; i++) { try { ISimpleListener extension = (ISimpleListener) decls[i].createExecutableExtension(CLASS_ATTRIBUTE); validExtensions.add(extension); } catch (CoreException e) { Activator.logError("Error instatiating the " + POINT_ID + " extension", e); } } return validExtensions; }

Use of the broadcaster

The use of the broadcaster from the Core plug-in is straight-forward. Here is an example of a job, which periodically sends message containing the time to the listeners.

/** * Broadcasts the current time * @author Simon Zambrovski * @version $Id$ */ public class SimpleTimeBroadcastJob extends Job { private SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd hh:mm:ss"); private SimpleBroadcaster broadcaster = null; public SimpleTimeBroadcastJob() { super("Time Broadcast Job"); } protected IStatus run(IProgressMonitor monitor) { try { broadcaster = new SimpleBroadcaster(this); broadcaster.eventOccured(new SimpleEvent("Curent time in Core is " + sdf.format(new Date()))); broadcaster.terminate(); return Status.OK_STATUS; } finally { // restart again in a 10 seconds schedule(10 * 1000); } } }

Now, after the Core part is implemented, we focus on the implementation of the UI part, which receives the events.

Use of extension point (UI plug-in side)

The usage of the extension point is simpler than its definition and basically consists of the implementation of the listener interface and its registration. Here is a sample implementation writing to System.out:

public class SimpleListener implements ISimpleListener { private Object source; public SimpleListener() { } public void eventOccured(SimpleEvent event) { String message = "Event from " + source.toString() + ": " + event.getMessage(); System.out.println(message); } public void initialize(Object source) { this.source = source; System.out.println("New " + SimpleListener.class.getName() + " listens to " + source.toString()); } public void terminate() { this.source = null; this.consoleStream = null; System.out.println("Listners destroyed"); } }

In order to tell the Eclipse Platform about the existence of this implementation, the extension point defined in the Core plug-in and has to be used in the UI plug-in. For this purpose, the UI plug-in must list the Core plug-in in its Dependencies and define the use of the extension point in the plugin.xml:

That’s it.

Example

The example source for this article is available here. It is a little bit more elaborate and provides a simple application, which prints the time into the Eclipse Console. I used Eclipse Galileo (3.5.0) – just copy the two projects into your workspace and run the product.

References

Notes on the Eclipse Plug-in Architecture

Design Patterns: Elements of Reusable Object-Oriented Software

Packaging Eclipse-based RCP for the use in enterprise context

Simon Zambrovski — Wed, 08 Jul 2009 20:00:33 +0000

Abstract

Using Eclipse-based rich-clients as stand-alone applications is discussed in many books and articles. In the context of enterprise systems, the software development adopted several paradigms to improve the quality of the overall architecture. This short article describes some issues in packaging the application for using it in the context of enterprise systems.

Architectural Assumptions

Designing enterprise architectures is a standard discipline for IT-consulting companies or freelancers involved in software development. Maybe one of the main characteristics of enterprise architectures is the framework-driven approach of software creation. Thus, the software has to comply certain rules and standards adopted inside the enterprise. In order to simplify such constrained development process, it is common to use an in-house software framework, which enforces the compliance of the enterprise-internal standards and acts as glue between different technologies adopted as parts of the enterprise architecture.

Using such frameworks has major implications for the software development in general, and especially for the rich client development. The design issues are summarized in the next section.

Usaging an Enterprise Framework

The major goal of the enterprise in-house framework is to simplify the process of software systems development and to enforce standardization among the software systems. This usually includes the following aspects:

Domain-specific component framework

Methods for master data management

Infrastructure services: authentication, authorization, communication, security, printing, reporting

Application skeletons and launchers

The more unification and standardization is included inside the framework, the easier it is for a software developer to concentrate on the particular business task and the easier is the maintenance of the software system.

From the previous list, the most interesting part related to RCP packaging and deployment is the existence of the application skeletons and launchers. So, when launching an application, the framework libraries are loaded and executed first and pass the control to the application-specific modules. The advantage of this approach is that infrastructure services can be loaded first, which can be developed and shared among different applications.

The required plug-ins

Following the general idea of RCP packaging (see rules provided in the RCP Book) and assuming one target platform (in terms of one RCP product), one top-level plug-in and should be defined. In addition, we assume at least one in-house framework plug-in and at least one application-specific plug-in. Usually there will be more of each type, but it will not change the picture much. Important at this point is the fact, that the application-specific code depends on the in-house framework code. In order to simplify the identification of the plug-ins, an example project is introduced. Let’s assume the project is called FooBar. Then, the plug-ins are called:

de.techjava.foobar: This is the functional plug-in, which contains the application-specific code.

de.techjava.framework: This is the framework plug-in, which contains framework component code.

de.techjava.foobar.product.standalone: This is an application and product definition plug-in which contains the definition of the product and application-agnostic code for launching the application.

Managing plug-in dependencies

A difficult issue for the RCP beginners is the management of dependencies between plug-ins. Especially, the transition from the development of a single plug-in to the configuration of features and products seem to be non-trivial. In order to solve this problem, there are simple rules to follow. You can violate these rules in sophisticated scenarios, but for the beginners it is a good idea to follow them.

Create dependencies only if you need them. Each plug-in should only list plug-ins (or even better packages) it really depends on. Make sure to check it with the “Find unused dependencies” action available on the right-click in the Dependencies Tab of the Plug-in Manifest Editor.

Use versioning information. Plug-ins (or better bundles, or as Chris call them Plundles) provide version information. And it is highly advisable to include them in the import statements of the plug-ins, which simplifies the migration later on…

Don’t forget anything. Every Plug-in should appear in at least in one Plug-In section of the Feature definition. Every feature should be included by another feature, higher in the hierarchy.

Keep the hierarchy flat. For simple scenarios, it is sufficient to have two levels of features (top-level feature, one per-product and the underlying features include their plug-ins).

Don’t re-export dependencies. Every Feature for a group of plug-ins should also include plug-ins required by the members of the group. It does not hurt if a plug-in is included several times, but it does if it is not included at all. You can optimize here if you check which plug-ins are imported by the Eclipse RCP feature (which can be considered as stable), but it does not make assumptions about features developed by third parties.

Following these rules it is simple to create features for the corresponding plug-ins. Several plug-ins which belong together and are handled as a fixed piece can be grouped into Features. Usaging Features is highly advisable, and sometimes simply required (e.G. by RCP in a Java Web Start target deployment strategy). So in addition to the previously mentioned plug-in projects, at least three feature projects are required:

de.techjava.foobar.feature: This is a functional feature, which includes the de.techjava.foobar plug-in and all plug-ins required by it, which do not appear in the Eclipse RCP feature

de.techjava.framework.feature: This is a framework feature, which includes the de.techjava.framework plug-in and all plug-ins required by it, which do not appear in the Eclipse RCP feature

de.techjava.foobar.feature.standalone This is the top level feature, which is used for the product configuration. It includes the two features above and the Eclipse RCP feature (and optional other features used, like e.G. org.eclipse.help). It also includes exactly one plug-in, which is not included anywhere else: de.techjava.foobar.standalone.product

The product definition plug-in

The definition of the product is spread among several files. First of all the plug-in.xml of the de.techjava.foobar.standalone.product plug-in makes uses of two extensions:

org.eclipse.core.runtime.applications

org.eclipse.core.runtime.products

The application extension point is used to point to the Java class implementing the interface org.eclipse.equinox.app.IApplication. Along with this implementation, other classes needed to start up the RCP (like Advisors, etc…) are placed into the source directory of the plug-in. The product extension point is used for the association of the application with a product id. The previously-defined top-level feature includes all required features and the product definition plug-in. Finally, the .product file is the place, where all things are bound together: product id, application id, launcher parameters, and the one top level feature: de.techjava.foobar.feature.standalone. Other customization of the RCP is possible from the plugin-customization.ini, which is placed together with the .product file into the plug-in root directory.

As a result the following configuration should be achieved after the packaging is finished. The product references the product-id and the application, defined in the plugin.xml of the plug-in project it is contained in. The product configuration is feature-based and includes one top-level feature. The top-level feature includes all other features (functional, framework, Eclipse RCP, other optional) and the one plugin, in which the product file resides.

The simple example provided in this articles is available as sourcecode for download ( rcp-packaging.zip).

The framework hooks

In the introduced scenario, the packaging is not specific to the in-house framework. It just includes the feature containing the framework plug-in. This approach works fine, if the framework is used in a white-box manner, which means that the framework provides ready-to-use components to be plugged-in to the application (like e.G. a component for the master data management). The other type of frameworks is the so-called black-box framework, which provides components that have to be configured and integrated into the application components. In this case, the framework components can not be plugged-in using some declarative extension points, but need to be called from the application code. In the latter case, the dependencies appear between the plug-in launching the application (de.techjava.foobar.standalone.product) and the framework plug-ins. This requires a modification in the previous setup and the violation of one of the rules posted above. The plug-in has to define the dependency to the framework plug-in, but the top-level feature does not include the required plug-in directly, but imports the whole framework feature.

Technorati-Tags: eclipse, java, rcp, packaging, plugin, feature, product, enterprise systems

Eclipse DemoCamp Galileo Hamburg

Simon Zambrovski — Tue, 26 May 2009 23:25:06 +0000

As announced in a previous post the Eclipse Demo Camp Hamburg – Galileo Edition took place in the East Hotel in Hamburg. Organized by Peter and Martin, the event was again an interesting meeting with Eclipse-interested people in a wonderful location. Five presenters introduced Eclipse and OSGi-related topics. Moritz Eysholdt reported about the (Meta)Model Evolutions, he was focusing on during his masters thesis. The interesting part of his solution are two Xtext DSLs for description of the Metamodel changes (EPatch) and model migration algorithms (MetaPatch). Heiko Behrens gave a funny and really good introduction of Xtext and DSLs for not Xtext developers. I really like his examples: these are simple and understanding for everyone. Great job! Marco Mosconi showed some ObjectTeams (black) magic. A very intersting technology using aspect-oriented programming for type-safe framework modifications. Seem to be pretty advanced technology with interesting tooling. Markus Alexander Kuppe had a talk on ECF and RFC 119 and gave some sneak preview of the upcomming features. Finally, I had a short talk on Common Navigator Framework, basically explaining the article posted here and something I documented for Galileo. Here are some visual impressions: my FlickR set and Peter’s.