Freitag, 21. Juni 2013

Geocoding location names with Geoff

What is geocoding?

Imagine you have some data in a database that (logically) could be visualized on a geographical map, but you are missing the geographic coordinates (typically latitude/longitude pairs), i.e. you only have the object's logical name:
  • city names
  • postal addresses, street names
  • points of interest: restaurants and bars, libraries, shops, etc.
In order to get the coordinates, you could look up those names in a search engine and show it on a map like Goolge Maps does, then, grab its coordinates and assign them to the objects.
This process is called geocoding: assigning geographical coordinates to a location name.

Querying geocoding services

As you guess, manually geocoding location names can take a lot of time if you have a bunch of objects.
Luckily, this procedure can be automated. There are (public) geocoding services available that can be used to automatically lookup location names and get a geocoded equivalent:
  • Commercial geocoding APIs/webservices providers (Google, Microsoft, Nokia, etc.)- may be 'free' but constrained depending on how many queries you execute
    • Obtain a proper key from those providers
  • OpenStreetMap's geocoding (public) API/webservice - not to be queried in productional environments
    • Host the OpenStreetMap planet files yourself or 
    • consume from a (commercial) provider that has done this already

Using Geoff's API to query a geocoding service

The Geoff project (which is a proposed project at the Eclipse Locationtech IWG)  has a simple interface (IGeocodingService) that acts as a facade/frontend to the public/commercial geocoding services:

public List executeQuery(String query);

It takes a query string as parameter (a location name, for example) and returns a list of potential matches of type POI (point of interest) which has a LongLat (geographic coordinates) and service specific properties.
The result is a List of best matches of geocoded POIs as in general it is not always possible to uniquely identify the location name when automatic geocoding is done. In such cases, you will have to check and resolve the best match.

Currently, there is a default implementation that queries OpenStreetMaps's Nominatim to geocode location names. Other implementations may follow.

Visualizing geocoded location names with Geoff

Once you have finished the geocoding process, you can use Geoff to visualize the POIs on a map (in your Eclipse RCP application). The following steps will walk you through a simple use case...

Setup the map

Geoff has an EMF ecore meta model to define a map object.

1. create the root map container
GeoMap map = MapFactory.eINSTANCE.createGeoMap();
MapOptions opts = MapFactory.eINSTANCE.createMapOptions();
opts.setNumZoomLevels(16);
map.setOptions(opts);

2. create an OpenStreetMap base layer
OSM layer = LayersFactory.eINSTANCE.createOSM();
LayerOptions opts = LayersFactory.eINSTANCE.createLayerOptions();
opts.setIsBaseLayer(true);
layer.setOptions(opts);
map.getLayers().add(layer);

3. create a second layer that will contain some POIs (Markers)
Markers markersLayer = LayersFactory.eINSTANCE.createMarkers();markersLayer.setName("Markers");map.getLayers().add(markersLayer);

4. a) obtain a list of location names from some backend data source
String[] cities = new String[] { "Berlin", "Paris", "London", "Madrid", "Rom" };

4. b) geocode the location names and add to second layer
IGeocodingService geo = IGeocodingService.Util.getFirstFound();
for (String city : cities) { List results = geo.executeQuery(city); if (!results.isEmpty()) { POI poi = results.get(0); Marker marker = MarkersFactory.eINSTANCE.createMarker(); LonLat lonLat = TypesFactory.eINSTANCE.createLonLat(); lonLat.setLon((float) poi.getLatLon().getLon()); lonLat.setLat((float) poi.getLatLon().getLat()); marker.setLonLat(lonLat); markersLayer.getMarkers().add(marker); }}

Setup the UI container (this part is SWT/E4 specific)

@PostConstruct
public void createUI(Composite parent) {
GeoMap map = ... //map object populated in first step
GeoffMapComposite mapComposite = new GeoffMapComposite(parent, SWT.NONE);
mapComposite.setMap(map, "map");
}

Preview

The output should be similar to the following screenshot...


How was that done?

GeoffMapComposite is a wrapper for SWT's Browser widget. It runs the JavaScript framework OpenLayers. Once you call GeoffMapComposite.setMap(), it will use Geoff's code generation functionality to generate OpenLayers specific JavaScript code at run-time and execute it in the wrapped Browser widget.


Mittwoch, 27. März 2013

Geoff: Visualizing geographical maps in Eclipse RCP/RAP applications

The Eclipse Foundation has set up a new industry working group, namely LocationTech.
Its main focus is on

- Storage and processing of massive data volume
- Model driven design
- Desktop, Web, and mobile mapping
- Real time analysis of business critical data

With geoff (geo fast forward), I have proposed a new project that aims at providing a solution to be used for existing (or maybe new ones, too) Eclipse RCP applications to enable visualization of geographical (geo spatial) maps. It uses model driven design (EMF) to provide a declarative configuration of a layered map that can be rendered via the JavaScript framework called OpenLayers 2.12.


EclipseSource's Ralf Sternberg was very cooperative to host an RAP version of the current state on their demo server - Thanks a lot!

Geoff RAP Demo Application

You can follow the progress on GitHub: Geoff on GitHub

Freitag, 28. Mai 2010

Chained Commands Execution

Chained Commands Execution

What are commands?

The eclipse command API [1] allows for declaratively contributing UI parts (menu/toolbar items, window controls, ...) to the UI anywhere in your workbench window.
In general, this requires to
  1. create a command definition
  2. create a handler or handlers (which are conditionally enabled upon a specific expression)
  3. define a menu contribution to be shown in the UI which the user can use to trigger the execution of the command

As the command API does exist since eclipse 3.3, there are plenty of (re-)usable commands:



What are chained commands?

As you might have noticed, the core API just allows to call one specific command per menu contribution (menu/toolbar item, ...).
Often, there is a need to execute several commands by just one UI button. To allow this, you have to define a composite command that is manually written to call command X, Y, and Z.
If you want to execute command A, B, and C in a sequence, you have to provide another composite command.
Things will become more complicated if those wrapped commands require parameters to be passed to them.

To fix this, we just define a chain of commands.


A chain of commands consists of an arbitrary number of commands tied together to be executed (conditionally) in a sequence.

Example: Imagine you have a web application based on RAP [2]. Once the user accesses the web application, he is given a login form where he has to provide his login data. Once he presses the login button, he is redirected to a home perspective. If the login fails, an error message will occur.

The plugin.xml may contain this extension:

<extension

         point="org.eclipse.ui.menus">

      <menuContribution

            allPopups="false"

            locationURI="chain:chains.demo.login">

         <command

               commandId="myapp.login"

               id="command.login"

               style="push">

         </command>

         <command

               commandId="ui.showMessage"

               style="push">

            <parameter

                  name="type"

                  value="error">

            </parameter>

            <parameter

                  name="message"

                  value="Login denied using: user={login.user}">

            </parameter>

            <visibleWhen

                  checkEnabled="false">

               <with

                     variable="previous">

                  <equals

                        value="false">

                  </equals>

               </with>

            </visibleWhen>

         </command>

         <command

               commandId="org.eclipse.ui.perspectives.showPerspective"

               style="push">

            <parameter

                  name="org.eclipse.ui.perspectives.showPerspective.perspectiveId"

                  value="myapp.myHomePerspective">

            </parameter>

            <visibleWhen

                  checkEnabled="false">

               <with

                     variable="command.login">

                  <equals

                        value="true">

                  </equals>

               </with>

            </visibleWhen>

         </command>

      </menuContribution>

   </extension>


This is the menu contribution extension point.
Our contributions will not go into a menu/toolbar/..., instead they will be added to a chain (locationURI="chain:chains.demo.login" where the chain's id is chains.demo.login).
Next, we define three commands to be executed by the chain:

1. the myapp.login command will authenticate the user
2. the ui.showMessage will show an error message if the user could not be authenticated
    - this will only happen if the previous command has been executed successfully, you can check this by comparing the "previous" variable's boolean value
3. the last command will change the active perspective, if the first command succeeded

Next, we have to define the chain execution menu item:

<extension

         point="org.eclipse.ui.menus">

      <menuContribution

            allPopups="false"

            locationURI="toolbar:org.eclipse.ui.main.toolbar">

         <command

               commandId="platform.executeChain"

               style="push">

            <parameter

                  name="chainID"

                  value="chains.demo.login">

            </parameter>

         </command>

      </menuContribution>

   </extension>


This command menu item will execute the chain defined by the id "platform.executeChain". That is our composite command that handles chain executions.

Source

The source of the chain command is available on google code at

https://erdalkaraca.googlecode.com/svn/trunk/org.eclipselabs.chains

Use a subversion client to checkout.

Links

[1] http://wiki.eclipse.org/index.php/Platform_Command_Framework
[2] http://eclipse.org/rap/



Dienstag, 12. Januar 2010

Single Sourcing RAP/RCP apps

Scenario

You read about RAP [1] to be able to do pretty much that is possible with RCP, and thus, decided to provide a web version of your eclipse plugin.
So, you install and setup the RAP tooling [2]. You change your target platform to compile against the RAP runtime. Several compile errors arise. After some research you read about RAP not being fully compatible with its RCP counterpart and that you will have to apply single sourcing techniques to get your plugin work on RAP.
A bit more of your research reveals the following approaches used for single sourcing:
  • use reflection to determine whether a specific functionality is available
  • swap non-working code into a bundle fragment
  • use osgi services for each functionality to be single sourced
  • use byte code weaving to patch non-working code at runtime
  • etc. (Are there any more to be listed here?)

This approach

This approach is based on a central single sourcing service (think OSGi). It provides an interface for registering and executing wrapped code by a user defined id:


Let us explain this by a simple example: In your RCP you are adding a mouse move listener to a control:

Composite comp = new Composite( parent, SWT.None );
comp.addMouseMoveListener( new MouseMoveListener() {
 public void mouseMove( MouseEvent e ) {
  System.out.println( "mouse location: "
   + e.x + ", " + e.y );
 }
} );

As you might know, RAP does not support mouse move events, and thus, this has to be single sourced.
We, first, have to register the wrapped code, i.e. the part that is not runnable on RAP:

ISingleSourcingService service = ISingleSourcingService.INSTANCE.get();
service.registerExec( "my.execs.addMouseMoveListenerToComposite",
 new IExec() {
  public Object run( Object... params ) {
   Composite comp = (Composite) params[ 0 ];
   comp.addMouseMoveListener( new MouseMoveListener() {
    public void mouseMove( MouseEvent e ) {
     System.out.println( "mouse location: "
      + e.x + ", " + e.y );
    }
   } );
   return null;
  }
 } );
 }


Then, we can call the single sourcing service to execute the wrapped code:
Composite comp = new Composite( parent, SWT.None );
service.execute( "my.execs.addMouseMoveListenerToComposite", null, comp );

This code can be used on both of the platforms, since it does not cause any errors anymore.

Missing clues

Where to register wrapped code?
The preferred way is a separate plugin to host the code. When running on RCP, you will have to make sure that this plugin has been started. On RAP, you would just exclude that plugin from deployment. The other way around is valid as well.

Where to find the sources?
You can checkout the sources from http://erdalkaraca.googlecode.com/svn/trunk/org.eclipse.labs.singlesrc.

[1] http://eclipse.org/rap/introduction.php
[2] http://eclipse.org/rap/gettingstarted.php