Spectrum Technology Platform

Transcription

1 Spectrum Technology Platform Version SP2 Getting Started Guide

2 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 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: Fax: Sales: Government Sales: Technical Support: Technical Support Fax: Canada: Phone: Fax: Sales: Technical Support: Technical Support Fax: Europe/United Kingdom: Phone: Fax: Technical Support: Asia Pacific/Australia: Phone: Fax: Technical Support: Contact information for all Pitney Bowes offices is located at: 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

3 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

4 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 Spectrum Technology Platform SP2

5 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? 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 SP2

7 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

8

9 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 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 . You can also download your access keys from 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: For example, if your host server is named "myserver" and it uses the default HTTP port 8080, you would go to: 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 SP2

11 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 How to Change Web Service Configuration Settings...12

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 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 SP2

13 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 Repository Contents Managing the Repository

14 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 SP2

15 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

16 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 SP2

17 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 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 SP2

19 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

20 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: 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 SP2

21 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 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

22 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 SP2

23 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 2. IIS (.NET) Proxy download located at 3. Controls JavaScript hosted at 4. JavaScript API Documentation hosted at or can be accessed at the Spectrum Technology Platform documentation site here: 5. RIA example application hosted at 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: 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

24 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: 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 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: 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 where servername is a placeholder for the hostname RIA is installed on. 3. Restart the proxy application. For example: trusted.base.url= 24 Spectrum Technology Platform SP2

25 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: 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= 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: 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

26 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 URL 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 by calling 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 instead of 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 SP2

27 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=" Layers.js"></script> <script type="text/javascript" src=" 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=" <script src=" </head> <body> <button onclick="search();">search</button> <script> ria.restservice.addproxy("/riaproxy?url="); function search() { var fs = new ria.search.featureservice( " ), var d = fs.searchnearest({ table: "/NamedTables/WorldcapTable", geometry: new OpenLayers.Geometry.Point( , srs: "epsg:4326", attributes: ["Capital"], withindistance: "2000 mi", distanceattributename: "dist", Getting Started Guide 27

28 Using a Browser-based Application maxfeatures: 10 }); d.addcallback(function(result) {alert(result.features.length + " result(s)")}); } </script> </body> </html 28 Spectrum Technology Platform SP2

29 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 Geometry Service Map Tiling Service Mapping Service Named Resource Service User Management Service Catalog Service for the Web Web Feature Service Web Map Service

30 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: The URL endpoint for the SOAP implementation of the Feature Service has the following general form: The URL for the Feature Service WSDL document has the following general form: The URL for the Feature Service demo page has the following general form: 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 SP2

31 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: The URL for the Geometry Service WSDL document has the following general form: The URL for the Geometry Service demo page has the following general form: 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

32 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: 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: 32 Spectrum Technology Platform SP2

33 Chapter 6: Learning More About the Web Services The URL endpoint for the SOAP implementation of the Mapping Service has the following general form: The URL for the Mapping Service WSDL document has the following general form: The URL for the Mapping Service demo page has the following general form: 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: The URL for the Named Resource Service WSDL document has the following general form: The URL for the Named Resource Service demo page has the following general form: Getting Started Guide 33