Spectrum Technology Platform Version 8.0.0 SP2 Getting Started Guide
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. April 02, 2013
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 Via Web Services...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 Find the Nearest Five Subway Stations...40 4 Spectrum Technology Platform 8.0.0 SP2
Introduction 1 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 the Location Intelligence Module?............6
What Is Location Intelligence? 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 operations, 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 certified OGC web 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 certified OGC web 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 6 Spectrum Technology Platform 8.0.0 SP2
Chapter 1: Introduction 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 Getting Started Guide 7
Installing Location Intelligence Module Services 2 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. Note: You must install the Spectrum Technology Platform server before you can install the Spectrum Technology Platform clients. In this section: Installing the Server..............................10 Installing the Clients..............................10
Installing the Server 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 notification email. You can also download your access keys from www.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 select Stop Server. Installing the Clients Note: You must uninstall your current clients before installing the 8.0 clients. 1. On the computer where you installed Spectrum Technology Platform, start the Spectrum Technology 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 the bin directory of where Spectrum Technology Platform is installed and type:../setup followed by./server.start. 2. On the computer where you want to install Management Console, Enterprise Designer, and/or Interactive 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: http://myserver:8080. Note that you can install clients only on Windows computers. 3. If you do not have Microsoft.NET 4.0 installed, click Microsoft.NET Framework and install it. 4. Click Client Installers and follow the prompts to complete installation of Management Console, Enterprise Designer, and/or Interactive Driver. 5. Once installed, you can launch Management Console, Enterprise Designer, or Interactive Driver from the Windows Start menu. Go to Pitney Bowes > Spectrum Technology Platform > Client Tools. 10 Spectrum Technology Platform 8.0.0 SP2
Configuring the Web Services 3 This section provides information about how to configure the Location Intelligence Module web services. In this section: About Web Service Configurations..................12 How to Change Web Service Configuration Settings...12
About Web Service Configurations 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 the Location Intelligence Module repository as a named configuration. 1 Note: 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. 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 the web service documentation. 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. Note: You cannot use the Named Resource Service to extract a named configuration file from the repository. 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. Note: You cannot use the Named Resource Service to add a named configuration file to the repository. 4. Do one of the following to reload the web service configuration: Restart the web service. Use the Spectrum Technology Platform JMX Console (available at http://hostname[:portnumber]/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. 12 Spectrum Technology Platform 8.0.0 SP2
Managing the Location Intelligence Module Repository 4 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 Managing the Repository..........................15
The Purpose of the Repository The Purpose of the Repository Whether you are accessing the Location Intelligence Module services via stages or web 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 administration 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 the Named 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 the Named Resources Guide. 14 Spectrum Technology Platform 8.0.0 SP2
Chapter 4: Managing the Location Intelligence Module Repository 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 the Named 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 the Named 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 the Styles 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 Intelligence Module repository using Management Console, see the section entitled "Named Tables" in the "Location Intelligence Module" chapter of the Spectrum Technology Platform User's Guide. Getting Started Guide 15
Managing Users 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 the MWS Uploader Utility guide. Using the Named Resource Service You can use the Named Resource Service to manage almost any type of named resource in the repository. 2 This 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 the Named 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 repository, 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 the User 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. 16 Spectrum Technology Platform 8.0.0 SP2
Accessing Location Intelligence Module Services 5 There are two distinct ways to access the services provided by the Location Intelligence 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 Web Services................................18
Via Stages 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 socketbased 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 Intelligence 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 an OGC-compliant web service. 18 Spectrum Technology Platform 8.0.0 SP2
Chapter 5: Accessing Location Intelligence Module Services 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, see Learning More About the Web Services on 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. Web Service SOAP REST POST/GET Feature Geometry Map Tiling Mapping Named Resource User Management Catalog Service for the Web * Web Feature * Web Map * * Indicates an OGC-compliant web service. Getting Started Guide 19
Web Service Documentation 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 wsimport tool that is included with the Java Development Kit. 1. Open an xterm or command prompt window and change to the directory that contains the wsimport program, usually JDK_install_dir/bin/. 2. At the command prompt, type wsimport -s source_dir -d classes_dir URL_TO_WSDL and press Enter. 20 Spectrum Technology Platform 8.0.0 SP2
Chapter 5: Accessing Location Intelligence Module Services 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-dpdev.nw.pb.com/namedresourceservice/services/namedresourceservice?wsdl After the command has been executed, the generated source.java files are placed within the directory you specified with the -s option, and the compiled.class files are placed within the directory you specified with the -d option. 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 the File menu, select New > Project. The New Project wizard opens. 3. In the New Project wizard, select Java > Java Project. Click Next. 4. In the Project Name field, enter the name you want to give your project. Click Finish to close the wizard. The new project folder appears in the Package Explorer. 5. In the Package Explorer, right-click on the project folder you created in the previous step. On the pop-up menu, select New > Other. The New wizard opens. 6. In the New wizard, select Web Services > Web Service Client. Click Next. 7. In the Service Definition field, enter the URL to the web service's WSDL document. Select Develop Client on the slider bar. Click Finish to 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 the File menu, select New > Project. The New Project dialog box opens. Getting Started Guide 21
Using a Browser-based Application 3. In the New Project dialog box, enter the desired settings, then click OK. 4. In the Solution Explorer pane, right-click on References. On the pop-up menu, select Add Web Reference. The Add Web Reference dialog box opens. 5. In the Add Web Reference dialog box, enter the URL to the web service's WSDL document. After you have entered the URL, click the Go button. Documentation for the web service then appears under the URL field. 6. In the Add Web Reference dialog box, note the web reference name provided in the Web Reference Name field, then click the Add Reference button. The web reference is added to the project. After you have completed these steps, you can see the new web reference in the Solution 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 browserbased 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: Control LegendControl FeatureService Multi-table FeatureService Description 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. A non-user interface control, that lets developers write Javascript code to call the FeatureService REST API. This control can be used to query tables for features. Search results are returned as GeoJSON FeatureCollections. The search call is performed asynchronously. A non-user interface control, that lets developers make FeatureService REST calls against multiple tables simultaneously. This is a 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 22 Spectrum Technology Platform 8.0.0 SP2
Chapter 5: Accessing Location Intelligence Module Services Control Description stacked on top of each other. For example, a SearchNearest against TABLE1 and TABLE2 at a given point (x,y). OpenLayers layer types Generic data formatting REST Services An easy way to display either a MappingService NamedMap or a TileService map tile on an OpenLayers map. Template formatting controls for developers to display JSON data in an OpenLayers popup (for example) but intelligently styled. For 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 asynchronous XMLHttpRequest calls. 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 at http://localhost:8080/ria-examples/riaproxy/riaproxy.war 2. IIS (.NET) Proxy download located at http://localhost:8080/ria-examples/riaproxy/riaproxy.zip 3. Controls JavaScript hosted at http://localhost:8080/ria/ria.js 4. JavaScript API Documentation hosted at http://localhost:8080/ria/api/, or can be accessed at the Spectrum Technology Platform documentation site here: http://reference.mapinfo.com/software/spectrum/lim/8_0/ria/api/index.html. 5. RIA example application hosted at http://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-controlbased 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 your webapps (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. Getting Started Guide 23
Using a Browser-based Application 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-examples/. 4. Download the riaproxy.war file from Spectrum Technology Platform and copy it to your webapps (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 Proxy on 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 FeatureService 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 arbitrary 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://localhost: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 of riaproxy. Note: 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 Proxy on page 27 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 24 Spectrum Technology Platform 8.0.0 SP2
Chapter 5: Accessing Location Intelligence Module Services 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://localhost: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 \ProxyService\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. Getting Started Guide 25
Using a Browser-based Application 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: URL http://www.example.com/dir/page.html http://www.example.com/dir2/other.html http://www.example.com:81/dir2/other.html https://www.example.com/dir2/other.html http://en.example.com/dir2/other.html http://example.com/dir2/other.html http://v2.www.example.com/dir2/other.html Same-Origin true true false false false false false Note Same protocol and host Same protocol and host Same protocol and host but different port Different protocol Different host Different host (exact match required) Different host (exact match required) 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 page http://myserver:8765/some/path/example.html by calling http://localhost/riaproxy?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. 26 Spectrum Technology Platform 8.0.0 SP2
Chapter 5: Accessing Location Intelligence Module Services 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> Replace localhost:8080 with 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. Note: The path above is the default for the Java Servlet proxy. For the IIS proxy, use the path /riaproxy/proxy.aspx?url=. Final Code Sample A simple page for performing a Feature Search: <!DOCTYPE html> <html> <head> <script src="http://localhost:8080/ria/openlayers/openlayers.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"); 47.813155), var d = fs.searchnearest({ table: "/NamedTables/WorldcapTable", geometry: new OpenLayers.Geometry.Point(12.875977, srs: "epsg:4326", attributes: ["Capital"], withindistance: "2000 mi", distanceattributename: "dist", Getting Started Guide 27
Using a Browser-based Application maxfeatures: 10 }); d.addcallback(function(result) {alert(result.features.length + " result(s)")}); } </script> </body> </html 28 Spectrum Technology Platform 8.0.0 SP2
Learning More About the Web Services 6 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 Web Map Service................................36
Feature Service Feature Service Description The Feature Service provides the ability to search spatial databases. It provides a set of common operations 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 the Feature Service Reference. To see the full documentation for the REST implementation of the Feature Service, refer to the REST Interfaces guide. 30 Spectrum Technology Platform 8.0.0 SP2
Chapter 6: Learning More About the Web Services Geometry Service Description The 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 the Geometry Service Reference. Map Tiling Service Description The 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, lightweight map rendering where more complex map rendering can be performed using the Mapping Service. Getting Started Guide 31
Mapping Service 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 intensive. 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 the Map Tiling Service guide. To walk through the steps for creating and using map tiles, see Map Tiling in the How Do I? section. Mapping Service Description The 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 32 Spectrum Technology Platform 8.0.0 SP2
Chapter 6: Learning More About the Web Services 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 the Mapping Service Reference. To see the full documentation for the REST implementation of the Mapping Service, refer to the REST Interfaces guide. Named Resource Service Description The 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 Getting Started Guide 33
User Management Service Documentation To see the full documentation for the Named Resource Service, refer to the Named Resource Service Reference. User Management Service Description The User Management Service provides a simplified interface to manage security for the repository, 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 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 the User Management Guide. Catalog Service for the Web Description The 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: 34 Spectrum Technology Platform 8.0.0 SP2
Chapter 6: Learning More About the Web Services 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 an OGC-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 the Catalog Service for the Web Reference Guide. Web Feature Service Description The 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 an OGC-compliant web service. Getting Started Guide 35
Web Map Service 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 the Web Feature Service guide. Web Map Service Description The 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 an OGC-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 the Web Map Service guide. 36 Spectrum Technology Platform 8.0.0 SP2
Sample Applications 7 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 SOAP Samples..................................40
REST Samples 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 /> 38 Spectrum Technology Platform 8.0.0 SP2
Chapter 7: Sample Applications 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/mappingservice/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()); Getting Started Guide 39
SOAP Samples } } 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. Expand Modules > Location Intelligence > Tools then click Named Tables. 4. Click Add. The Add Named Table dialog box opens. 5. Enter the repository path and name for the new named table in the Named table name field. 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 the SubwayStations named table and are creating this named table in the NamedTables directory in the repository, the name you would enter in the Named table name field would be /NamedTables/SubwayStations. 6. In the Named table type field select Tab. 7. In the Path field enter the path to the TAB file. 40 Spectrum Technology Platform 8.0.0 SP2
Chapter 7: Sample Applications 8. Click OK. 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 the Repository field, 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/repositoryservice/repository/default/. 5. In the NamedMaps Path field, 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 the NamedTables Path field, 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 the MapName field, 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 the Local Data Path field, 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 the Server Data Path field, 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 the Overwrite Files, Map, Tables, and Use Named Tables options. 11. Click the Upload Workspace button. The Open dialog box opens. 12. In the Open dialog box, select the MWS file you want to upload, then click Open. 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 Getting Started Guide 41
Find the Nearest Five Subway Stations 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, see Generating Stub Code for a Java Client on page 20. For the URLs of the Feature and Mapping Service WSDL documents, see WSDL URLs on page 20. Step 3a: Create the Client Code for the Feature Service Creating the SearchNearestRequest is 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 of SearchNearestRequest and populate it with the desired parameters. 2. Make the call to the searchnearest method and get the SearchNearestResponse. 3. Return the FeatureCollection from SearchNearestResponse. 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); 42 Spectrum Technology Platform 8.0.0 SP2
Chapter 7: Sample Applications // return the distance from the search point to each found point as an attribute called 'distance' request.setreturneddistanceattributename(distance_attribute_name); request.setreturneddistanceunit(distance_units); // specify the attributes to return. in this case we want the name of the subway station and the geometry AttributeList projectionlist = new AttributeList(); projectionlist.getattributename().add("name"); projectionlist.getattributename().add("obj"); request.setattributelist(projectionlist); // specify the Named Table to search against NamedTable table = new NamedTable(); table.setname("/demo/stations"); request.settable(table); // create the client-side instance/interface to the FeatureService and specify the security settings to access the service FeatureService featureservicebootstrap = new FeatureService(); FeatureServiceInterface serviceport = featureservicebootstrap.getport(featureserviceinterface.class); ((BindingProvider)servicePort).getRequestContext().put(BindingProvider.USER- NAME_PROPERTY, ADMIN_USERNAME); ((BindingProvider)servicePort).getRequestContext().put(BindingProvider.PASS- WORD_PROPERTY, ADMIN_PASSWORD); // query the Feature Service and return the resulting FeatureCollection try { SearchNearestResponse response = serviceport.searchnearest(request); } return response.getfeaturecollection(); } catch (ServiceException e) { throw new RuntimeException(e); } Step 3b: Create the Client Code for the Mapping Service The next step is to create a map image with the found subway stations using Toronto as the base map. We need to use the RenderNamedMapWithOverlay method of the Mapping Service. The steps are: 1. Create an instance of RenderNamedMapWithOverlayRequest. 2. Set the desired width and height of the image. 3. Set the view (bounds) of the map. 4. Set the named map to render. 5. Set the MIME type (image format) to generate. 6. Create a FeatureLayer overlay based on the specified FeatureCollection. 7. Set some label properties to label each subway station with its name and distance in meters. 8. Create a theme to give the subway stations a recognizable style. 9. Execute the request and return the image's bytes. Getting Started Guide 43
Find the Nearest Five Subway Stations Here is the code: /** * Returns the image of the map overlayed with Features in the specified FeatureCollection. * @param fc the FeatureCollection to render on top of the map. * @param centerlongitude the longitude of the center of the map * @param centerlatitude the latitude of the center of the map * @param zoom the zoom (distance across the map) assumed to be kilometers. * @return the image of the map overlayed with Features in the specified FeatureCollection. */ private byte[] createmap(featurecollection fc, double centerlongitude, double centerlatitude, double zoom) { RenderNamedMapWithOverlayRequest request = new RenderNamedMapWithOverlayRequest(); ZoomAndCenterMapView mapview = new ZoomAndCenterMapView(); // set the dimensions of the returned image to be 640 x 480 mapview.setwidth(640); mapview.setheight(480); // set the view. in this case we are using the zoom/center view Point center = new Point(); center.setsrsname("epsg:4326"); center.setpos(new Pos()); center.getpos().setx(centerlatitude); center.getpos().sety(centerlongitude); mapview.setmapcenter(center); Distance zoomlevel = new Distance(); zoomlevel.setvalue(zoom); zoomlevel.setuom(distanceunit.kilometer); mapview.setzoomlevel(zoomlevel); request.setmapview(mapview); // use the /demo/namedmaps/ontario Named Map for the background String namedmap = "/demo/namedmaps/ontario"; request.setnamedmap(namedmap); // we want a GIF String mimetype = "image/gif"; request.setimagemimetype(mimetype); // return the image NOT an URL to the image request.setreturnimage(true); // now create the FeatureCollection overlay using a MemoryTable and a FeatureLayer OverlayList overlaylist = new OverlayList(); List<Layer> overlays = overlaylist.getoverlay(); MemoryTable table = new MemoryTable(); table.setfeaturecollection(fc); FeatureLayer layer = new FeatureLayer(); layer.settable(table); { 44 Spectrum Technology Platform 8.0.0 SP2
// create the label properties MapBasicPointStyle style = new MapBasicPointStyle(); MapBasicFontSymbol mapbasicsymbol; mapbasicsymbol = new MapBasicFontSymbol(); mapbasicsymbol.setbold(true); mapbasicsymbol.setcolor("black"); mapbasicsymbol.setfontname("arial"); mapbasicsymbol.setsize((short) 14); mapbasicsymbol.setshape(33); style.setmapbasicsymbol(mapbasicsymbol); LabelProperties labelproperties = new LabelProperties(); // the label expression is an MI SQL fragment labelproperties.setexpression("name + '(' + round(distance) + ' m)'"); labelproperties.setallowduplicate(allowduplicatetype.all); labelproperties.setallowoverlap(true); labelproperties.setxoffset(10.0); // a small offset in the X direction so the label does not overwrite the symbol layer.setlabelproperties(labelproperties); } overlays.add(layer); request.setoverlaylist(overlaylist); // add theme to set the style of the overlay OverrideTheme theme = new OverrideTheme(); MapBasicPointStyle featurestyle = new MapBasicPointStyle(); MapBasicFontSymbol mapbasicfontsymbol = new MapBasicFontSymbol(); mapbasicfontsymbol.setshape(64); mapbasicfontsymbol.setcolor("red"); mapbasicfontsymbol.setfontname("mapinfo Transportation"); mapbasicfontsymbol.setsize((short) 14); featurestyle.setmapbasicsymbol(mapbasicfontsymbol); theme.setstyle(featurestyle); ThemeList themelist = new ThemeList(); themelist.gettheme().add(theme); layer.setthemelist(themelist); Chapter 7: Sample Applications // create the client-side instance/interface to the FeatureService and specify the security settings to access the service MappingService mappingservicebootstrap = new MappingService(); MappingServiceInterface serviceport = mappingservicebootstrap.getport(mappingserviceinterface.class); ((BindingProvider)servicePort).getRequestContext().put(BindingProvider.USER- NAME_PROPERTY, ADMIN_USERNAME); ((BindingProvider)servicePort).getRequestContext().put(BindingProvider.PASS- WORD_PROPERTY, ADMIN_PASSWORD); } RenderNamedMapWithOverlayResponse response; try { response = serviceport.rendernamedmapwithoverlay(request); } catch (com.mapinfo.midev.service.mapping.ws.v1.serviceexception e) { throw new RuntimeException(e); } MapImage mapimage = response.getmapimage(); return mapimage.getimage(); Getting Started Guide 45
Find the Nearest Five Subway Stations Final Result And finally, here is the resulting map showing the five nearest subway stations: 46 Spectrum Technology Platform 8.0.0 SP2