Spectrum™
Technology Platform
Version 8.0.0 SP2
Information in this document is subject to change without notice and does not represent a commitment on the part of the vendor or its representatives. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, without the written permission of Pitney Bowes Software Inc., One Global View, Troy, New York 12180-8399.
©2013 Pitney Bowes Software Inc. All rights reserved. Pitney Bowes Software Inc. is a wholly-owned subsidiary of Pitney Bowes Inc. Pitney Bowes, the Corporate logo, MapInfo, Group 1 Software, and MapInfo Professional are [registered] trademarks of Pitney Bowes Inc. or a subsidiary. All other trademarks are the property of their respective owners. United States: Phone: 518.285.6000 Fax: 518.285.6070 Sales: 800.327.8627 Government Sales: 800.619.2333 Technical Support: 518.285.7283 Technical Support Fax: 518.285.7575 www.pb.com/software Canada: Phone: 416.594.5200 Fax: 416.594.5201 Sales: 800.268.3282 Technical Support:.518.285.7283 Technical Support Fax: 518.285.7575 www.pb.com/software Europe/United Kingdom: Phone: +44.1753.848.200 Fax: +44.1753.621.140 Technical Support: +44.1753.848.229 www.pitneybowes.co.uk/software Asia Pacific/Australia: Phone: +61.2.9437.6255 Fax: +61.2.9439.1773 Technical Support: 1.800.648.899 www.pitneybowes.com.au/software
Contact information for all Pitney Bowes offices is located at:www.pb.com/contact-us.
Products named herein may be trademarks of their respective manufacturers and are hereby recognized. Trademarked names are used editorially, to the benefit of the trademark owner, with no intent to infringe on the trademark.
Contents
Chapter 1: Introduction...5
What Is Location Intelligence?...6
What Is the Location Intelligence Module?...6
Location Intelligence Module Capabilities...6
Chapter 2: Installing Location Intelligence Module Services...9
Installing the Server...10
Installing the Clients...10
Chapter 3: Configuring the Web Services...11
About Web Service Configurations...12
How to Change Web Service Configuration Settings...12
Chapter 4: Managing the Location Intelligence Module Repository...13
The Purpose of the Repository...14
Repository Contents...14
Named Tables...14
Named Layers...14
Named Maps...15
Named Tiles...15
Named Styles...15
Managing the Repository...15
Managing Named Resources...15
Managing Users...16
Chapter 5: Accessing Location Intelligence Module Services...17
Via Stages...18
Request Types...19
Web Service Documentation...20
Using a Client Application...20
Using a Browser-based Application...22
Chapter 6: Learning More About the Web Services...29
Feature Service...30
Geometry Service...31
Map Tiling Service...31
Mapping Service...32
Named Resource Service...33
User Management Service...34
Catalog Service for the Web...34
Web Feature Service...35
Web Map Service...36
Chapter 7: Sample Applications...37
REST Samples...38
List the Named Tiles In the Repository...38
List the Named Maps In the Repository...39
SOAP Samples...40
1
Introduction
Welcome to the Spectrum™Technology Platform Location Intelligence Module Getting Started Guide. This guide covers the basic concepts you need to get started using Location Intelligence Module services, such as:
• What the Location Intelligence Module is
• What services are provided by the Location Intelligence Module • How you access the services
• What the Location Intelligence Module repository is
In this section:
•
What Is Location Intelligence? . . . .6
What Is Location Intelligence?
Location intelligence is:
• An awareness of relationships between location information and business analysis and operations • The ability to use the understanding of geographic relationships to predict how it impacts a business
or organization
• The capability to react to how location influences an organization by changing business processes in order to minimize risk and maximize opportunities
Location Intelligence enables a business to measure, compare and analyze its data from business oper-ations, in conjunction with external data such as transportation networks, regulatory jurisdictions, market characteristics or its own customers.
What Is the Location Intelligence Module?
The Location Intelligence Module enables an organization to rapidly integrate location information into business applications and processes. This enables organizations to create and embed maps, understand spatial relationships, and carry out spatial calculations. The Location Intelligence Module provides support for standards-based geospatial information sharing through support for certifiedOGCweb services. The Location Intelligence Module provides support for integration at three levels:
• Web application development- Rapid application development user interface components and JavaScript API
• Web service integration- Support for SOAP, REST and certifiedOGCweb services (WMS, WFS, CSW)
• Data integration- Batch and transactional integration of spatial data sources
The Location Intelligence Module is part of the Spectrum Spatial solution encompassing: • Location Intelligence Module
• Enterprise Geocoding Module • Enterprise Routing Module
Location Intelligence Module Capabilities
The Location Intelligence Module offers the following capabilities: • Map-based data visualization and analysis
• Feature querying and searching
• Geometry operations including measurements (area, perimeter, length), predicates (within, contains, intersects), geometry manipulation (union, buffer, intersection) and coordinate transformation Some of the things these capabilities enable you to do are:
• Determine which sites are nearest to a given location • Determine whether or not a location resides in a given area
• Query a spatial database using spatial functions as well as standard SQL functions
• Perform a variety of calculations on spatial data, such as determining the area of a polygon, determining the distance between two points, or measuring the perimeter of an area
• Return a geometry object that represents the union of two input geometry objects
7 Getting Started Guide
2
Installing Location
Intelligence Module Services
The Location Intelligence Module is a component of the Spectrum™Technology Platform. Use the steps provided in the following sections to install the Spectrum™ Technology Platform.
You must install the Spectrum™Technology Platform server before you can install the Spectrum™Technology Platform clients.
Note:
In this section:
•
Installing the Server . . . .10
Installing the Server
1. Insert the Spectrum™Technology Platform DVD and run the installer.
2. When prompted, enter the access keys provided on your shipment's packing slip and shipment noti-fication email. You can also download your access keys fromwww.g1.com/support.
3. If you are installing on Windows, the Spectrum™Technology Platform server will automatically start running. Right-click the Spectrum™Technology Platform icon in the system tray and selectStop
Server.
Installing the Clients
Youmustuninstall your current clients before installing the 8.0 clients.
Note:
1. On the computer where you installed Spectrum™Technology Platform, start the Spectrum™ Tech-nology Platform server.
• On Windows, right-click the Spectrum™Technology Platform icon in the system tray and select
Start Server.
• On Unix and Linux, change the working directory to thebindirectory of where Spectrum™ Technology Platform is installed and type:. ./setupfollowed by./server.start.
2. On the computer where you want to install Management Console, Enterprise Designer, and/or Inter-active Driver, open a web browser and go to:http://hostname:portnumber. For example, if your host server is named "myserver" and it uses the default HTTP port 8080, you would go to: ht-tp://myserver:8080. Note that you can install clients only on Windows computers.
3. If you do not have Microsoft .NET 4.0 installed, clickMicrosoft .NET Frameworkand install it.
4. ClickClient Installersand follow the prompts to complete installation of Management Console, En-terprise Designer, and/or Interactive Driver.
5. Once installed, you can launch Management Console, Enterprise Designer, or Interactive Driver from the Windows Start menu. Go toPitney Bowes>Spectrum™Technology Platform>Client Tools.
3
Configuring the Web
Services
This section provides information about how to configure the Location Intelligence Module web services.
In this section:
•
About Web Service Configurations . . . .12
About Web Service Configurations
You can, and frequently must, explicitly specify the desired behavior of the Location Intelligence Module web services via settings in each web service's configuration file. The configuration file for each web service is held in theLocation Intelligence Module repositoryas a named configuration.1
Named configurations are not like other named resources that are held in the repository. You cannot use the Named Resource Service to access named configurations. Instead, you must use a WebDAV tool of your choice, such as DAVExplorer or Windows web folders.
Note:
For information about the name and location of each web service's named configuration in the repository, as well as a list of the configuration parameters for each web service, refer to theweb service docu-mentation.
How to Change Web Service Configuration Settings
To change web service configuration settings:
1. Pull the named configuration file for the web service out of the repository using your favorite WebDAV tool.
You cannot use the Named Resource Service to extract a named configuration file from the repository.
Note:
2. Using a text editor, make any required changes to the named configuration file.
3. Re-add the named configuration file back into the repository using your favorite WebDAV tool. You cannot use the Named Resource Service to add a named configuration file to the repos-itory.
Note:
4. Do one of the following to reload the web service configuration: • Restart the web service.
• Use the Spectrum™Technology Platform JMX Console (available athttp://hostname[:
port-number]/jmx-console) to reload the configuration without restarting the web service.
1 The Geometry Service alone does not have a corresponding named configuration because the Geometry
Service has no configurable settings.
4
Managing the Location
Intelligence Module
Repository
This section discusses the Location Intelligence Module repository: what it's for, what it holds, and how to manage it.
In this section:
•
The Purpose of the Repository . . . .14
•
Repository Contents . . . .14
The Purpose of the Repository
Whether you are accessing the Location Intelligence Module services viastagesorweb services, the services require access to map data to perform their various functions. The purpose of the repository is to hold the map data definitions that are required by the Location Intelligence Module services.
Repository Contents
The Location Intelligence Module repository holds map data definitions in the form of named resources. A named resource is a file that defines the attributes of a particular mapping resource, such as the location of a spatial database or the styles with which a map is to be rendered. Attaching names to resources offers the following advantages:
• Allows a resource to be known by its name and not by its properties.
• Allows a resource to be located in one spot but be referenced from many locations, which makes ad-ministration of resources easier.
• To change the look or behavior of applications or data, only the resource needs to be changed, not each application or data file.
Named Tables
A named table defines the properties of a mapping data source, such as a connection to a database that contains tables, or a connection to a particular database table.
The spatial data contained in a data source is what is used to construct a map layer. Currently, the supported data sources are:
• TAB file • Shape file • Oracle database • SQL Server database
• PostgreSQL/PostGIS database
For more information about named tables, see theNamed Resources Guide.
Named Layers
A named layer defines the properties of a map layer. Map layers are used to make up a map, and a map is always composed of at least one map layer. Each map layer is populated with spatial data from a data source such as a TAB file.
For more information about named layers, see theNamed Resources Guide.
Named Maps
A named map defines the properties of a map, that is, the data, themes, and display conditions that define the content and appearance of a map. A map is always composed of at least one map layer. For more information about named maps, see theNamed Resources Guide.
Named Tiles
A named tile defines the properties of a map tile. A map tile is a rectangular piece of a map and, like pieces of a jigsaw puzzle, map tiles fit together to make up an entire map. A named tile defines the bounds of the map tile and the larger map that the tile is part of. Dividing a map into separate map tiles can greatly reduce the time required to display a map, particularly if you want to display only a small part of it.
For more information about named tiles, see theNamed Resources Guide.
Named Styles
A named style defines the properties of a map style. Styles enable you to control the visual appearance of your maps by specifying the visual characteristics of various map elements, such as lines, filled areas, and symbols.
For more information about named styles, see theStyles Guide.
Managing the Repository
The job of managing the Location Intelligence Module repository entails performing two basic tasks: • Getting named resources into and out of the repository
• Deciding which users can access which named resources, and setting permissions accordingly
Managing Named Resources
Depending on what you want to add to or delete from the Location Intelligence Module repository, you can use any one of the following tools.
Using Management Console
If you want to add a named table that references a TAB file, Shape file, or database table to the repository, you can use Management Console.
For more information about how to add named tables to, or delete named tables from, the Location In-telligence Module repository using Management Console, see the section entitled "Named Tables" in the "Location Intelligence Module" chapter of the Spectrum™Technology PlatformUser's Guide.
15 Getting Started Guide
Using the MWS Uploader Utility
If you want to convert a MapInfo Workspace (MWS) file to a named map, and add the named map to the repository, you can use the MWS Uploader Utility.
For more information about the MWS Uploader Utility, see theMWS Uploader Utilityguide.
Using the Named Resource Service
You can use the Named Resource Service to manage almost any type of named resource in the repos-itory.2This service provides a set of common operations that you can use to add, list, update, delete, and search resources in the repository. The advantage of this is that you can administer the repository's resources at the service level, with a simple SOAP API that allows you to manage your content. The Named Resource Service provides operations that:
• List all resources (or a subset) in the repository • Add a resource to the repository
• Modify a resource that exists in the repository • Delete a resource from the repository
• Read a resource from the repository to return the definition • Search for resources in the repository
For more information about the Named Resource Service, see theNamed Resource Service Reference.
Managing Users
To manage users' access to the named resources in the repository, you use the User Management Service. The User Management Service provides a simplified interface to manage security for the repos-itory, focused on how to restrict who can access the resources in the repository. Setting security allows you to expose or restrict different resources (subsets of your data and resources) to different users or departments. To enforce this, security has been added to the Location Intelligence Module that allows you to specify which users get to see what resources.
The Location Intelligence Module repository security is managed using an internal ACL (Access Control List). This allows you to specify which users are granted access to resources, as well as what operations are allowed on given resources. The operations for repository user management are performed using the User Management SOAP interface.
For more information about the User Management Service, see theUser Management Guide.
2
Named configurations are the only named resource that you cannot manage using the Named Resource Service. To access named configurations in the repository you must use a WebDAV tool of your choice, such as DAVExplorer or Windows web folders.
5
Accessing Location
Intelligence Module Services
There are two distinct ways to access the services provided by the Location Intel-ligence Module.
The first way is to construct a dataflow in Enterprise Designer that includes one or more Location Intelligence Module stages.
The second way is to submit an HTTP request directly to a Location Intelligence Module web service, from either a web browser or from a client application. Each of these two ways is discussed in the following sections.
In this section:
•
Via Stages . . . .18
Via Stages
To access Location Intelligence Module services via stages, you build and run a dataflow in Enterprise Designer that includes one of more Location Intelligence Module stages. The stages use a direct socket-based method to communicate with the corresponding Location Intelligence Module services.
The following Location Intelligence Module stages are available in the Enterprise Designer: • Closest Site– Determines which sites are closest to a given location.
• Find Nearest– Locates the points of interest (POI) that are nearest to a given location. • Point In Polygon– Determines whether or not a location resides in a given area.
• Query Spatial Data– Allows you to query a spatial database using spatial functions as well as standard SQL functions.
• Read Spatial Data– Allows you to access spatial data in a variety of commonly-used spatial data formats.
• Spatial Calculator– Performs a variety of calculations on spatial data, such as determining the area of a polygon, determining the distance between two points, or measuring the perimeter of an area, among other functions.
• Spatial Union– Returns a geometry object which represents the union of two input geometry objects.
For more information about Location Intelligence Module stages, see the "Location Intelligence Module" chapter in the Spectrum™Technology Platform User's Guide.
Via Web Services
To access Location Intelligence Module services via the web services, you construct an HTTP request and submit it directly to the web service. The HTTP request can be in the form of a SOAP request, a REST request, or a POST/GET request, and can be submitted directly from a web browser or from a client application.
The Location Intelligence Module services are exposed as the following web services: • Feature Service– Provides the ability to search spatial databases.
• Geometry Service– Provides a simplified interface to perform Geometry Service measurements, conversions, and operations.
• Map Tiling Service– Generates map tiles that can be combined to form larger map images. • Mapping Service– Provides a simplified interface to perform Mapping Service rendering, themes,
overlays, and conversions.
• Named Resource Service– Provides the ability to work with resources in the Location Intelligence Module repository.
• User Management Service– Provides a simplified interface to manage security for the Location In-telligence Module repository, focused on how to restrict who can access the resources in the repository. • Catalog Service for the Web *– Enables an application to publish and search collections of descriptive
information (metadata) for data, services, and related information.
* Indicates anOGC-compliant web service.
• Web Feature Service*– Used for searching, obtaining metadata descriptions, querying, and filtering spatial data (feature types) at the service level.
• Web Map Service*– Enables software clients to reference map images over the Internet or a private intranet.
For more information about each of the web services listed above, seeLearning More About the Web Serviceson page 29.
Request Types
Depending on the web service, you can submit an HTTP request to a Location Intelligence Module web service in one of the following forms:
• a SOAP request • a REST request • a POST/GET request
SOAP is short for Simple Object Access Protocol. A SOAP request message must be in the XML format that is defined by the SOAP specification.
REST is short for Representational State Transfer. A REST request message is contained in the query string parameters of an HTTP request.
A POST/GET request message can be structured either as query string parameters submitted via HTTP GET, or as an XML-formatted message submitted via HTTP POST. The XML-formatted message is identical to a regular SOAP request, but with the SOAP XML wrapper removed.
Many of the web services can accept requests in more than one form. For example, the Feature Service can accept either a SOAP request or a REST request. Some services, however, can accept a request in only one form. For example, the Map Tiling Service can accept only a REST request, and the Web Map Service can accept only a POST/GET request.
The following table lists the types of request that each web service can accept.
POST/GET REST SOAP Web Service Feature Geometry Map Tiling Mapping Named Resource User Management
Catalog Service for the Web * Web Feature*
Web Map*
* Indicates anOGC-compliant web service.
19 Getting Started Guide
Web Service Documentation
To see the full documentation for each Location Intelligence Module web service, click on the links below: Feature Service:SOAP REST
Geometry Service Map Tiling Service
Mapping Service:SOAP REST Named Resource Service User Management Service Catalog Service for the Web Web Feature Service Web Map Service
Using a Client Application
This section describes the steps required to create a client application (such as a Java client) that accesses the Location Intelligence Module web services using SOAP requests.
About Stub Code
To create a client application that can invoke the Location Intelligence Module web services, you use a tool to generate the stub code for the application. The tool generates the stub code from the web service operations described in a service's Web Services Description Language (WSDL) document. Once the stub code has been generated, its methods provide a proxy for the web service operations.
WSDL URLs
To generate the stub code for your client application, you need to tell your stub code generator where to find the web service's WSDL document. The URLs for the WSDL documents will vary from installation to installation, but all installations have the following basic patterns:
• http://on.premise.domain/soap/MappingService?wsdl
• http://on.premise.domain/soap/FeatureService?wsdl
• http://on.premise.domain/soap/GeometryService?wsdl
• http://on.premise.domain/soap/NamedResourceService?wsdl
• http://on.premise.domain/soap/CSWService?wsdl
Generating Stub Code for a Java Client
Use the following steps to generate the stub code for a Java web services client application, using the wsimporttool that is included with the Java Development Kit.
1. Open an xterm or command prompt window and change to the directory that contains thewsimport program, usuallyJDK_install_dir/bin/.
2. At the command prompt, typewsimport -s source_dir -d classes_dir URL_TO_WSDL and press Enter.
For example, to generate stub classes for the SAAS version of the Named Resource Service, you might enter the following command:
wsimport -s output/source -d output/classes
http://stratus-dp-dev.nw.pb.com/NamedResourceService/services/NamedResourceService?wsdl After the command has been executed, the generated source.javafiles are placed within the directory you specified with the-soption, and the compiled.classfiles are placed within the directory you specified with the-doption.
Adding a Web Reference in Eclipse
To develop Java programs that consume Location Intelligence Module web services in Eclipse, you first create a reference to the web service in your Java project. When the reference is created, the client-side stub code required to use the web service is generated.
1. Start Eclipse.
2. On theFilemenu, selectNew>Project. TheNew Projectwizard opens.
3. In theNew Projectwizard, selectJava>Java Project. ClickNext.
4. In theProject Namefield, enter the name you want to give your project. ClickFinishto close the wizard.
The new project folder appears in thePackage Explorer.
5. In thePackage Explorer, right-click on the project folder you created in the previous step. On the pop-up menu, selectNew>Other.
TheNewwizard opens.
6. In theNewwizard, selectWeb Services>Web Service Client. ClickNext.
7. In theService Definitionfield, enter theURL to the web service's WSDL document. SelectDevelop Clienton the slider bar.
ClickFinishto close the wizard.
The stub code for the web service is generated in the project folder.
Adding a Web Reference in Visual Studio
Before you can use web reference facilities in your C# program code, you must first add the web reference to your Visual Studio project.
Use the following steps to add a web reference to any of the Location Intelligence Module web services.
1. Start Visual Studio.
2. On theFilemenu, selectNew>Project. TheNew Projectdialog box opens.
21 Getting Started Guide
3. In theNew Projectdialog box, enter the desired settings, then clickOK.
4. In theSolution Explorerpane, right-click onReferences. On the pop-up menu, selectAdd Web Reference.
TheAdd Web Referencedialog box opens.
5. In theAdd Web Referencedialog box, enter theURL to the web service's WSDL document. After you have entered the URL, click theGobutton. Documentation for the web service then appears under theURLfield.
6. In theAdd Web Referencedialog box, note the web reference name provided in theWeb Reference Namefield, then click theAdd Referencebutton.
The web reference is added to the project.
After you have completed these steps, you can see the new web reference in theSolution Explorer
pane.
Using a Browser-based Application
You can create powerful mapping applications that run entirely in a web browser, using the RIA controls installed with Spectrum™Technology Platform. This section describes what the RIA controls are, and how to get started using the RIA controls in your web applications.
What Are the RIA Controls?
The RIA (Rich Internet Application) controls provide a set of browser-based user interface components for easily embedding maps and other location-based capabilities in web pages. A JavaScript API is also provided which, together with the user interface components, enable you to create custom browser-based mapping applications.
The RIA controls can be used in a wide range of scenarios, from simply embedding maps in your web site to show locations, to creating rich web applications. Built entirely in JavaScript, the controls work without the need for any browser plug-ins and without having to write any server-side code. The RIA controls use Web 2.0 techniques to provide functionality such as seamless map panning and the ability to search and display information without requiring a web page refresh.
The following controls are available:
Description Control
A user interface control containing descriptive information about features appearing on a map. It also provides the means to show and hide individual overlays on a map.
LegendControl
A non-user interface control, that lets developers write Javascript code to call the FeatureService REST API. This control can be FeatureService
used to query tables for features. Search results are returned as GeoJSON FeatureCollections. The search call is performed asyn-chronously.
A non-user interface control, that lets developers make FeatureSer-vice REST calls against multiple tables simultaneously. This is a Multi-table FeatureService
convenience class, allowing a feature search on multiple tables which is useful when a feature search is triggered by interactions with a map, that typically display the features of multiple tables
Description Control
stacked on top of each other. For example, a SearchNearest against TABLE1 and TABLE2 at a given point (x,y).
An easy way to display either a MappingService NamedMap or a TileService map tile on an OpenLayers map.
OpenLayers layer types
Template formatting controls for developers to display JSON data in an OpenLayers popup (for example) but intelligently styled. For Generic data formatting
example, a Table name underlined, field names in italics, and field values in bold.
REST-ful service control for developers to send cross-domain calls to the REST services. These calls will be performed as asynchron-ous XMLHttpRequest calls.
REST Services
Getting Started with the RIA Controls
The RIA controls are installed with Spectrum™Technology Platform. To get started using these controls, you are provided with the following:
1. Java Servlet Proxy download located athttp://localhost:8080/ria-examples/riaproxy/riaproxy.war
2. IIS (.NET) Proxy download located athttp://localhost:8080/ria-examples/riaproxy/riaProxy.zip
3. Controls JavaScript hosted athttp://localhost:8080/ria/ria.js
4. JavaScript API Documentation hosted athttp://localhost:8080/ria/api/, or can be accessed at the Spectrum™Technology Platform documentation site here: http://reference.mapinfo.com/soft-ware/spectrum/lim/8_0/ria/api/index.html.
5. RIA example application hosted athttp://localhost:8080/ria-examples/.
Using these resources and the instructions provided in this guide, you will be able to get the RIA proxy installed in your environment, run the example RIA controls, and start developing your own RIA-control-based application.
Developing with the RIA Controls
To develop with the RIA controls on your own machine or to place applications developed with RIA controls on another server, you will need to install the RIA proxy. The following link from Yahoo provides background information on why proxy pages are needed:
http://developer.yahoo.com/javascript/howto-proxy.html
The RIA proxy is required to start working with the RIA Controls. Simply reference the relevant JavaScript file hosted by Spectrum™Technology Platform in your html pages, and the browser takes care of the rest. To get started developing an RIA control based application:
1. Have a web application server (for example, Tomcat) installed on your machine.
2. Create a new service folder in yourwebapps(or equivalent) directory for your application (for example, myapp).
3. Create your application pages in your newly created service folder, using the functionality of the Spectrum™Technology Platform JavaScript API.
23 Getting Started Guide
You can use the RIA examples that ship with Spectrum™Technology Platform as a starting point for your applications. View the page source of the examples here: http://localhost:8080/ria-ex-amples/.
4. Download the riaproxy.war file from Spectrum™Technology Platform and copy it to yourwebapps (or equivalent) directory.
For information on how to download the RIA proxy, and on why you must use the proxy, see the section:Using the RIA Proxyon page 24.
5. Restart your application server.
Using the RIA Proxy
Several RIA controls depend on a server side component to be fully functional. For example, the Fea-tureService calls a server in order to query spatial data that isn't directly available in the browser. However, due to security restrictions that are put in place by all modern browsers, it is not possible to call any ar-bitrary server on the web.
The RIA controls require a proxy in order to work around those security restrictions. The following sections describe why this is necessary and how a proxy can be used for your own application development.
Installing the RIA Proxy
Spectrum™Technology Platform ships with two proxy implementations, one for Java Servlet containers (2.4 and higher) and one for IIS.
Java Servlet Proxy
Download the proxy binary from your Spectrum™Technology Platform installation at: http://local-host:8080/ria-examples/riaproxy/riaproxy.war.
Once downloaded, you can deploy it to a web application server of your choice. Please refer to the documentation of the application server for details on deploying WAR files.
If you are using Apache Tomcat, copy the WAR file into the %CATALINA_HOME%\webapps directory. As long automatic application deployment is enabled and you keep the WAR file name intact, the proxy will be made available under the default context path ofriaproxy.
If you decide to deploy the proxy under a different context path, please make sure to provide the correct value when following the step to define the path to the proxy in your web application. This step is defined in the section:Define the Path to your Proxyon page 27
Note:
Once the proxy has been installed, a trusted base URL needs to be set. URLs that do not start with this value will not be relayed by the proxy. This is necessary to prevent the proxy from being abused to request resources from other domains than the one required by the RIA controls. To configure this:
1. Open the proxy.properties file located within the ...\riaproxy\WEB-INF folder.
2. Set the value of the trusted.base.url property to http://servername, where servername is a placeholder for the hostname RIA is installed on.
3. Restart the proxy application.
For example:
• trusted.base.url=http://localhost:8080
To enable HTTP Basic Authentication, the following properties need to be set:
1. auth.type=basic
2. anonymous_username=username
3. anonymous_password=password
Replace username and password with the actual login credentials to be used by the proxy. Please note that this performs HTTP basic authentication against the RIA server-side component on behalf but transparent to the client. Requests by the client to the proxy are not protected and additional steps have to be taken if that is necessary. Please consult the documentation of your application server for further details.
IIS Proxy
Download the proxy binary from your Spectrum™Technology Platform installation at: http://local-host:8080/ria-examples/riaproxy/riaProxy.zip.
Once downloaded, unzip the file and run setup.exe to install the proxy into IIS. You can deploy it to a web application server of your choice. Please refer to the documentation of the application server for details on deploying WAR files.
The configuration of the IIS proxy is equivalent to the Java Servlet proxy, in that you need to configure the base URL and authentication. The only difference is the configuration file is located at …\ProxySer-vice\Web.config. The Web.config file is an XML file and configuration properties are set with<add> elements nested inside the<appSettings>element of the file.
For example:
• <add key=”trusted.base.url” value=http://localhost:8080/>
Verification
Once you have installed the proxy and set it to forward the requests to the RIA application, you can test it by accessing the RIA JavaScript file, ria.js directly and through the proxy. Suppose RIA is installed on 'myserver' on port 8070 and the proxy is installed on the localhost using the default name of riaproxy on default port 80, the two URLs are as shown below:
• http://myserver:8070/ria/ria.js
• http://localhost/riaproxy/proxy.aspx?url=http%3A%2F%2Fmyserver%3A8070%2Fria%2Fria.js Compare the pages loaded by the two URLs and make sure they are same.
Why use the RIA Proxy?
The same-origin policy is a security restriction on what web content JavaScript code can interact with. Essentially, it dictates that a running script can only interact with data coming from the same origin as the server hosting the page or application upon which the code is running. This is especially important for applications using AJAX (Asynchronous JavaScript and XML) techniques like RIA controls as it means that our requests may only be made back to the host server.
The RIA controls require a proxy in order to work around those security restrictions. The following sections describe why this is necessary and how a proxy can be used for your own application development.
25 Getting Started Guide
Origin Concept
The origin in the same-origin policy means the same host, but there are a few specifics that should be noted. The following table illustrates whether the same origin when compared with a base origin of www.example.com:
Note Same-Origin URL
Same protocol and host true
http://www.ex-ample.com/dir/page.html
Same protocol and host true
http://www.ex-ample.com/dir2/other.html
Same protocol and host but different port false http://www.ex-ample.com:81/dir2/other.html Different protocol false https://www.ex-ample.com/dir2/other.html Different host false http://en.example.com/dir2/oth-er.html
Different host (exact match required) false
http://example.com/dir2/oth-er.html
Different host (exact match required) false
http://v2.www.ex-ample.com/dir2/other.html Why is this Important?
In order to host applications on a different machine than directly on the server hosting RIA controls, we need a way to bypass the same-origin policy. This is particularly useful during application development, where developers typically want to run their code on a local machine. The local machine will typically use a hostname of localhost, or a machine name, and the server with the controls will have a different hostname, therefore and entirely different origin.
To achieve this, a proxy has been provided that will forward requests to a remote host and appear to the browser to still be in the domain. The Java proxy can be deployed to any Java servlet container that implements the Servlet 2.4 specification or higher.
The proxy simply takes a URL as a parameter and requests the page, passing the contents back to the requester. Given the proxy is installed on a server of a local machine on port 80, you can access the web pagehttp://myserver:8765/some/path/example.htmlby calling http://localhost/ri-aproxy?url=http://myserver:8765/some/path/example.html. The result sent by the proxy will be the same as if the target URL was accessed directly. The important difference is the second URL will be seen by a browser as part of the local domain http://localhost/ instead of http://myserver:8765/. Please note that the URL parameter needs to be encoded properly to follow the syntax rules of Internet URLs (conf. RFC 1738: Uniform Resource Locators).
Using the RIA Proxy in your Web Application
This section describes how to use the RIA proxy in your web application.
Import ria.js
The first step is to import OpenLayers and the main RIA JavaScript library. This can be done as follows: <script type="text/javascript" src="http://localhost:8080/ria/openlayers/Open-Layers.js"></script>
<script type="text/javascript" src="http://localhost:8080/ria/ria.js"></script>
Replacelocalhost:8080with the actual hostname and port number RIA is installed on.
Define the Path to your Proxy
To indicate that cross-domain calls should be routed through a proxy, the path to the proxy has to be registered like this:
ria.RestService.addProxy("/riaproxy?url=");
Rather than calling a URL to a different domain directly, the RIA library code will append the encoded URL to the end of the path registered above and use the result to perform the request. The proxy takes the URL from the request parameter (by default url) , requests the resource associated with it and sends the result back to the RIA library code without any modifications. The exact path passed to the addProxy() method depends on which proxy is being used and how the proxy was deployed.
The path above is the default for the Java Servlet proxy. For the IIS proxy, use the path /ri-aproxy/Proxy.aspx?url=.
Note:
Final Code Sample
A simple page for performing a Feature Search: <!DOCTYPE html> <html> <head> <script src="http://localhost:8080/ria/openlayers/OpenLay-ers.js"></script> <script src="http://localhost:8080/ria/ria.js"></script> </head> <body> <button onclick="search();">Search</button> <script> ria.RestService.addProxy("/riaproxy?url="); function search() {
var fs = new ria.search.FeatureService(
"http://localhost:8080/rest/Spatial/FeatureService"); var d = fs.searchNearest({
table: "/NamedTables/WorldcapTable",
geometry: new OpenLayers.Geometry.Point(12.875977, 47.813155), srs: "epsg:4326", attributes: ["Capital"], withinDistance: "2000 mi", distanceAttributeName: "dist", 27 Getting Started Guide
maxFeatures: 10 }); d.addCallback(function(result) {alert(result.features.length + " result(s)")}); } </script> </body> </html
6
Learning More About the
Web Services
This section provides a brief overview of each of the Location Intelligence Module web services.
In this section:
•
Feature Service . . . .30
•
Geometry Service . . . .31
•
Map Tiling Service . . . .31
•
Mapping Service . . . .32
•
Named Resource Service . . . .33
•
User Management Service . . . .34
•
Catalog Service for the Web . . . .34
•
Web Feature Service . . . .35
Feature Service
DescriptionThe Feature Service provides the ability to search spatial databases. It provides a set of common oper-ations that you can use to query content, regardless of the underlying data provider. The advantage of this is that you can run the exact same operation against many different content stores (such as a native TAB file, an Oracle database table, or a SQL Server database table) by specifying different named tables; the same query will work on each table type.
The Feature Service provides operations that: • list all tables in the catalog
• describe specific tables in the catalog • search within a distance
• search intersects • search within a polygon • search for the nearest feature
• search using a custom MapInfo SQL query
Service URLs
The URL endpoint for the REST implementation of the Feature Service has the following general form: http://hostname[:portnumber]/rest/Spatial/FeatureService
The URL endpoint for the SOAP implementation of the Feature Service has the following general form: http://hostname[:portnumber]/soap/FeatureService
The URL for the Feature Service WSDL document has the following general form: http://hostname[:portnumber]/soap/FeatureService?wsdl
The URL for the Feature Service demo page has the following general form:
http://hostname[:portnumber]/Spatial/FeatureService/DemoPage.html
Documentation
To see the full documentation for the SOAP implementation of the Feature Service, refer to theFeature Service Reference.
To see the full documentation for the REST implementation of the Feature Service, refer to theREST Interfacesguide.
Geometry Service
DescriptionThe Geometry Service provides a simplified interface to perform Geometry Service measurements, conversions, and operations. The Geometry Service provides four different types of capabilities: • Aggregate (buffer, centroid, envelope, union, intersection, convex hull, difference, symdifference) • Transformation (coordinate transformations)
• Measurement (area, distance, length, perimeter) • Predicate (contains, intersects, within)
This service provides a set of common operations that you can use to perform operations on content, regardless of the data provider. One advantage is that you can run the exact same operation against many different content repositories (e.g., a native TAB file, an Oracle table, or a SQL Server table) by specifying different named tables; the same operation will work on each table type. Using the Geometry Service, you only need to worry about the request, not the location or type of data in the repository. The Geometry Service is based on the well known mathematical concepts described in the OGC Simple Features Specification.
Service URLs
The URL endpoint for the Geometry Service has the following general form: http://hostname[:portnumber]/soap/GeometryService
The URL for the Geometry Service WSDL document has the following general form: http://hostname[:portnumber]/soap/GeometryService?wsdl
The URL for the Geometry Service demo page has the following general form:
http://hostname[:portnumber]/Spatial/GeometryService/DemoPage.html
Documentation
To see the full documentation for the Geometry Service, refer to theGeometry Service Reference.
Map Tiling Service
DescriptionThe Map Tiling Service dynamically generates subsets of a map on a per-request basis. This subset is called a tile. The tiles generated from the Map Tiling Service can be used individually, or combined to form larger maps, in applications for seamless map interaction. This service provides fast, simple, light-weight map rendering where more complex map rendering can be performed using the Mapping Service.
31 Getting Started Guide
The Map Tiling Service allows the hosting of multiple maps that can be used to generate the tiles. These named maps are located in one or more map repositories. Each map hosted by the Map Tiling Service can have a specific configuration that defines how the map will be used to create tiles.
The built-in pluggable caching mechanism is an important feature of the Map Tiling Service. When this caching is turned on, tiles are stored so serving of tiles to the client is both faster and less resource in-tensive. This also allows the pregeneration of tiles and pointing the Map Tiling Service to this cache.
Service URLs
The URL endpoint for the Map Tiling Service has the following general form: http://hostname[:portnumber]/rest/Spatial/MapTilingService
Documentation
To see the full documentation for the Map Tiling Service, refer to theMap Tiling Serviceguide. To walk through the steps for creating and using map tiles, seeMap Tilingin the How Do I? section.
Mapping Service
DescriptionThe Mapping Service provides a simplified interface to perform Mapping Service rendering, themes, overlays, and conversions. The Mapping Service provides both simple operations that are more frequently used, or more complex operations that require higher levels of customization.
The Mapping Service provides operations that:
• list and get all maps, layers, styles, or tables in the repository
• conversion methods between real world coordinates, XY, and screen coordinates • screen calculations such as length
• navigation methods such as zoom, and pan • render maps and layers
• overlay, override, and theme maps
• customize your map with legends, watermarks, and other adornments.
In the past, mapping required the use of many map layers and map definitions to access data. With the addition of the table model and repository, data access and mapping is independent. The tables define the data access, and the repository takes care of the table management. Therefore, with the Mapping Service, you are able to render maps and perform mapping operations without the worry of where the data is located.
Service URLs
The URL endpoint for the REST implementation of the Mapping Service has the following general form: http://hostname[:portnumber]/rest/Spatial/MappingService
The URL endpoint for the SOAP implementation of the Mapping Service has the following general form: http://hostname[:portnumber]/soap/MappingService
The URL for the Mapping Service WSDL document has the following general form: http://hostname[:portnumber]/soap/MappingService?wsdl
The URL for the Mapping Service demo page has the following general form:
http://hostname[:portnumber]/Spatial/MappingService/DemoPage.html
Documentation
To see the full documentation for the SOAP implementation of the Mapping Service, refer to theMapping Service Reference.
To see the full documentation for the REST implementation of the Mapping Service, refer to theREST Interfacesguide.
Named Resource Service
DescriptionThe Named Resource Service provides the ability to work with resources in the repository. It provides a set of common operations that you can use to add, list, update, delete, and search resources in the repository. The advantage of this is that you can administer the repositories resources at the service level, with a simple SOAP API that allows you to manage your content.
The Named Resource Service provides operations that: • list all resources (or a subset) in the repository • add a resource to the repository
• modify a resource that exists in the repository • delete a resource from the repository
• read a resource from the repository to return the definition • search for resources in the repository
Service URLs
The URL endpoint for the Named Resource Service has the following general form: http://hostname[:portnumber]/soap/NamedResourceService
The URL for the Named Resource Service WSDL document has the following general form: http://hostname[:portnumber]/soap/NamedResourceService?wsdl
The URL for the Named Resource Service demo page has the following general form:
http://hostname[:portnumber]/Spatial/NamedResourceService/DemoPage.html
33 Getting Started Guide
Documentation
To see the full documentation for the Named Resource Service, refer to theNamed Resource Service Reference.
User Management Service
DescriptionThe User Management Service provides a simplified interface to manage security for the repository, fo-cused on how to restrict who can access the resources in the repository. Setting security allows you to expose or restrict different resources (subsets of your data and resources) to different users or depart-ments. To enforce this, security has been added to Spectrum™Technology Platform that allows you to specify which users get to see what resources.
The Location Intelligence Module repository security is managed using an internal ACL (Access Control List). This allows you to specify which users are granted access to resources, as well as what operations are allowed on given resources. The operations for repository user management are performed using the User Management SOAP interface.
Service URLs
The URL endpoint for the User Management Service has the following general form: http://hostname[:portnumber]/soap/UserManagementService
The URL for the User Management Service WSDL document has the following general form: http://hostname[:portnumber]/soap/UserManagementService?wsdl
The URL for the User Management Service demo page has the following general form:
http://hostname[:portnumber]/Spatial/UserManagementService/DemoPage.html
Documentation
To see the full documentation for the User Management Service, refer to theUser Management Guide.
Catalog Service for the Web
DescriptionThe Catalog Service for the Web (CSW) provides the ability to search, retrieve, and update collections of descriptive information (metadata) about geospatial data, services, and related resources. Catalogs are used to register metadata that conform to a specific information model or standard. You then have the ability to search for geospatial data and services in very efficient ways.
The CSW provides operations that:
• describe the service capabilities
• describe the information models (schema) supported by the catalog • search within the catalog
• get records based on a particular ID • insert, update, or delete catalog entries • batch retrieval and conversion of metadata
The Catalog Service for the Web is anOGC-compliant web service.
Service URLs
The URL endpoint for the POST/GET implementation of the Catalog Service for the Web has the following general form:
http://hostname[:portnumber]/rest/Spatial/CSW
The URL endpoint for the SOAP implementation of the Catalog Service for the Web has the following general form:
http://hostname[:portnumber]/soap/CSWService
The URL for the Catalog Service for the Web WSDL document has the following general form: http://hostname[:portnumber]/soap/CSWService?wsdl
The URL for the Catalog Service for the Web demo page has the following general form: http://hostname[:portnumber]/Spatial/CSWService/DemoPage.html
Documentation
To see the full documentation for the Catalog Service for the Web, refer to theCatalog Service for the Web Reference Guide.
Web Feature Service
DescriptionThe Web Feature Service is used for searching, obtaining metadata descriptions, querying, and filtering spatial data (feature types) at the service level. The XML interface and syntax follow the WFS 1.0.0 OGC specification. Both SOAP and HTTP POST/GET requests are supported. As a result, a standard compliant WFS client, such as MapInfo Professional, can access data by submitting an XML request through HTTP to display it on a map or to get vector geometries for calculations.
Use the Web Feature Service to help perform a search for features within a given distance from a point (or other type of geometry). For example, a real estate application determines a realistic value for a home by comparing the distance of it to numerous features, including railroad tracks, highways, shopping malls, and police stations. This application would call WFS to select a highway feature and a home (a point). The application would then calculate distance values for proprietary rating calculations. The Web Feature Service is anOGC-compliant web service.
35 Getting Started Guide
Service URLs
The URL endpoint for the Web Feature Service has the following general form: http://hostname[:portnumber]/rest/Spatial/WFS
Documentation
To see the full documentation for the Web Feature Service, refer to theWeb Feature Serviceguide.
Web Map Service
DescriptionThe Web Map Service (WMS) allows software clients to reference map images over the Internet or a private intranet. The WMS implementation is based on the WMS 1.1.1 and 1.3.0 OGC specification. Using HTTP requests, the WMS provides georeferenced data to a client that displays this data as an image. Georeferenced data is information associated with maps that describe the real world extents of specific features and the projection upon which it is based.
The images can be provided as GIF, JPEG, PNG, and other image formats. The Web Map Service is anOGC-compliant web service.
Service URLs
The URL endpoint for the Web Map Service has the following general form: http://hostname[:portnumber]/rest/Spatial/WMS
Documentation
To see the full documentation for the Web Map Service, refer to theWeb Map Serviceguide.
7
Sample Applications
In this section we're going to bring together the concepts discussed in the previous sections to create both REST and SOAP client applications.
In this section:
•
REST Samples . . . .38
REST Samples
This section provides examples that show you how to make REST requests from client applications.
List the Named Tiles In the Repository
This web page uses a JavaScript call to the Map Tiling Service's REST interface to list the named tiles in the repository. The list of named tiles that is returned in the response is then displayed in a JavaScript alert box.
Here is the code:
<html> <body>
<script type="text/javascript"> function submitform() {
//Create an XMLHttpRequest object or try ActiveX var req;
if (typeof XMLHttpRequest != "undefined") {
req = new XMLHttpRequest(); }
else {
try {
req = new ActiveXObject("Msxml2.XMLHTTP"); }
catch (e) {
req = new ActiveXObject("Microsoft.XHTTP"); }
}
// populate the request, username and password
var reqString = document.getElementById('request').value; var userName = document.getElementById('user').value; var password = document.getElementById('password').value; //Execute the REST request against a server secured with Basic Authentication
req.open("GET", reqString, false, userName, password); req.send();
//Display the response resp = req.response; alert(resp);
} </script>
<form action="javascript: submitform()">
User: <input type="text" name="User" id="user" value="admin"/> Password: <input type="password" name="Password" id="password" value="admin"/><br />
Request: <input type="text" name="request" id="request"
value="http://MyServer:8080/rest/Spatial/MapTilingService/mapList.json"/><br />
<input type="submit" value="Submit" /> </form>
</body> </html>
List the Named Maps In the Repository
This Java application calls the Mapping Service's REST interface to list the named maps in the repository. The list of named maps that is returned in the response is then output at the command line.
Here is the code:
public static void main(String[] args) {
java.io.InputStream is = null; try
{
// Create the REST request URL
String serverUrl = "http://MyServer:8080/rest/Spatial/MappingSer-vice/maps.json";
java.net.URL url = new java.net.URL(serverUrl);
java.net.HttpURLConnection conn = (java.net.HttpURLConnection)url.open-Connection();
String user = "user"; String password = "pass";
// Credentials need to be a base64 encoded string of the nature "user:pass"
String credentials = user + ":" + password;
byte[] encodedBytes =
org.apache.commons.codec.binary.Base64.encode-Base64(credentials.getBytes());
String base64EncodedString = new String(encodedBytes);
// Apply the authorization header - a string of nature "Basic <base64EncodedCredentialsString>"
String authHeader = "Basic" + " " + base64EncodedString; conn.addRequestProperty("Authorization", authHeader); // Get response for the request
is = conn.getInputStream();
java.io.ByteArrayOutputStream bos = new java.io.ByteArrayOutput-Stream();
org.apache.commons.io.IOUtils.copy(is, bos); is.close();
// Display the response
System.out.println(new String(bos.toByteArray())); } catch (Exception e) { System.out.println(e.getMessage()); 39 Getting Started Guide
} finally { org.apache.commons.io.IOUtils.closeQuietly(is); } }
SOAP Samples
This section provides examples that show you how to make SOAP requests from client applications.
Find the Nearest Five Subway Stations
This application enables a user to find the five nearest subway stations in Toronto, Canada. To create this application, we will:
1. Create a named table that references the subway stations table, and add it to the repository. This table contains the location data for each subway station.
2. Create a named map that references the map of Toronto and add it to the repository. This map will show the user where each subway station is.
3. Create Java code that will call on the Feature Service to locate each subway station, and the Mapping Service to generate an underlying map of Toronto so that the user can see where each subway station is situated.
Step 1: Add the Subway Stations Named Table to the Repository
The first step is to create a named table in the repository that references the subway stations table (a TAB file). The TAB file contains the location data for each subway station.
To create the named table in the repository, use the following steps:
1. Copy the subway stations TAB file to a location on the file system that is accessible to the Feature Service.
2. Open the Management Console and log in as an administrator.
3. ExpandModules>Location Intelligence>Toolsthen clickNamed Tables.
4. ClickAdd.
TheAdd Named Tabledialog box opens.
5. Enter the repository path and name for the new named table in theNamed table namefield. You must prepend the name of the named table with where in the repository the named table is going to be created. For example, if you are creating theSubwayStationsnamed table and are creating this named table in theNamedTablesdirectory in the repository, the name you would enter in the
Named table namefield would be/NamedTables/SubwayStations.
6. In theNamed table typefield select Tab.
7. In thePathfield enter the path to the TAB file.
8. ClickOK.
The subway stations table now appears as a named table in the repository.
Step 2: Add the Toronto Named Map to the Repository
The next step is to create a named map for Toronto in the repository by uploading an MWS file. This map will show the user where each subway station is.
1. Find the file system location of the MWS file and the TAB files that the MWS references.
2. Copy the TAB files to a location on the file system that is accessible to the Mapping Service.
3. Open the MWS Uploader Utility.
4. In theRepositoryfield, enter the standard WebDAV URL for the repository into which you want to upload the MWS file, including the final slash. For example, http://localhost:8080/Reposit-oryService/repository/default/.
5. In theNamedMaps Pathfield, enter the path inside the repository where you want the named map to be created.
If this field is left empty, then the named map will be created at the root of the repository.
6. In theNamedTables Pathfield, enter the path inside the repository where you want the named tables that are referenced by the named map to be created.
If this field is left empty, then the named tables will be created at the root of the repository.
7. In theMapNamefield, enter the name you want the new named map in the repository to have. If this field is left empty, then the name will default to the name of the MWS file.
8. In theLocal Data Pathfield, enter the path to any referenced TAB files on the machine where the MWS file was created.
If you do not know where the TAB files are located, then open the MWS file in a text editor and look for the path for any TAB files.
9. In theServer Data Pathfield, enter the path to the same TAB files on your Spectrum™Technology Platform hosting machine.
While uploading, the MWS Uploader Utility will look for any references to the local data path in the MWS and dependent files, and replace them with the server data path.
10.Select theOverwrite Files,Map,Tables, andUse Named Tablesoptions.
11.Click theUpload Workspacebutton. TheOpendialog box opens.
12.In theOpendialog box, select the MWS file you want to upload, then clickOpen.
The selected MWS file, and the TAB files it references, are uploaded to the repository as a named map and named tables.
The named map of Toronto and the required named tables have now been added to the repository and are available to the Mapping Service.
Step 3: Create the Java Client Code
The final step is to write the Java client code. The client code will receive a request to retrieve the five subway stations that are nearest to a given point. The point could be obtained either by geocoding an
41 Getting Started Guide
address or from a mobile device's GPS. Either way, the point will be provided to the client code as WGS 84 (lat/long) coordinates. The client code will call on the Feature Service to get the station locations. The client code will then use the Mapping Service to return a map of Toronto that has the location of the five subway stations as an overlay.
Before you can begin writing the Java client code, you must first generate the stub code based on the WSDL documents for the Feature and Mapping services. For information about how to generate stub code for a Java client, seeGenerating Stub Code for a Java Clienton page 20. For the URLs of the Feature and Mapping Service WSDL documents, seeWSDL URLson page 20.
Step 3a: Create the Client Code for the Feature Service
Creating theSearchNearestRequestis a multi-step process as we need to specify: • the geometry to search from
• the maximum candidates desired
• the name and location of, and distance to, each subway station • the named table to query
The steps are:
1. Create an instance ofSearchNearestRequestand populate it with the desired parameters.
2. Make the call to thesearchNearestmethod and get theSearchNearestResponse.
3. Return theFeatureCollectionfromSearchNearestResponse.
Here is the code:
/**
* Returns a FeatureCollection of the 5 subway stations nearest the specified point.
* The specified point is assumed to be in WGS 84 (i.e. long/lat).
* @param longitude the longitude (i.e. X ordinate) of the point to search from.
* @param latitude the latitude (i.e. Y ordinate) of the point to search from.
* @return a FeatureCollection of the 5 subway stations nearest the specified point.
*/
private FeatureCollection findNearest(double longitude, double latitude) { // create the request and populate it along the way
SearchNearestRequest request = new SearchNearestRequest(); // create the search point
Point searchPoint = new Point(); searchPoint.setSrsName("epsg:4326"); Pos pos = new Pos();
pos.setX(longitude); pos.setY(latitude); searchPoint.setPos(pos);
// set the search geometry which in this case is a point request.setGeometry(searchPoint);
// we want at most 5 candidates request.setMaxNumberOfCandidates(5);
