Eclipse RCP and REST – Default properties make configuration even easier

This is a continuation of a series of blog posts demonstrating the use of the ECF Remote Services JAX-RS Jersey Client within an Eclipse RCP application. The previous posts are:

The REST calls made by the Eclipse RCP SpaceX client are done using the ECF Remote Services framework. In previous versions of this example, it was necessary to specify all of the Remote Services properties at the service level, even though most of these properties are not unique to a service. This often results in unnecessary duplication and maintenance issues.

In ECF 3.14.19 (released this week) a new feature has been added allowing for the specification of default properties. This feature simplifies the creation and maintenance of REST endpoint definitions.

Default properties files

A default properties file must be named edef_defaults.properties and can be located either in the root folder of a bundle or in a folder containing REST endpoint definitions.

The scope of the properties depend on the file location. Note that all properties override any values specified in an XML EDEF file.

As part of this work, all properties files now allow for the specification of various data types (Long, Boolean, UUID) as well as arrays of values. Basically everything you can specify in an XML EDEF can now be specified in a properties file.

For detailed instructions on creating properties files, see the updated ECF documentation.

Properties-only endpoints

You may be wondering if XML EDEF files are even necessary at this point, as properties files provide for much more flexible endpoint configuration. You will probably find your XML EDEF file getting gradually smaller until it contains very little if nothing at all.

In that case, ECF Remote Services now supports the direct specification of a properties file as an endpoint definition. In your manifest, this would look something like:

Remote-Service: OSGI-INF/LaunchService_EDEF.properties

Goodbye XML!

Profiles and defaults

In my last article on Eclipse RCP and REST I described how profiles can be used to specify conditional endpoint properties. Usually this is done when you want to support multiple endpoint environments (dev, test, prod, etc.).

These profiles rely on a command line argument specifying the name of the profile and a matching suffix in the properties file names. The new ECF release now supports these profiles for default properties as well. For example, if you specified “dev” as the profile, then the endpoint properties would be read like this.

This combination of bundle/folder defaults and profile overrides provides a great deal of flexibility in endpoint configuration.

Updated SpaceX example

So let’s look at how these new features are used in the Eclipse RCP SpaceX client.

First, the global JAX-RS Jersey client can be configured with bundle level defaults. I can now specify many REST endpoints in my bundle without having to configure them individually.

edef_defaults.properties (located in bundle root folder)

endpoint.id:uuid=
ecf.endpoint.id.ns=ecf.namespace.jaxrs
remote.configs.supported:array=ecf.jaxrs.jersey.server
remote.intents.supported:array=passByValue, exactlyOnce, ordered, jaxrs
service.imported.configs:array=ecf.jaxrs.jersey.server
service.intents:array=osgi.async
ecf.endpoint.rsfilter=(objectClass=*)
ecf.rsvc.id:Long=0

Then for the Launch Service a properties file defines the attributes that are uniform across all environments/profiles. In this case, the only uniform property is the annotated JAX-RS client interface.

OSGI-INF/LaunchService_EDEF.properties

objectClass:array=com.modumind.spacex.service.LaunchService

# Could also supply a default endpoint URI in case profile is not set
ecf.endpoint.id=https://api.spacexdata.com/v4

And then finally an endpoint URI can be set for each profile if the goal is to do something like this.

For the SpaceX client I currently do not have environments, but as an example the SpaceX REST API has recently been upgraded from version 3 to 4. If I wanted to support both versions during a migration I could have two profiles – “v3” and “v4” and then create the following two properties files.

OSGI-INF/LaunchService_EDEF-v3.properties

ecf.endpoint.id=https://api.spacexdata.com/v3

OSGI-INF/LaunchService_EDEF-v4.properties

ecf.endpoint.id=https://api.spacexdata.com/v4

Wrapping up

At this point there is no outstanding work to do on the ECF Remote Services JAX-RS Jersey Client (though feature requests would be welcome!) and in my opinion it’s extremely easy to use. If you’re interested in integrating REST clients into an Eclipse RCP application, I would very much suggest you take a look.

Note that if you’ve been using earlier versions of ECF Remote Services, you’ll need to reload the SpaceX Client target to bring in the latest version (3.14.19 or later).

The latest SpaceX client code can be found here:

https://github.com/modular-mind/spacex-client