Enterprise J2ME Developing Mobile Java Applications [Electronic resources] نسخه متنی

18.2 Microsoft MapPoint Web Services

Standalone GIS servers (e.g., Oracle GIS server) that are capable of geocoding, map rendering, and other complex geographic algorithms have been commercially available for a long time. However, running a GIS server by yourself is probably too expensive for most small to mid-sized businesses. The costs include:

Hiring GIS experts to set up and maintain the system.

Licensing high-resolution digital maps and business yellow page listings. This could be very expensive if your users roam across many metropolitan areas.

Aggregating geographic information updates from many sources (e.g., road construction and business address changes) and updating them frequently to the database.

Ongoing server administration for secure and high availability services.

Licensing cost of the GIS server software itself.

For most companies, it makes sense to outsource the entire GIS operation to specialized providers. Microsoft's MapPoint Web Service is a managed GIS solution accessible via a set of platform-independent SOAP Web Services APIs. MapPoint also allows users to import their own geocoding data and points-of-interest listings for customized services.

Note

You can pay for MapPoint services based on the number of queries you perform. Or, you can get unlimited queries for a flat subscription fee. Developers can evaluate the service for free for 45 days.

18.2.1 The MapPoint v3.0 SOAP API

MapPoint Web Services expose a very rich set of SOAP APIs. Important remote methods in MapPoint v3.0 are divided into four categories.

Common Service contains utility functions that are common to other services.

Find Service allows the user to do generic geocoding tasks, including finding addresses from latitudes and longitudes, and vice versa. It also allows searching for nearby points of interests.

Route Service calculates routes and directions based on locations and waypoints. It also generates map view representations of the calculated routes. The map view can be used to highlight routes on a map.

Render Service renders the map for the locations or routes. It highlights routes, places pushpins and icons, and supports zoom.

Table 18.1 lists the methods from all categories. The first 5 methods in that table belong to the common service; the next 5 methods belong to the find service; the next 2 methods belong to the route service; and the last 4 methods belong to the render service. The API also defines many composite data types (e.g., Address, MapView, and RouteSpecification) to pass data to or from those service methods. Detailed discussions on how use the MapPoint API is beyond the scope of this book. For interested readers, the Axis gateway example in Section 18.2.3 demonstrates the use of many basic API functions from a Java client.

18.2.2 The Aggregated API

Through the SOAP API, MapPoint Web Service offers fine-grained access to its GIS back end, allowing us to design flexible applications without arbitrary limitations imposed by preset scripts. However, the trade-off is that we have to make separate method calls for each small step to complete a task. For example, in order to retrieve driving directions between two addresses, we have to go through the following steps.

Convert the addresses to latitude and longitude coordinates.

Calculate the route according to options.

Render the overview map with the route and start and end locations highlighted.

Retrieve turn-by-turn instructions for each route segment.

Render highlighted turn-by-turn maps for each route segment.

The last two steps need to be performed repeatedly for a long route with many segments. Since all those method calls are remote SOAP calls, those excessive round trips cause long delays over slow wireless networks. To minimize the data transfer over wireless networks, we can place a remote facade between the mobile client and MapPoint. The facade takes in two human-readable addresses in a single SOAP call, queries MapPoint via many API calls over the wired Internet, constructs the resultant driving directions, and returns the results. It provides a coarse-grained, simple interface that aggregates functions of the fine-grained MapPoint API methods for specific applications. Figure 18.1 illustrates the facade architecture.

Note

As a Microsoft platform, MapPoint was never designed for Java clients. But the use of SOAP Web Services makes it platform-independent. This highlights the power of Web Services.

18.2.3 The Axis Facade

In this section, we introduce a Java-based SOAP facade (gateway) that aggregates generic MapPoint APIs into convenient remote methods for specific tasks to minimize round trips for mobile clients. The gateway is built using Apache Axis (v1.0). It is developed as follows:

Generate Java SOAP stub classes for the MapPoint SOAP API using the WSDL2Java tool in Axis.

Use those Java stub classes to develop a Java object, MPClient, that contains convenience aggregated methods.

Publish the MPClient object as a SOAP Web Service via Axis's server interface. This is the RPC interface for mobile devices. The steps are as follows.

Configure and run Axis server inside a Tomcat server.

Copy the JAR file containing the MPClient class to Axis library directory.

Specify the scope of the service object, methods to expose, and other options via a .wsdd file.

Deploy the .wsdd file to Axis through its server administration utility.

Detailed tutorials on how to configure and use Axis are beyond the scope of this book. Please refer to Axis documentations in the "Resources" section. Due to the limited space, I show only the public interfaces of remote methods in the MPClient class here (Listing 18.1). The API usage is embedded in the code comments. The complete code is available in the AxisFacade project, downloadable from this book's Web site. The project archive also contains generated stub classes, Axis libraries, sample .wsdd files, and ANT script to build and deploy the facade gateway.

Listing 18.1. The Axis facade MPClient class

public class MPClient {
// Authentication credentials obtained from
// MapPoint Web site
private static String userName = "userid";
private static String password = "password";
// other variables
// The cached route segments
private Segment[] segments;
// Get the driving directions between
// two human-ready addresses. This method
// also caches the route in the segments array
//
// You have to run this method before you can
// retrieve maps for the entire route or for
// each route segment.
public String [] getDirections (
String fromStreet, String fromCity,
String fromState, String fromZip,
String toStreet, String toCity,
String toState, String toZip
) throws Exception {
// method body
}
// Return the number of segments of the current
// cached route. The number is available after
// you call the getDirections() method.
public int getSegmentNum () throws Exception {
// Method body
}
// Get a map from the current cached route.
// The return value is a byte array for
// the GIF image.
//
// index == 0 for the overview map
// index <= segmentNum for a segment map
public byte [] getMap (int index,
int width, int height) throws Exception {
// Method body
}
}

Note

You have to call the getDirections() method to obtain the route before you can retrieve any map.

The MPClient facade class aggregates driving direction services for illustration purposes only. In real-world, location-based applications that require more functionalities, you should design and implement facade gateways that fit your own application needs.