Technology Platform. Spectrum. Version Spectrum Spatial Developer Guide

Transcription

1 Spectrum Version 10.0 Technology Platform

2 Table of Contents 1 - Working With Spatial Services Learning More About the Web Services 5 Accessing Location Intelligence Module Services Working with RIA Controls What Are the RIA Controls? 17 Getting Started with the RIA Controls 18 Developing with the RIA Controls 18 Using the RIA Proxy Working With REST Services What Are the REST Services? Understanding Tables Supported Data Sources 30 Uses for Tables Understanding Layers Line Chart Layer 55 Grid Layer 59 Modifying the Style with a FeatureStyleModifier Using Styles Types of Styles 79 Pattern Codes 131 Symbol Codes Rasters and Grids Supported Capabilities for Rasters and Grids 138 Using Rasters and Grids How To's Mapping 144 Accessing Data from a Database 158 Map Tiling 160 Web Service Authentication 179 WMS Configuration 184 Custom Symbols Migrating from Envinsa or MapXtreme Java Feature Layer 33 Group Layer 36 Line Linkage Layer 38 Label Layer 42 Graduated Symbol Layer 45 Bar Chart Layer 48 Pie Chart Layer 51 Architecture Considerations 198 Migration Tasks Sample Applications When to Use REST and SOAP 211

3 REST Samples 211 SOAP Samples Common Object Types Geometry Types 223 MapView Types MapInfo Workspace (MWS) Description What Is the MapInfo Workspace? 243 Structure of a Workspace 243 Header Section 244 Connection Section 244 DataSource Definition Section 246 Map Definition Section 248 3

4 1 - Working With Spatial Services This chapter describes the spatial services, and how you can access the various spatial services. This section also shows you how to start using the spatial services in your applications. In this section Learning More About the Web Services 5 Accessing Location Intelligence Module Services 10

5 Working With Spatial Services Learning More About the Web Services This section provides a brief overview of each of the Location Intelligence Module web services. 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: 5

6 Working With Spatial Services Documentation 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: 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, light-weight map rendering where more complex map rendering can be performed using the Mapping Service. 6

7 Working With Spatial Services 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: 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: 7

8 Working With Spatial 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 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: 8

9 Working With Spatial Services 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: 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: The URL endpoint for the SOAP implementation of the Catalog Service for the Web has the following general form: The URL for the Catalog Service for the Web WSDL document has the following general form: The URL for the Catalog Service for the Web demo page has the following general form: 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 OGC specification. Both SOAP and HTTP POST/GET requests are supported. As a 9

10 Working With Spatial Services 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. Service URLs The URL endpoint for the Web Feature Service has the following general form: 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 and 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: Accessing Location Intelligence Module Services 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. 10

11 Working With Spatial Services 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. Via Stages To access Location Intelligence Module services via stages, you build and run a dataflow in Enterprise Designer that includes one of more Location Intelligence Module stages. The stages use a direct socket-based method to communicate with the corresponding Location Intelligence Module services. The following Location Intelligence Module stages are available in the Enterprise Designer: Find Nearest Locates the points of interest (POI) that are nearest to a given location. Query Spatial Data Allows you to query a spatial database using MI SQL functions that can, for example, search for a point within a given polygon. Read Spatial Data Allows you to access spatial data in a variety of commonly-used spatial data formats using MI SQL functions. Spatial Calculator Performs string and geometry conversions as well a variety of calculations on spatial data, such as determining the area of a polygon or distance between two points. Spatial Union Returns a geometry object which represents the union of two input geometry objects. Write Spatial Data Allows you to insert data into a named table or update data in a named table as output of a job. Closest Site Determines which sites are closest to a given location. Point In Polygon Determines whether or not a location resides in a given area. For more information about these stages, see the the Stages section in the Spectrum Technology Platform Spectrum Spatial Guide on support.pb.com. 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. 11

12 Working With Spatial Services Named Resource Service Provides the ability to work with resources in the Location Intelligence Module repository. Catalog Service for the Web * Enables an application to publish and search collections of descriptive information (metadata) for data, services, and related information. 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 5. 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 * Indicates an OGC-compliant web service. 12

13 Working With Spatial Services Web Service SOAP REST POST/GET Mapping Named Resource Catalog Service for the Web * Web Feature * Web Map * Web Service Documentation To see the documentation for each Location Intelligence Module web service, refer to the the Services section in the Spectrum Technology Platform Spectrum Spatial Guide on support.pb.com. 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: * Indicates an OGC-compliant web service. 13

14 Working With Spatial Services 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. For example, to generate stub classes for the Geometry Service, 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. 14

15 Working With Spatial Services 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. 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. See Working with RIA Controls on page 16 for a description of the RIA controls and how to get started using them in your web applications. 15

16 2 - Working with RIA Controls 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. In this section What Are the RIA Controls? 17 Getting Started with the RIA Controls 18 Developing with the RIA Controls 18 Using the RIA Proxy 19

17 Working with RIA Controls What Are the RIA Controls? The RIA (Rich Internet Application) controls provide a set of browser-based user interface components for easily embedding maps and other location-based capabilities in web pages. A JavaScript API is also provided which, together with the user interface components, enable you to create custom browser-based mapping applications. The RIA controls can be used in a wide range of scenarios, from simply embedding maps in your web site to show locations, to creating rich web applications. Built entirely in JavaScript, the controls work without the need for any browser plug-ins and without having to write any server-side code. The RIA controls use Web 2.0 techniques to provide functionality such as seamless map panning and the ability to search and display information without requiring a web page refresh. The following controls are available: Control Description LegendControl 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. FeatureService 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. MultiTableFeatureService 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 stacked on top of each other. For example, a SearchNearest against TABLE1 and TABLE2 at a given point (x,y). OpenLayers layer types An easy way to display either a MappingService NamedMap or a TileService map tile on an OpenLayers map. Generic data formatting 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 Services REST-ful service control for developers to send cross-domain calls to the REST services. These calls will be performed as asynchronous XMLHttpRequest calls. 17

18 Working with RIA Controls 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: Java Servlet Proxy download from IIS (.NET) Proxy download from Controls JavaScript hosted at JavaScript API Documentation hosted at 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-control-based application. Note: To use the RIA controls with Bing Maps, including using the examples, you will need a Bing Maps key. To register, go to the Bing Maps Account Center. 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. Install a web application server (for example, Tomcat) on your machine. 2. Create a new service folder in your webapps (or equivalent) directory of your newly installed application server for your application (for example, a folder called "myapp" located in C:\apache-tomcat \webapps). 3. Download the riaproxy.war file from Spectrum Technology Platform and copy it to your webapps (or equivalent) directory to install it. 18

19 Working with RIA Controls For information on how to download and install the RIA proxy, and on why you must use the proxy, see Using the RIA Proxy on page 19. For information on how to use the RIA proxy with your web application, see Using the RIA Proxy in your Web Application on page Restart your application server. 5. Create your application pages in the service folder that you created in the webapps (or equivalent) directory, using the functionality of the Spectrum Technology Platform JavaScript API. You can use the RIA examples that ship with Spectrum Technology Platform as a starting point for your application. View the page source of the examples on your local installation at a) Save the source to the myapp folder you created above. For example, to include searchnearest in your application, right-click in the Search Nearest content frame to display the source. b) Rename the.jsp file to index.htm. c) Edit proxy.properties to contain the following: trusted.base.url= auth.type=basic anonymous_username=guest d) Restart Tomcat and browse to your application at 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. Decide which proxy to install, then verify the installation was successful. Java Servlet Proxy To install the Java Servlet proxy: 19

20 Working with RIA Controls 1. Download the proxy binary from your Spectrum Technology Platform installation at: 2. Deploy the WAR file to a web application server of your choice. Refer to the documentation of the application server for details on deploying WAR files. If you are using Apache Tomcat, this involves copying the WAR file into the %CATALINA_HOME%\webapps directory. As long as 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, be 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 Once the proxy has been installed, set a trusted base URL. 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: a. Open the proxy.properties file located within the..\riaproxy\web-inf folder (for example, C:\apache-tomcat \webapps\riaproxy\WEB-INF). b. Set the value of the trusted.base.url property to where servername is a placeholder for the hostname RIA is installed on; for example, trusted.base.url= c. Restart the proxy application. 4. To enable HTTP Basic Authentication, set the following properties in the proxy.properties file, replacing username and password with the actual login credentials to be used by the proxy: a. auth.type=basic b. anonymous_username=username c. anonymous_password=password Note: This performs HTTP basic authentication against the RIA server-side component on behalf of 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. Refer to the documentation of your application server for further details. IIS Proxy The IIS proxy requires IIS6 or IIS7. If IIS7 is installed, it is also necessary to install the IIS6 Compatibility Components. A description of how to install these components can be found here: To install the IIS proxy: 1. Download the proxy binary from your Spectrum Technology Platform installation at: 20

21 Working with RIA Controls 2. 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. Refer to the documentation of the application server for details on deploying WAR files. Note: 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. 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 Note true Same protocol and host true Same protocol and host 21

22 Working with RIA Controls URL Same-Origin Note false Same protocol and host but different port false Different protocol false Different host false Different host (exact match required) false 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. 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" 22

23 Working with RIA Controls src=" <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=. 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: "/Samples/NamedTables/WorldcapTable", geometry: new OpenLayers.Geometry.Point( , ), srs: "epsg:4326", 23

24 Working with RIA Controls attributes: ["Capital"], withindistance: "2000 mi", distanceattributename: "dist", maxfeatures: 10 }); d.addcallback(function(result) {alert(result.features.length + " result(s)")}); } </script> </body> </html Test this sample web application by viewing it in your browser and clicking Search. A dialog appears that displays the results of the Feature Search: In a web debugger such as Fiddler, you can see a listing of the 10 results: {"type":"featurecollection","metadata":[{"type":"string","name":"capital"}, {"type":"double","name":"dist"}],"features":[{"type":"feature","properties" :{"Capital":"Ljubljana","dist": }},{"type":"Feature","properties" :{"Capital":"Vienna","dist": }},{"type":"Feature","properties" :{"Capital":"Vaduz","dist": }},{"type":"Feature","properties" :{"Capital":"Prague","dist": }},{"type":"Feature","properties" :{"Capital":"Bratislava","dist": }},{"type":"Feature","properties" :{"Capital":"Zagreb","dist": }},{"type":"Feature","properties" :{"Capital":"Bern","dist": }},{"type":"Feature","properties" :{"Capital":"San Marino","dist": }},{"type":"Feature","properties" 24

25 Working with RIA Controls :{"Capital":"Budapest","dist": }},{"type":"Feature","properties" :{"Capital":"Berlin","dist": }}]} Troubleshooting a.net RIA Proxy If an exception is encountered from the remote service request or there is a problem with the authentication, the HTTP status code, description, headers, URL, and the html body (if available) are inserted into an event log. This log appears in the Microsoft Event Viewer as the "Pitney Bowes RIA Proxy Service." 25

26 3 - Working With REST Services This chapter describes the REST services and how you can access them. In this section What Are the REST Services? 27

27 Working With REST Services What Are the REST Services? The REST services are a set of services you can call in your web application to access the functionality of Spectrum Technology Platform. There are three services that can be accessed using a REST API: The Mapping Service provides a simplified interface to perform Mapping Service rendering, legends, and resource queries. The Mapping Service provides both simple operations that are more frequently used, or more complex operations that require higher levels of customization. The Feature Service provides the ability to search spatial databases, and named resources within the repository. It provides a set of common operations that you can use to query content, regardless of the underlying data provider. 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 MapTiling Service can be used individually, or combined to form larger maps, in applications for seamless map interaction. This service provides fast, simple, light-weight map rendering. REST Interfaces The REST interfaces are what you use to access the Spectrum Technology Platform functionality from within your web application. The following table describes which REST Interface you use to access a particular service. To access this service... Mapping Service Feature Service Map Tiling Service Use this REST Interface To get more detailed descriptions of the REST services, see the spatial REST interface WADL on your system: The REST API is essentially just a set of URLs your web application can send as HTTP GET requests. Each URL defines a request to a particular method of a particular interface. Your application then gets back a response, usually in the form of a JSON object or map image, from the corresponding REST Interface. The returned JSON object can be parsed by your web application to extract and process the requested information. 27

28 Working With REST Services Using the Spectrum Technology Platform REST API Using the REST API in your web application is a two-step process: 1. Build the URL you need to make an interface request (and send it via HTTP GET). 2. Process the contents of the JSON object or image returned in the interface response. The REST API defines the format of the URLs needed to make interface requests, and the format of the JSON objects returned in the response. Request URL Format The URL of a REST API request has the following general form: Where: host is the hostname of the server hosting the services. port is the optional TCP port number (if the services do not receive requests via the default HTTP port). ServiceName is the name of the service you are requesting. For example MappingService, FeatureService, or MapTilingService. pathparams is the name of a resource or method or inline parameter you are requesting. matrixparam is a parameter being passed to the interface method to set an attribute. queryparam is a parameter used to modify the structure or information displayed in the output. Note: The example request URLs in this guide have been encoded with spaces (%20) and colons (%3A) for direct use. 28

29 4 - Understanding Tables Tables are collections of features from a data source. Tables hold rows and columns of information that describe the features, including their geometry, style, and attributes. In this section Supported Data Sources 30 Uses for Tables 31

30 Understanding Tables Supported Data Sources The Location Intelligence Module supports spatial and non-spatial tables from a variety of data sources: Table 1: Supported Data Sources Data Source Spatial Table Non-Spatial Table XY Table Generic JDBC n/a Read/Insert/Update Read/Insert/Update SAP HANA 7.4 Read Read Read Oracle 11gR2 / Oracle Linux Read/Insert/Update Read/Insert/Update Read/Insert/Update SQLServer 2008/2012 R2 Read/Insert/Update Read/Insert/Update Read/Insert/Update Postgres 8+ / PostGIS 1.5 and 2.x Read/Insert/Update Read/Insert/Update Read/Insert/Update GeoPackage / Windows Read Read n/a Table Formats (file-based data sources) Shape Read n/a n/a MapInfo TAB Read n/a n/a Specialty tables include raster, grid, and seamless versions of.tab. View tables are also supported. A view table is a subset of information from one or more data sources, including other view tables. Views are created with an MI SQL Select statement. Spatial tables contain a geometry column that allows the table to be rendered on a map or used in spatial queries. The spatial information can be stored in a MapCatalog that Location Intelligence Module reads to understand the data types. If a MapCatalog does not exist for the database, the Location Intelligence Module will derive the data types directly from the data source. Non-spatial tables containing columns for X and Y coordinates that represent a location (that is, a point) can be expressed as a spatial table composed entirely of point geometries. The metadata to represent the non-spatial table can either come from the MapCatalog or be part of the named table definition. Named tables are explained in the Resources and Data section in the Spectrum Technology Platform Spectrum Spatial Guide on support.pb.com. 30

31 Understanding Tables The Location Intelligence Module also supports an extensible data provider API for accessing custom data sources. Refer to the Download section on support.pb.com. Uses for Tables In order for to Spectrum Technology Platform to access data sources, the associated table must first be included in the repository as a named table. Named tables should also have a named connection defined. For instructions, see Creating a Connection on page 158. Named tables can be used in Spectrum Technology Platform in the following ways: In the Feature Service or WFS to search for features that meet some criteria In a named map, indirectly through layers In a RenderMap request on the Mapping Service In a RenderNamedMapWithOverlay that includes layers In Dataflows and Stages, such as Read Spatial Data 31

32 5 - Understanding Layers A layer is a map component that hold features, themes, and labels. This section describes the supported layer types and provides examples of layer definitions. In this section Feature Layer 33 Group Layer 36 Line Linkage Layer 38 Label Layer 42 Graduated Symbol Layer 45 Bar Chart Layer 48 Pie Chart Layer 51 Line Chart Layer 55 Grid Layer 59 Modifying the Style with a FeatureStyleModifier 63

33 Understanding Layers Feature Layer A feature layer is layer that displays features contained in a table. FeatureLayers can come from native.tab data, remote RDB (Oracle, PostGIS, MS SQL Server, SAP HANA), seamless, raster and grid data and in-memory tables. To modify the style of a FeatureLayer, add a FeatureStyleModifier. A FeatureStyleModifier is a construct that modifies the appearance of a feature in a table using specified criteria or algorithms. FeatureStyleModifiers are discussed later in this chapter. Styles are discussed in Using Styles on page 78. A FeatureLayer is represented in Spectrum Technology Platform in four ways: Embedded inline in a named map As a named layer In a SOAP request as an overlay In a REST request as an overlay with an in-memory table. FeatureLayer in Named Map Example This is an example of a named map with three FeatureLayers (World Capitals, Grid and Ocean). The FeatureLayers are defined by their visibility and a reference to the data source. The World layer is a named layer that references a named table. <?xml version="1.0" encoding="utf-8"?> <NamedMapDefinition version="mxp_namedresource_1_5" xmlns=" xmlns:gml=" <ConnectionSet /> <DataSourceDefinitionSet> <TABFileDataSourceDefinition id="id1" readonly="false"> <DataSourceName>grid15</DataSourceName> <FileName>E:\Spectrum/server/modules/spatial/samples/data/world/grid15.tab</FileName> </TABFileDataSourceDefinition> <TABFileDataSourceDefinition id="id4" readonly="false"> <DataSourceName>worldcap</DataSourceName> <FileName>E:\Spectrum/server/modules/spatial/samples/data/world/worldcap.tab</FileName> 33

34 Understanding Layers </TABFileDataSourceDefinition> <TABFileDataSourceDefinition id="id2" readonly="false"> <DataSourceName>ocean</DataSourceName> <FileName>E:\Spectrum/server/modules/spatial/samples/data/world/ocean.tab</FileName> </TABFileDataSourceDefinition> </DataSourceDefinitionSet> <MapDefinition id="id5" name="mymap" alias=""> <DisplayConditions> <MapSize uom="mapinfo:imagesize pixel"> <ImageWidth>960</ImageWidth> <ImageHeight>800</ImageHeight> </MapSize> <ZoomAndCenter> <MapZoom uom="mapinfo:length mi"> </mapzoom> <gml:point srsname="mapinfo:coordsys 12,62,7,0"> <gml:coordinates> ,0</gml:coordinates> </gml:point> </ZoomAndCenter> <DisplayCoordSys> <SRSName>mapinfo:coordsys 12,62,7,0</SRSName> </DisplayCoordSys> <ResizeMethod>preserveZoom</ResizeMethod> <RasterConditions dither="halftone" rasterreprojectionresampling="cubicconvolution" rasterreprojection="none" truecolor="true" optimizerasterlayers="screen" optimizevectorlayers="screen"/> <RenderingOptions enableopacity="true" enableantialias="true"/> </DisplayConditions> <LayerList> <FeatureLayer id="id7" name="world Capitals" alias="worldcap" volatile="unknown"> <Visibility visible="true"> <VisibleRange enabled="false"> <ZoomRange uom="mapinfo:length mi">0 0</ZoomRange> </VisibleRange> </Visibility> <DataSourceRef ref="id4" /> </FeatureLayer> <FeatureLayer id="id8" name="grid" alias="grid15" volatile="unknown"> <Visibility visible="true"> <VisibleRange enabled="false"> <ZoomRange uom="mapinfo:length mi">0 0</ZoomRange> </VisibleRange> </Visibility> <DataSourceRef ref="id1" /> </FeatureLayer> <NamedLayerRef name="world" resourceid="/samples/namedlayers/worldfeaturelayer"/> <FeatureLayer id="id10" name="ocean (Robinson)" alias="ocean" volatile="unknown"> 34

35 Understanding Layers <Visibility visible="true"> <VisibleRange enabled="false"> <ZoomRange uom="mapinfo:length mi">0 0</ZoomRange> </VisibleRange> </Visibility> <DataSourceRef ref="id2" /> </FeatureLayer> </LayerList> </MapDefinition> </NamedMapDefinition> Named Layer Example This is an example of a named layer definition for a FeatureLayer. In this example, the definition defines the attributes of a feature layer named World Countries. The data for this feature layer is contained in a file named worldcap.tab on the local file system. <?xml version="1.0" encoding="utf-8"?> <NamedLayer version="mxp_namedresource_1_5" xmlns=" <ConnectionSet/> <DataSourceDefinitionSet> <TABFileDataSourceDefinition id="id4" readonly="false"> <DataSourceName>worldcap</DataSourceName> <FileName>@INSTALLDIR@/Mapping/world/worldcap.tab</FileName> </TABFileDataSourceDefinition> </DataSourceDefinitionSet> <FeatureLayer id="id9" name="world Countries" alias="world" volatile="unknown"> <Visibility visible="true"> <VisibleRange enabled="false"> <ZoomRange uom="mapinfo:length mi">0 0</ZoomRange> </VisibleRange> </Visibility> <DataSourceRef ref="id4"/> </FeatureLayer> </NamedLayer> 35

36 Understanding Layers FeatureLayer as an Overlay FeatureLayer can also be used as an overlay in a SOAP or REST request. For a demo of the SOAP request, go to the Spectrum Spatial SOAP Mapping Service Demo Page at Choose Render Named Map with Overlay and Render Named Map with FeatureLayer Overlay. Group Layer A group layer combines a set of layers as one layer. You can combine a set of layers that are related to each other based on certain properties under one group. For example, individual layers that represent Primary Schools, Secondary Schools, and Colleges can be grouped as one group layer called Educational Institute. A group layer is represented in Spectrum Technology Platform in four ways: Embedded inline in a named map As a named layer In a SOAP request as an overlay In a REST request as an overlay with an in-memory table. Group Layer in Named Map Example This is an example of a named map with a named group layer, WorldGroupLayer. <?xml version="1.0" encoding="utf-8"?> <NamedMapDefinition version="mxp_namedresource_1_5" xmlns=" xmlns:gml=" <ConnectionSet /> <DataSourceDefinitionSet/> <MapDefinition id="id5" name="mymap" alias=""> <DisplayConditions> <MapSize uom="mapinfo:imagesize pixel"> <ImageWidth>960</ImageWidth> <ImageHeight>800</ImageHeight> </MapSize> <ZoomAndCenter> <MapZoom uom="mapinfo:length mi"> </mapzoom> <gml:point srsname="mapinfo:coordsys 12,62,7,0"> 36

37 Understanding Layers <gml:coordinates> ,0</gml:coordinates> </gml:point> </ZoomAndCenter> <DisplayCoordSys> <SRSName>mapinfo:coordsys 12,62,7,0</SRSName> </DisplayCoordSys> <ResizeMethod>preserveZoom</ResizeMethod> <RasterConditions dither="halftone" rasterreprojectionresampling="cubicconvolution" rasterreprojection="none" truecolor="true" optimizerasterlayers="screen" optimizevectorlayers="screen"/> <RenderingOptions enableopacity="true" enableantialias="true"/> </DisplayConditions> <LayerList> <NamedLayerRef name="worldcap" resourceid="/samples/namedlayers/worldcapfeaturelayer"/> <NamedLayerRef name="worldgrouplayer" resourceid="/samples/namedlayers/grouplayer"/> </LayerList> </MapDefinition> </NamedMapDefinition> Group Layer Definition Example This is an example of a named layer definition that contains a named group layer. In this example, the definition defines the attributes of a LayerGroup named WorldGroupLayer. <?xml version="1.0" encoding="utf-8"?> <?xml version="1.0" encoding="utf-8"?> <NamedLayer version="mxp_namedresource_1_5" xmlns=" > <ConnectionSet /> <DataSourceDefinitionSet /> <LayerGroup id="id3" name="worldgrouplayer" alias="grouplayerwithnamedlayers"> <LayerList> <NamedLayerRef name="grid" resourceid="/samples/namedlayers/grid15featurelayer"/> <NamedLayerRef name="world" resourceid="/samples/namedlayers/worldfeaturelayer"/> <NamedLayerRef name="ocean" resourceid="/samples/namedlayers/oceanfeaturelayer"/> </LayerList> </LayerGroup> 37

38 Understanding Layers </NamedLayer> Line Linkage Layer Maps using line linkages enable you to examine the relationship between points by connecting them with a line based on a common variable between them. A good example of a line linkage map is to display the flights in and out of airports and show the connections between each airport. These linkage maps represent the lines drawn on the map from a source geometry (centroid) to a destination geometry (centroid) based on a relationship expression/column. Figure 1: Line Linkage Map Example You can customize the color of each point as well as the lines connecting each point. To style the point, a simple style can be applied. To style the line, a metric theme can be applied to group values. The layer allows for one style for start points, one style for end points, and zero or more modifiers for the line styles. There are various ways to create line linkage maps; using a named layer, using a named map with an overlay using named tables, using an inline defined line linkage in a map. However, they all have the same basic structure. All linkage maps require two tables, a geometry and a linkage table. And all linkage maps need to define the relationship, metric, source, and destination expressions. The geometry table contains two important columns; a relationship and a geometry column. The relationship column is the column that contains the records that will be linked to the records in the source and destination columns in the linkage table. The values in the columns need to be the same. The geometry column is the column that contains the geometries to render the points for both the source and destination columns. The linkage table contains three important columns: a source, a 38

39 Understanding Layers destination, and a metric column. The source column is the starting location for a linkage, while the destination column is the end location for a linkage. These two columns must contain the same type of information as the relationship column in the geometry table. The metric column defines the actual linkage between the two points, and contains values that represent the line. This column is used to add themes or stylize the line. For example, the metric column might contain values of the number of flights between two cities. In this case you may want to make the connecting line thicker/thinner or styled differently depending on the number of flights. A LineLinkageLayer is represented in Spectrum Technology Platform in four ways: Embedded inline in a named map As a named layer In a SOAP request as an overlay In a REST request as an overlay with an in-memory table. LineLinkageLayer in Named Map Example This is an example of a named map with a LinkLinkageLayer named World Countries. <NamedMapDefinition version="mxp_namedresource_1_5" xmlns:gml=" xmlns=" > <ConnectionSet/> <DataSourceDefinitionSet> <NamedDataSourceDefinitionRef id="id1" resourceid="/samples/namedtables/worldtable"/> <NamedDataSourceDefinitionRef id="id2" resourceid="/samples/namedtables/flightstable"/> </DataSourceDefinitionSet> <MapDefinition id="id3" name="mymap" alias=""> <DisplayConditions> <MapSize uom="mapinfo:imagesize pixel"> <ImageWidth>960</ImageWidth> <ImageHeight>800</ImageHeight> </MapSize> <ZoomAndCenter> <MapZoom uom="mapinfo:length mi"> </mapzoom> <gml:point srsname="mapinfo:coordsys 12,62,7,0"> <gml:coordinates> ,0</gml:coordinates> </gml:point> </ZoomAndCenter> <DisplayCoordSys> <SRSName>mapinfo:coordsys 12,62,7,0</SRSName> </DisplayCoordSys> <ResizeMethod>preserveZoom</ResizeMethod> <RasterConditions dither="halftone" 39

40 Understanding Layers rasterreprojectionresampling="cubicconvolution" rasterreprojection="none" truecolor="true" optimizerasterlayers="screen" optimizevectorlayers="screen"/> <RenderingOptions enableopacity="true" enableantialias="true"/> </DisplayConditions> <LayerList> <LineLinkageLayer id="id5" name="world Countries" alias="world_linelinkage" volatile="unknown"> <Visibility visible="true"> <VisibleRange enabled="false"> <ZoomRange uom="mapinfo:length mi">0 0</ZoomRange> </VisibleRange> </Visibility> <GeometryTable> <DataSourceRef ref="id1" /> </GeometryTable> <LinkageTable> <DataSourceRef ref="id2" /> </LinkageTable> <SourcePointStyle> <NamedStyleRef resourceid="/samples/namedstyles/pointstylepin"/> </SourcePointStyle> <DestinationPointStyle> <NamedStyleRef resourceid="/samples/namedstyles/pointstylestar"/> </DestinationPointStyle> <RelationshipExpression>Country</RelationshipExpression> <MetricExpression>Metric</MetricExpression> <SourceExpression>Source_Airport</SourceExpression> <DestinationExpression>Destination_Airport</DestinationExpression> </LineLinkageLayer> <FeatureLayer id="id4" name="world" alias="world_feature" volatile="unknown"> <DataSourceRef ref="id1"/> </FeatureLayer> </LayerList> </MapDefinition> </NamedMapDefinition> Layer With Line Linkage Example This is an example of a named layer definition that contains a line linkage layer connecting the centroids of two points. <?xml version="1.0" encoding="utf-8"?> 40

41 Understanding Layers <NamedLayer version ="MXP_WorkSpace_1_5" xmlns=" <ConnectionSet /> <DataSourceDefinitionSet> <NamedDataSourceDefinitionRef id="id4" resourceid="/samples/namedtables/worldtable"/> <NamedDataSourceDefinitionRef id="id5" resourceid="/samples/namedtables/flightstable"/> </DataSourceDefinitionSet> <LineLinkageLayer id="id9" name="world Countries" alias="world" volatile="unknown"> <Visibility visible="true"> <VisibleRange enabled="false"> <ZoomRange uom="mapinfo:length mi">0 0</ZoomRange> </VisibleRange> </Visibility> <GeometryTable> <DataSourceRef ref="id4" /> </GeometryTable> <LinkageTable> <DataSourceRef ref="id5" /> </LinkageTable> <SourcePointStyle> <PointStyle> <FontSymbol text="#" size="12" size-unit="mapinfo:length pt" stroke="rgb(0,0,0)" stroke-opacity="1" family="mapinfo 3.0 Compatible"/> </PointStyle> </SourcePointStyle> <DestinationPointStyle> <PointStyle> <FontSymbol text="#" size="12" size-unit="mapinfo:length pt" stroke="rgb(0,0,0)" stroke-opacity="1" family="mapinfo 3.0 Compatible"/> </PointStyle> </DestinationPointStyle> <RelationshipExpression>Country</RelationshipExpression> <MetricExpression>Metric</MetricExpression> <SourceExpression>Source_Airport</SourceExpression> <DestinationExpression>Destination_Airport</DestinationExpression> </LineLinkageLayer> </NamedLayer> 41

42 Understanding Layers Label Layer A label layer contains the definition of labels based on the features in one or more data sources. Labels typically contain the name of feature, but can also contain derived information as the result of an expression. Each label source controls the visibility, base label properties and themes applied to a label layer. An optional attribute "maxlabels" limits the total number of labels that actually display. If more than one data source exists, a LabelSourceList determines the default priority of label layers: the bottommost label source on the list has the lowest priority. Label properties determine the visibility, style, placement, and priority of the labels. Themes control how the label properties are applied: LabelOverrideTheme - applies a single LabelProperties to every feature label in the label source. LabelRangeTheme - applies LabelProperties to each feature label in the data source based on the mapping of the feature to a range bin. LabelIndividualValueTheme - applies a LabelProperties to every feature label in the data source that matches a specific scalar value. LabelSelectionTheme - applies LabelProperties to the label of every feature that satisfies one or more selection conditions. The display size of the labels in a label theme can be scaled to a specific view based on a reference scale. For example, 16 pt labels at 1:50:000 would display as 32 pt labels when scaled at 1:25:000. Object themes, such as graduated symbols, can be applied to labels to show relative size based on a feature attribute. A Label Layer is represented in Spectrum Technology Platform in four ways: Embedded inline in a named map (table and styles can be modified) As a named layer (table and styles can be modified) In a SOAP request as an overlay (label properties cannot be modified) In a REST request as an overlay with an in-memory table (label properties cannot be modified). Layer With Labels Example This is an example of a named layer definition that contains labels. <?xml version="1.0" encoding="utf-8"?> <NamedLayer version="mxp_namedresource_1_5" 42

43 Understanding Layers xmlns=" <ConnectionSet /> <DataSourceDefinitionSet> <TABFileDataSourceDefinition id="id4" readonly="false"> <DataSourceName>worldcap</DataSourceName> <FileName>E:\Spectrum/server/modules/spatial/samples/data/world/worldcap.tab</FileName> </TABFileDataSourceDefinition> </DataSourceDefinitionSet> <LabelLayer id="id6" name="labels" alias="layer2" volatile="unknown"> <Visibility visible="true"> <VisibleRange enabled="false"> <ZoomRange uom="mapinfo:length mi">0 0</ZoomRange> </VisibleRange> </Visibility> <LabelSourceList> <LabelSource maxlabels=" " name="world Countries"> <Visibility visible="true"> <VisibleRange enabled="true"> <ZoomRange uom="mapinfo:length mi">0 6000</ZoomRange> </VisibleRange> </Visibility> <DataSourceRef ref="id4" /> <BaseLabelProperties> <LabelProperties> <LabelVisibility visible="true" allowoverlap="true" allowduplicates="all" allowoutofview="false"> <VisibleRange enabled="false"> <ZoomRange uom="mapinfo:length mi"> </ZoomRange> </VisibleRange> </LabelVisibility> <LabelText justification="center"> <BaseLabelStyle> <FontStyle family="microsoft Sans Serif" font-style="normal" effect="white" effect-opacity="1" effect-type="none" font-weight="normal" text-decoration="none" text-case="default" shadow="false" expand="false" size="12" size-unit="mapinfo:length pt" stroke="black"/> </BaseLabelStyle> <StringTokenList> <StringToken> <StringValueExpression> <AttributeName>Country</AttributeName> </StringValueExpression> </StringToken> </StringTokenList> <LabelCharacterLimit spacing="1"> </labelcharacterlimit> </LabelText> <LabelCallout visible="false" end="arrow"> <LineStyle stroke="black" stroke-opacity="1" width="1" width-unit="mapinfo:imagesize pixel"> 43

44 Understanding Layers <Pen>mapinfo:pen 2</Pen> </LineStyle> </LabelCallout> <LabelReferencePosition recalculate="outofview"> <LineLabelPositionInterval>0</LineLabelPositionInterval> </LabelReferencePosition> <LabelLayout> <Alignment> <HorizontalAlignment>center</HorizontalAlignment> <VerticalAlignment>center</VerticalAlignment> </Alignment> <Offset uom="mapinfo:imagesize pixel"> <XOffset>0</XOffset> <YOffset>0</YOffset> </Offset> <LabelAngle uom="degrees" origin="referencepoint">0</labelangle> </LabelLayout> <LabelBaseSize usescale="false"> <MapScale>0</MapScale> </LabelBaseSize> <LabelPriority> <MajorPriority> <NumericValueExpression> <MapinfoNumericExpression/> </NumericValueExpression> </MajorPriority> <MinorPriority> <NumericValueExpression> <MapinfoNumericExpression/> </NumericValueExpression> </MinorPriority> </LabelPriority> </LabelProperties> </BaseLabelProperties> <LabelThemeList/> </LabelSource> </LabelSourceList> </LabelLayer> </NamedLayer> 44

45 Understanding Layers Graduated Symbol Layer Graduated symbol layers are object themes that use symbols to represent different values. You can use graduated symbols regardless of the type of map object with which you are working. Graduated symbols maps work best when you use numeric data. Symbols can be displayed for positve and negative values. You can also specify the scale of the view at which a symbol is rendered. This means the symbol will be scaled up or down depending on the scale of the view relative to the reference scale on the Graduated Symbol layer. SymbolBaseSize is available both in the Graduated Symbol layer in the Repository as a Named Layer and also available in the GraduatedSymbolLayer overlay used on the Mapping Service s RenderNamedMapWithOverlay and RenderMap methods. A GraduatedSymbolLayer is represented in Spectrum Technology Platform in four ways: Embedded inline in a named map As a named layer In a SOAP request as an overlay In a REST request as an overlay with an in-memory table. 45

46 Understanding Layers Graduated Symbol Theme Definition This is an example of a definition for a graduated symbol theme: <ObjectThemeLayer id="id5" name="graduated Symbol Theme" alias="graduated Symbol Theme id5"> <DataSourceRef ref="id4" /> <FeatureGraduatedSymbolTheme id="id7"> <Alignment> <HorizontalAlignment>center</HorizontalAlignment> <VerticalAlignment>center</VerticalAlignment> </Alignment> <SymbolBaseSize usescale="false"> <MapScale>1</MapScale> <DataValueAtSize>23</DataValueAtSize> <PositiveSymbol> <PointStyle> <FontSymbol text=""" size="36" size-unit="mapinfo:length pt" stroke="rgb(255,0,0)" stroke-opacity="1" family="mapinfo 3.0 Compatible" /> </PointStyle> </PositiveSymbol> <SymbolGraduation>sqrt</SymbolGraduation> </SymbolBaseSize> <SymbolLayout /> <NumericValueExpression> <AttributeName>Indust_Growth</AttributeName> </NumericValueExpression> </FeatureGraduatedSymbolTheme> </ObjectThemeLayer> Graduated Symbol Theme SOAP Request This is an example of a SOAP mapping service request for a map containing a graduated symbol theme where a reference scale of 10,000,000 has been set using SymbolBaseSize. For a demo of the request, go to the Mapping Service Demo Page for your local installation at 46

47 Understanding Layers the size of the graduated symbols. If you change the ZoomLevel from 3000 to 1500, and re-submit the request, the resulting graduated symbols will appear about twice as large as the original request. <?xml version="1.0"?> <S:Envelope xmlns:s=" xmlns:v1=" xmlns:ns2=" xmlns:ns3=" xmlns:ns4=" xmlns:ns5=" xmlns:ns7=" xmlns:ns8=" xmlns:xsi=" <S:Header/> <S:Body> <v1:rendermaprequest imagemimetype="image/png" returnimage="false"> <v1:mapview xsi:type="v1:zoomandcentermapview"> <v1:width>800.0</v1:width> <v1:height>600.0</v1:height> <v1:zoomlevel uom="mile">3000</v1:zoomlevel> <v1:mapcenter srsname="epsg:4269"> <ns2:pos> <ns2:x>-100</ns2:x> <ns2:y>42</ns2:y> </ns2:pos> </v1:mapcenter> </v1:mapview> <v1:map> <v1:layer xsi:type="v1:graduatedsymbollayer" valueatsize="200000" spatialexpression="obj" valueexpression="pop_1990" SymbolBaseSize="5000" graduationmethod="constant"> <ns5:table xsi:type="ns5:namedtable" name="/samples/namedtables/usa_caps"/> <v1:positivesymbol xsi:type="ns4:namedstyle" name="/samples/namedstyles/pointstylestar"/> <v1:symbolbasesize usescale= true > <v1:mapscale> </v1:mapscale> </v1:symbolbasesize> </v1:layer> <v1:layer xsi:type="v1:featurelayer"> <ns5:table xsi:type="ns5:namedtable" name="/samples/namedtables/usa"/> </v1:layer> </v1:map> </v1:rendermaprequest> </S:Body> </S:Envelope> 47

48 Understanding Layers Bar Chart Layer A bar chart layer contains an object theme that allows you to examine more than one variable per record at a time. A bar chart is built for every map object at the centroid of the object, enabling you to analyze the thematic variables in a particular chart by comparing the height of the bars. You can also examine the same variable across all the charts in your map. You can also change the type of bar chart. You can create a multi-bar chart, where each thematic variable has its own bar. Alternatively, you can create a stacked bar chart with each thematic variable on top of one another, or a graduated bar chart, where the bars are graduated in size based on some value. You can also scale the bars in a multi-bar chart independently from one another. Bar charts can be flat or three-dimensional. To show negative values in a bar chart map, the bars extend in the opposite direction to the chart's orientation. Note that negative values do not display in stacked bar charts. To ensure the order of categories in this type of chart, use an Order By clause in the query that defines the underlying table. Bar Chart Theme Definition This is an example of a definition for a bar chart theme: <ObjectThemeLayer id="id5" 48

49 Understanding Layers name="bar Theme" alias="bar Theme id5"> <DataSourceRef ref="id4" /> <FeatureBarTheme id="id7"> <Alignment> <HorizontalAlignment>center</HorizontalAlignment> <VerticalAlignment>bottom</VerticalAlignment> </Alignment> <BarBaseSize usescale="true"> <MapScale> </MapScale> <DataValueAtSize> </DataValueAtSize> <Height uom="mapinfo:length in">1</height> <Width uom="mapinfo:length in">0.5</width> <BarGraduation>const</BarGraduation> </BarBaseSize> <BarLayout> <BarBaselineAngle uom="degrees">0</barbaselineangle> <SideBySideBars independentsize="false" order="lefttoright" /> </BarLayout> <BarDefinitionList> <BarDefinition> <NumericValueExpression> <AttributeName>Pop_Lt_15</AttributeName> </NumericValueExpression> <AreaStyle> <Interior fill-opacity="1" fill="rgb(255,0,0)" /> </AreaStyle> </BarDefinition> <BarDefinition> <NumericValueExpression> <AttributeName>Pop_16_64</AttributeName> </NumericValueExpression> <AreaStyle> <Interior fill-opacity="1" fill="rgb(0,255,0)" /> </AreaStyle> </BarDefinition> <BarDefinition> <NumericValueExpression> <AttributeName>Pop_65Plus</AttributeName> </NumericValueExpression> <AreaStyle> <Interior fill-opacity="1" fill="rgb(0,0,255)" /> </AreaStyle> </BarDefinition> </BarDefinitionList> </FeatureBarTheme> </ObjectThemeLayer> 49

50 Understanding Layers Bar Chart Theme SOAP Request This is an example of a SOAP mapping service request for a map containing a bar chart theme. For a demo of the request, go to the Mapping Service Demo Page for your local installation at <?xml version="1.0"?> <S:Envelope xmlns:s=" xmlns:v1=" xmlns:ns3=" xmlns:ns5=" xmlns:ns4=" xmlns:xsi=" <S:Header/> <S:Body> <v1:rendermaprequest imagemimetype="image/png" returnimage="false"> <v1:mapview xsi:type="v1:zoomandcentermapview"> <v1:width>800.0</v1:width> <v1:height>600.0</v1:height> <v1:zoomlevel uom="mile">3000</v1:zoomlevel> <v1:mapcenter srsname="epsg:4269"> <ns3:pos> <ns3:x>-101.0</ns3:x> <ns3:y>42.0</ns3:y> </ns3:pos> </v1:mapcenter> </v1:mapview> <v1:map> <v1:layer xsi:type="v1:barlayer" verticalalignment="bottom" horizontalalignment="center" charteffecttype="as3d"> <ns5:table xsi:type="ns5:namedtable" name="/samples/namedtables/usa"/> <v1:graduation graduationmethod="constant"> <v1:valueatsize> </v1:valueatsize> </v1:graduation> <v1:border xsi:type="ns4:namedstyle" name="/samples/namedstyles/linestylesolid"/> <v1:categorylist> <v1:category expression="pop_2000" description="pop_2000"> <ns4:style xsi:type="ns4:namedstyle" name="/samples/namedstyles/areastyleblue"/> </v1:category> <v1:category expression="pop_male" description="pop_male"> <ns4:style xsi:type="ns4:namedstyle" name="/samples/namedstyles/areastylegreen"/> </v1:category> 50

51 Understanding Layers <v1:category expression="pop_female" description="pop_female"> <ns4:style xsi:type="ns4:namedstyle" name="/samples/namedstyles/areastylered"/> </v1:category> </v1:categorylist> <v1:barbasesize usescale="true"> <v1:mapscale> e7</v1:mapscale> </v1:barbasesize> </v1:layer> <v1:layer xsi:type="v1:featurelayer"> <ns5:table xsi:type="ns5:namedtable" name="/samples/namedtables/usa"/> </v1:layer> </v1:map> </v1:rendermaprequest> </S:Body> </S:Envelope> Pie Chart Layer A pie chart layer contains an object theme that enables you to examine more than one variable per record at a time. Like comparing the height of the bars in bar charts, in pie charts you compare the wedges in a single pie, or examine a particular wedge across all pies. Pie charts enable you to compare parts of a whole. Both pie and bar charts are particularly useful for analyzing demographic data. For example, you have a table of demographic information for the United States. Your table shows the populations of several major demographic groups. Using pie charts, you can show the population of each demographic group, and see what fraction of the pie it makes up in each pie. This enables you to see the distribution of demographic groups on a per state basis, or across the entire United States. You can also look at one demographic group and see how the population of the group varies in different states. For best results, use no more than four to six pie wedges per pie chart in your analysis. To ensure the order of categories in this type of chart, use an Order By clause in the query that defines the underlying table. 51

52 Understanding Layers Pie Chart Theme Definition This is an example of a definition for a pie chart theme: <ObjectThemeLayer id="id5" name="pie Theme" alias="pie Theme id5"> <DataSourceRef ref="id4" /> <FeaturePieTheme id="id7"> <Alignment> <HorizontalAlignment>center</HorizontalAlignment> <VerticalAlignment>center</VerticalAlignment> </Alignment> <PieBaseSize usescale="true"> <MapScale> </MapScale> <DataValueAtSize> </DataValueAtSize> <Diameter uom="mapinfo:length in">1</diameter> <PieGraduation>sqrt</PieGraduation> </PieBaseSize> <PieLayout graduatedsize="true"> <PieStartAngle uom="degrees">180</piestartangle> <PieDirection>clockwise</PieDirection> <PieArea>full</PieArea> </PieLayout> <WedgeDefinitionList> <WedgeDefinition> <NumericValueExpression> <AttributeName>Pop_Lt_15</AttributeName> </NumericValueExpression> 52

53 Understanding Layers <AreaStyle> <LineStyle stroke="rgb(0,0,0)" stroke-opacity="1" width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 2</Pen> </LineStyle> <Interior fill-opacity="1" fill="rgb(255,0,0)" /> </AreaStyle> </WedgeDefinition> <WedgeDefinition> <NumericValueExpression> <AttributeName>Pop_16_64</AttributeName> </NumericValueExpression> <AreaStyle> <LineStyle stroke="rgb(0,0,0)" stroke-opacity="1" width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 2</Pen> </LineStyle> <Interior fill-opacity="1" fill="rgb(0,255,0)" /> </AreaStyle> </WedgeDefinition> <WedgeDefinition> <NumericValueExpression> <AttributeName>Pop_65Plus</AttributeName> </NumericValueExpression> <AreaStyle> <LineStyle stroke="rgb(0,0,0)" stroke-opacity="1" width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 2</Pen> </LineStyle> <Interior fill-opacity="1" fill="rgb(0,0,255)" /> </AreaStyle> </WedgeDefinition> </WedgeDefinitionList> </FeaturePieTheme> </ObjectThemeLayer> 53

54 Understanding Layers Pie Chart Theme SOAP Request This is an example of a SOAP mapping service request for a map containing a pie chart theme. For a demo of the request, go to the Mapping Service Demo Page for your local installation at <?xml version="1.0"?> <S:Envelope xmlns:s=" xmlns:v1=" xmlns:ns3=" xmlns:ns4=" xmlns:ns5=" xmlns:xsi=" <S:Header/> <S:Body> <v1:rendermaprequest imagemimetype="image/png" returnimage="false"> <v1:mapview xsi:type="v1:zoomandcentermapview"> <v1:width>800.0</v1:width> <v1:height>600.0</v1:height> <v1:zoomlevel uom="mile">3000.0</v1:zoomlevel> <v1:mapcenter srsname="epsg:4269"> <ns3:pos> <ns3:x>-100.0</ns3:x> <ns3:y>42.0</ns3:y> </ns3:pos> </v1:mapcenter> </v1:mapview> <v1:map name="/samples/namedmaps/mapwithpielayer"> <v1:layer xmlns:xsi=" xsi:type="v1:pielayer" depthfactor="0.50" verticalalignment="middle" horizontalalignment="center" charteffecttype="as3d" charttype="full" startangle="180.0" wedgerenderdirection="clockwise"> <ns5:table xsi:type="ns5:namedtable" name="/samples/namedtables/usa"/> <v1:categorylist> <v1:category expression="pop_2000" description="pop_2000"> <ns4:style xsi:type="ns4:namedstyle" name="/samples/namedstyles/areastyleblue"/> </v1:category> <v1:category expression="pop_male" description="pop_male"> <ns4:style xsi:type="ns4:namedstyle" name="/samples/namedstyles/areastylegreen"/> </v1:category> <v1:category expression="pop_female" description="pop_female"> 54

55 Understanding Layers <ns4:style xsi:type="ns4:namedstyle" name="/samples/namedstyles/areastylered"/> </v1:category> </v1:categorylist> <v1:border xsi:type="ns4:namedstyle" name="/samples/namedstyles/linestylesolid"/> <v1:diameter uom="inch">1.0</v1:diameter> <v1:opacity>1.0</v1:opacity> <v1:graduation graduationmethod="square_root"> <v1:valueatsize> </v1:valueatsize> </v1:graduation> <v1:spatialexpression>obj</v1:spatialexpression> <v1:piebasesize usescale="true"> <v1:mapscale> e7</v1:mapscale> </v1:piebasesize> </v1:layer> <v1:layer xsi:type="v1:namedlayer" name="/samples/namedlayers/layerwithtable" xmlns:xsi=" </v1:map> </v1:rendermaprequest> </S:Body> </S:Envelope> Line Chart Layer A line chart layer contains an object theme that displays information as a series of data points connected by line segments. Like bar and pie charts, this enables you to examine more than one variable per record at a time. To ensure the order of categories in this type of chart, use an Order By clause in the query that defines the underlying table. Line charts are composed of a chart with horizontal and vertical axes that represent the range of data values. The line connects the data points at the appropriate locations along the axes. A grid pattern is provided to aid in visualization. 55

56 Understanding Layers Line Chart Theme Definition This is an example of a definition for a FeatureLineChartTheme. This would be included in a named layer defintion. <ObjectThemeLayer id="id5" name="world LineChart Layer" alias="worldlinechartlayer"> <DataSourceRef ref="id1" /> <FeatureLineChartTheme id="id7"> <ChartBaseSize usescale="true"> <MapScale> </MapScale> <Height uom="mapinfo:length in">1</height> <Width uom="mapinfo:length in">0.5</width> </ChartBaseSize> <ChartLayout visibleoutline="true"> <AreaStyle> <LineStyle stroke="rgb(0,0,0)" stroke-opacity="1" width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 2</Pen> </LineStyle> <Interior fill-opacity="1" fill="(#id8)"> <Defs> <Pattern id="id8"> <Bitmap uri="mapinfo:brush 1"> <ColorAdjustmentSet> <ColorAdjustment color-1="nonwhite" color-2="rgb(153,204,255)" opacity="1" /> <ColorAdjustment color-1="rgb(153,204,255)" color-2="rgb(153,204,255)" opacity="1" /> </ColorAdjustmentSet> </Bitmap> </Pattern> </Defs> 56

57 Understanding Layers </Interior> </AreaStyle> </ChartLayout> <ChartLine> <LineStyle stroke="rgb(0,0,0)" stroke-opacity="1" width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 2</Pen> </LineStyle> </ChartLine> <LineChartDefinitionList> <LineChartDefinition> <NumericValueExpression> <AttributeName>Pop_Male</AttributeName> </NumericValueExpression> <LegendRowOverride visible="false" /> </LineChartDefinition> <LineChartDefinition> <NumericValueExpression> <AttributeName>Pop_Fem</AttributeName> </NumericValueExpression> <LegendRowOverride> <Text>Legend 1</Text> </LegendRowOverride> </LineChartDefinition> <LineChartDefinition> <NumericValueExpression> <AttributeName>Pop_1994</AttributeName> </NumericValueExpression> <LegendRowOverride visible="true"> <Text>Legend 2</Text> </LegendRowOverride> </LineChartDefinition> </LineChartDefinitionList> </FeatureLineChartTheme> </ObjectThemeLayer> Line Chart Theme SOAP Request This is an example of a SOAP mapping service request for a map containing a line chart theme. For a demo of the request, go to the Mapping Service Demo Page for your local installation at <?xml version="1.0"?> <S:Envelope xmlns:s=" xmlns:v1=" xmlns:ns3=" 57

58 Understanding Layers xmlns:ns5=" xmlns:ns4=" xmlns:xsi=" <S:Header/> <S:Body> <v1:rendermaprequest imagemimetype="image/png" returnimage="false" > <v1:mapview xsi:type="v1:zoomandcentermapview"> <v1:width>800.0</v1:width> <v1:height>600.0</v1:height> <v1:zoomlevel uom="mile">1000</v1:zoomlevel> <v1:mapcenter srsname="epsg:4269"> <ns3:pos> <ns3:x>-98.0</ns3:x> <ns3:y>43.0</ns3:y> </ns3:pos> </v1:mapcenter> </v1:mapview> <v1:map> <v1:layer xsi:type="v1:linechartlayer"> <ns5:table xsi:type="ns5:namedtable" name="/samples/namedtables/usa"/> <!-- line customization --> <v1:line xsi:type="ns4:namedstyle" name="/samples/namedstyles/linestylesolid"/> <!-- dataset --> <v1:categorylist> <v1:category expression="pop_2000" description="pop_2000" applystyle="false"> <ns4:style xsi:type="ns4:namedstyle" name="/samples/namedstyles/pointstylepin"/> </v1:category> <v1:category expression="pop_male" description="pop_male"> <ns4:style xsi:type="ns4:namedstyle" name="/samples/namedstyles/compositestyle"/> </v1:category> <v1:category expression="pop_female" description="pop_female"> <ns4:style xsi:type="ns4:namedstyle" name="/samples/namedstyles/pointstylestar"/> </v1:category> </v1:categorylist> <v1:chartwidth uom="pixel">300</v1:chartwidth> <v1:chartheight uom="pixel">300</v1:chartheight> <v1:opacity>0.5</v1:opacity> <!-- Scaling support --> <v1:chartbasesize usescale="true"> <v1:mapscale> e7</v1:mapscale> </v1:chartbasesize> <!-- Domain axis customization --> <v1:domainaxis visible="true" label="true"> <ns4:style xsi:type="ns4:namedstyle" 58

59 Understanding Layers name="/samples/namedstyles/linestyledash"/> </v1:domainaxis> <!-- Range axis customization --> <v1:rangeaxis visible="true" label="true"> <ns4:style xsi:type="ns4:namedstyle" name="/samples/namedstyles/linestyledash"/> </v1:rangeaxis> <!-- line chart plot customization --> <v1:chart visibleoutline="false"> <ns4:style xsi:type="ns4:namedstyle" name="/samples/namedstyles/compositestyle"/> <v1:domaingrid visible="true" > <ns4:style xsi:type="ns4:namedstyle" name="/samples/namedstyles/linestyledash"/> </v1:domaingrid> <v1:rangegrid visible="true" > <ns4:style xsi:type="ns4:namedstyle" name="/samples/namedstyles/linestyledash"/> </v1:rangegrid> </v1:chart> </v1:layer> <v1:layer xsi:type="v1:featurelayer"> <ns5:table xsi:type="ns5:namedtable" name="/samples/namedtables/usa"/> </v1:layer> </v1:map> </v1:rendermaprequest> </S:Body> </S:Envelope> Grid Layer A grid is an overlay layer that shows a continuous gradation of color to represent interpolated values from the underlying data. User-controlled properties of a grid include brightness, contrast, opacity, grayscale, transparency, and an inflection collection (how the colors are defined and spread). A grid is a raster that is generated from a sparse set of points and their values. A raster is made up of pixels, each with a value. Grids are created on the fly as part of a mapping service request. They are not stored in the repository as a named layer. During the interpolation process, every pixel value is assigned an estimated value influenced by the known data values, interpolator weighting algorithm and aggregation method. Once the grid is created, the known and interpolated values are grouped into inflections (bins) and assigned colors. When the grid is displayed, the colors are spread evenly to reflect the gradation of values. Inflections 59

60 Understanding Layers can be pre-calculated and sent via a GridStyle that takes an InflectionList or can be calculated at run-time. Previously created grids from grid creation tools can be displayed as the results of a service request. The following grid formats are supported: MapInfo Grid (.mig), Vertical Mapper Continuous (.grd), Vertical Mapper Classified (.grc) and Defense Digital Terrain Elevation Data (DTED dt0,.dt1,.dt2,.dt3). Spectrum Technology Platform supports the IDW interpolator (inverse distance weighting) which is suitable for most grid applications, including sparse data sets. For more information on the schema elements for grids, see GridLayer Elements on page 60 GridLayer Elements This table defines the schema elements that make up a GridLayer. Element Description Table The underlying table that the grid layer references. Style The style definition that is applied when rendering the grid. The style specified must be a named style that resolves to a GridStyle or a GridStyle itself. If the GridStyle includes its own InflectionList, it overrides the InflectionCollection. For more information on GridStyle see GridStyle on page 127. CellWidth The width of a grid cell in linear units. ValueExpression The expression used to derive the value of a grid cell. 60

61 Understanding Layers Element Description SpatialExpression The expression used to get the value of the point geometry. Interpolator An algorithm used to calculate values in a grid. The IDW (Inverse Distance Weighting) interpolator uses a distance weighted average of data points to calculate grid cell values. It is best suited for data values that produce arbitrary values over the grid, that is, data that does not have any relationship or influence over neighboring data values, such as population. This method of interpolation also works well for sparse data. InflectionCollection A collection of elements that refer to how the color that represents the values is spread between the inflections. If a GridStyle with an InflectionList of pre-calculated inflections is present, InflectionCollection is ignored. GridEnvelope Optional. The bounds of the control points. Usually derived from the data, this property can be used to extend the interpolated bounds beyond the bounds of the points in the data. Grid Layer Overlay Example The following code shows how to create a GridLayer overlay and use it in a request for a named map. Note the use of the CustomInflectionCollection whereby the colors are specified for each inflection. Alternatively you can use a ComputedInflectionCollection with a start and end color and number of inflections. The color is spread evenly across the number of inflections. For an explanation of the GridLayer elements, see GridLayer Elements. public class RenderNamedMapWithGridLayerOverlay { public static void main(string[] args) { try { MappingServiceInterface mapping = Preference.getServiceinterface(); Point mapcenter = BuildGeometry.buildPoint("mapinfo:coordsys 12, 62, 7, 0.0", 0, 0, null); MapView mapview = MappingView.getZoomAndCenterMapView(mapCenter,MappingUtility.buildDistance(19000, DistanceUnit.KILOMETER)); NamedTable namedtable = new NamedTable(); namedtable.setname("/samples/namedtables/worldcaptable"); Distance cellwidth = MappingUtility.buildDistance(50, DistanceUnit.MILE); IDWInterpolator interpolator = new IDWInterpolator(); 61

62 Understanding Layers interpolator.setaggregationmethod(aggregationmethod.average); interpolator.setexponent(2); interpolator.setmaxpoints(25); interpolator.setsearchradius(100); CustomInflectionCollection inflectioncollection = new CustomInflectionCollection(); inflectioncollection.setinflectionmethod(inflectionmethod.equal_count); inflectioncollection.setroundby(0.1); InflectionColorBinList inbinlist = new InflectionColorBinList(); InflectionColorBin red = new InflectionColorBin(); red.setcolor("red"); inbinlist.getinflectioncolorbin().add(red); InflectionColorBin yellow = new InflectionColorBin(); yellow.setcolor("yellow"); inbinlist.getinflectioncolorbin().add(yellow); InflectionColorBin green = new InflectionColorBin(); green.setcolor("green"); inbinlist.getinflectioncolorbin().add(green); InflectionColorBin rgb = new InflectionColorBin(); rgb.setcolor("rgb(0,255,255)"); inbinlist.getinflectioncolorbin().add(rgb); InflectionColorBin blue = new InflectionColorBin(); blue.setcolor("blue"); inbinlist.getinflectioncolorbin().add(blue); inflectioncollection.setinflectioncolorbinlist(inbinlist); //Creating GridEnvelope List<Pos> pointlist = new ArrayList<Pos>(2); pointlist.add(buildgeometry.buildpos( e7, , null)); pointlist.add(buildgeometry.buildpos( e7, , null)); Envelope gridenvelope = BuildGeometry.buildEnvelope("mapinfo:coordsys 12, 62, 7, 0.0", pointlist); 62

63 Understanding Layers //Creating GridLayer Layer gridlayer = MappingUtility.buildGridLayer(namedTable, null, cellwidth, "Cap_Pop", "Obj", interpolator, inflectioncollection, gridenvelope); RenderNamedMapWithOverlayRequest request = MappingServiceRequestBuilder.createRenderNamedMapOverlayRequest ("RenderNamedMapWithGridLayerOverlay","/Samples/NamedMaps/WorldMap", mapview, gridlayer); RenderNamedMapWithOverlayResponse response = mapping.rendernamedmapwithoverlay(request); PrintMappingResponse.printRenderNamedMapWithOverlayResponse(response); } catch (ServiceException se) { PrintMappingResponse.printError(se); } catch (Exception e) { e.printstacktrace(); } } } Modifying the Style with a FeatureStyleModifier To modify the style of a FeatureLayer or a LineLinkageLayer before it is drawn, use a FeatureStyleModifier. A FeatureStyleModifier is a construct that modifies the appearance of a feature in a table using specified criteria or algorithms. There are four types of style modifiers: Table 2: Modifier Description Style override A simple FeatureStyleModifier that applies a style to the layer without condition. Range Applies a style to each feature geometry based on the placement of the feature's numeric data value in a set of numeric ranges. The numeric data value may be the contents of a single numeric valued attribute or the result of evaluating a numeric 63

64 Understanding Layers Modifier Description valued expression. Also contains optional data that defines the constraints used to calculate the bins and styles and an associated legend. Individual Value Applies a style to a feature geometry based on an equality match against the feature's data value. The data value may be the value of a single attribute or the result of evaluating an expression. Also contains optional data that defines an associated legend. Dot Density Uses the density of placement of a "dot" to represent a numeric value associated with a feature. The number of dots that display is the ratio of the feature's numeric value to the value that each dot represents (DensityValueExpression/ValuePerDot). The numeric value may be the contents of a single numeric attribute or the result of evaluating a numeric valued expression. Also contains optional data that defines the associated legend. Style Override A style override applies a single style to all features in a layer. FeatureStyleOverrideTheme Definition This is an example of a definition for a style override. It replaces the style of every feature in the table with this style. <FeatureStyleOverrideTheme id="id6" name="style Override" alias="featurestylemodifier2"> <CompositeStyle> <AreaStyle> <LineStyle width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 9</Pen> </LineStyle> <Interior fill-opacity="1" fill="(#id8)"> <Defs> <Pattern id="id8"> <Bitmap uri="mapinfo:brush 2"> <ColorAdjustmentSet> <ColorAdjustment color-1="nonwhite" color-2="rgb(224,255,176)" opacity="1"/> <ColorAdjustment color-1="white" color-2="white" opacity="1"/> </ColorAdjustmentSet> </Bitmap> </Pattern> </Defs> </Interior> 64

65 Understanding Layers </AreaStyle> <PointStyle> <FontSymbol size="18" size-unit="mapinfo:length pt" stroke="red" stroke-opacity="1" text="c" family="mapinfo Symbols"/> </PointStyle> <MapinfoTextObjectStyle> <FontStyle family="microsoft Sans Serif" font-style="normal" effect="white" effect-opacity="1" effect-type="none" font-weight="normal" text-decoration="none" text-case="default" shadow="false" expand="false" size="12" size-unit="mapinfo:length pt" stroke="black"/> <LineStyle stroke="black" stroke-opacity="1" width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 2</Pen> </LineStyle> </MapinfoTextObjectStyle> </CompositeStyle> </FeatureStyleOverrideTheme> Style Override SOAP Request Example This is an example of a SOAP mapping service request for a map containing an override theme for a style override. To see the result of this request, copy and paste the XML into the Mapping Service Demo Page at and click Submit. <?xml version="1.0"?> <S:Envelope xmlns:s=" xmlns:v1=" xmlns:ns2=" xmlns:ns3=" xmlns:ns5=" xmlns:ns6=" xmlns:ns7=" xmlns:xsi=" <S:Header /> <S:Body> <v1:rendermaprequest imagemimetype="image/png" returnimage="false"> <v1:mapview xsi:type="v1:zoomandcentermapview"> <v1:width>800.0</v1:width> <v1:height>600.0</v1:height> <v1:zoomlevel uom="mile">3700.0</v1:zoomlevel> <v1:mapcenter srsname="epsg:4269"> <ns3:pos> 65

66 Understanding Layers <ns3:x>-74.0</ns3:x> <ns3:y>42.0</ns3:y> </ns3:pos> </v1:mapcenter> </v1:mapview> <v1:map> <v1:layer xsi:type="v1:featurelayer"> <ns2:table xsi:type="ns2:namedtable" name="/samples/namedtables/usa"> </ns2:table> <v1:themelist> <ns5:theme xsi:type="ns5:overridetheme" > <ns6:style xsi:type="ns6:namedstyle" name="/samples/namedstyles/areastylered" /> </ns5:theme> </v1:themelist> </v1:layer> </v1:map> </v1:rendermaprequest> </S:Body> </S:Envelope> Range Theme When you create a range thematic map, all records are grouped into ranges and each record's object is assigned the color, symbol, or line for its corresponding range. For example, if you wanted to visualize the population of the world by growth rate, you would shade countries according to their reported growth rate amounts. The growth rate amounts are grouped into ranges. All records are assigned to a range and then assigned a color based on that range. 66

67 Understanding Layers Types of Ranged Values You can create ranges using five methods: Equal Count Equal Ranges Natural Break (Standard Deviation) Quantile Custom Equal Count Equal Count has the same number of records in each range. If you want to group 100 records into 4 ranges using Equal Count, the Equal Count method computes the ranges so that approximately 25 records fall into each range, depending on the rounding factor you set. When using Equal Count (or any other range method), it's important to watch out for any extreme data values that might affect your thematic map (in statistics, these values are referred to as outliers). Equal Ranges Equal Ranges divides records across ranges of equal size. For example, you have a field in your table with data values ranging from 1 to 100. You want to create a thematic map with four equal size ranges. The Equal Ranges method produces ranges 1-25, 25-50, 50-75, and (Since ranges use "=>" and "<=", they need to overlap.) Keep in mind that the Equal Ranges method may create ranges with no data records, depending on the distribution of your data. Natural Break (Standard Deviation) Natural Break creates ranges according to an algorithm that uses the average of each range to distribute the data more evenly across the ranges. It distributes the values so that the average of each range is as close as possible to each of the range values in that range. This ensures that the ranges are well-represented by their averages, and that data values within each of the ranges are fairly close together. The Natural Break algorithm is based on the procedure described by Jenks and Caspall in their article "Error on Choroplethic Maps: Definition, Measurement, Reduction" from the Annals of American Geographers, June When you create ranges using Standard Deviation, the middle range breaks at the mean of your values, and the ranges above and below the middle range are one standard deviation above or below the mean. Quantile Quantiling enables you to build ranges that determine the distribution of a thematic variable across a segment of your data. For example, you can quantile state population by urban population to illustrate how urban population is distributed across the United States. Your map legend will not 67

68 Understanding Layers indicate that you have used Quantile to build your ranges. You can customize the map legend so that it shows which field you used to quantile the table. Custom Ranges Spectrum Technology Platform also suppports creating custom ranges. To set ranges manually, use Custom. FeatureStyleRangeTheme Example This is an example of a definition for a ranged theme: <FeatureStyleRangeTheme id="id6" alias="ranged Theme id6" name="ranges by Pop_1980"> <RangeValueExpression> <NumericValueExpression> <AttributeName>Pop_1980</AttributeName> </NumericValueExpression> </RangeValueExpression> <RangeThemeBaseStyle applystylepart="all"> <AreaStyle> <LineStyle stroke="rgb(0,0,0)" stroke-opacity="1" width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 2</Pen> </LineStyle> <Interior fill-opacity="1" fill="(#id7)"> <Defs> <Pattern id="id7"> <Bitmap uri="mapinfo:brush 42"> <ColorAdjustmentSet> <ColorAdjustment color-1="nonwhite" color-2="rgb(255,0,0)" opacity="1"/> <ColorAdjustment color-1="rgb(255,255,255)" color-2="rgb(255,255,255)" opacity="1"/> </ColorAdjustmentSet> </Bitmap> </Pattern> </Defs> </Interior> </AreaStyle> </RangeThemeBaseStyle> 68

69 Understanding Layers <RangeThemeBinSet> <RangeThemeBin> <NumericRange> </NumericRange> <CompositeStyle> <LineStyle stroke="rgb(0,0,0)" stroke-opacity="1" width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 2</Pen> </LineStyle> <AreaStyle> <LineStyle stroke="rgb(0,0,0)" stroke-opacity="1" width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 2</Pen> </LineStyle> <Interior fill-opacity="1" fill="(#id8)"> <Defs> <Pattern id="id8"> <Bitmap uri="mapinfo:brush 3"> <ColorAdjustmentSet> <ColorAdjustment color-1="nonwhite" color-2="rgb(0,0,0)" color-1="rgb(255,255,255)" opacity="1"/> <ColorAdjustment color-2="rgb(255,255,255)" opacity="1"/> </ColorAdjustmentSet> </Bitmap> </Pattern> </Defs> </Interior> </AreaStyle> <PointStyle> <FontSymbol text=""" size="12" size-unit="mapinfo:length pt" stroke="rgb(0,0,0)" stroke-opacity="1" family="mapinfo 3.0 Compatible"/> </PointStyle> </CompositeStyle> </RangeThemeBin> <RangeThemeBin> 69

70 Understanding Layers <NumericRange> </NumericRange> <CompositeStyle> <LineStyle stroke="rgb(128,0,0)" stroke-opacity="1" width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 2</Pen> </LineStyle> <AreaStyle> <LineStyle stroke="rgb(0,0,0)" stroke-opacity="1" width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 2</Pen> </LineStyle> <Interior fill-opacity="1" fill="rgb(128,0,0)"/> </AreaStyle> <PointStyle> <FontSymbol text=""" size="12" size-unit="mapinfo:length pt" stroke="rgb(128,0,0)" stroke-opacity="1" family="mapinfo 3.0 Compatible"/> </PointStyle> </CompositeStyle> </RangeThemeBin> <RangeThemeBin> <NumericRange> </NumericRange> <CompositeStyle> <LineStyle stroke="rgb(255,0,0)" stroke-opacity="1" width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 2</Pen> </LineStyle> <AreaStyle> <LineStyle stroke="rgb(0,0,0)" stroke-opacity="1" width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 2</Pen> </LineStyle> <Interior fill-opacity="1" fill="(#id9)"> <Defs> <Pattern id="id9"> <Bitmap uri="mapinfo:brush 42"> 70

71 Understanding Layers <ColorAdjustmentSet> <ColorAdjustment color-1="nonwhite" color-2="rgb(255,0,0)" opacity="1"/> <ColorAdjustment color-1="rgb(255,255,255)" color-2="rgb(255,255,255)" opacity="1"/> </ColorAdjustmentSet> </Bitmap> </Pattern> </Defs> </Interior> </AreaStyle> <PointStyle> <FontSymbol text=""" size="12" size-unit="mapinfo:length pt" stroke="rgb(255,0,0)" stroke-opacity="1" family="mapinfo 3.0 Compatible"/> </PointStyle> </CompositeStyle> </RangeThemeBin> <AllOthersStyle> <CompositeStyle> <LineStyle stroke="rgb(255,255,255)" stroke-opacity="1" width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 2</Pen> </LineStyle> <AreaStyle> <LineStyle stroke="rgb(0,0,0)" stroke-opacity="1" width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 2</Pen> </LineStyle> <Interior fill-opacity="1" fill="rgb(255,255,255)"/> </AreaStyle> <PointStyle> <FontSymbol text="(" 71

72 Understanding Layers size="12" size-unit="mapinfo:length pt" stroke="rgb(255,255,255)" stroke-opacity="1" family="mapinfo 3.0 Compatible"/> </PointStyle> </CompositeStyle> </AllOthersStyle> </RangeThemeBinSet> <RangeThemeBinValueConstraints> <RangeSpreadMethod allowemptyranges="false">equalcount</rangespreadmethod> <RoundTo>100000</RoundTo> </RangeThemeBinValueConstraints> <RangeThemeBinStyleConstraints spreadmethod="color"> <ColorSpreadMethod>rgb</ColorSpreadMethod> <SizeSpreadMethod>sqrt</SizeSpreadMethod> </RangeThemeBinStyleConstraints> </FeatureStyleRangeTheme> Range Theme SOAP Request Example This is an example of a SOAP mapping service request for a map containing a range theme. For a demo of the request, go to the Mapping Service Demo Page for your local installation at <?xml version="1.0"?> <S:Envelope xmlns:s=" xmlns:v1=" xmlns:ns2=" xmlns:ns3=" xmlns:ns5=" xmlns:ns6=" xmlns:ns7=" xmlns:xsi=" <S:Header /> <S:Body> <v1:rendermaprequest imagemimetype="image/png" returnimage="false"> <v1:mapview xsi:type="v1:zoomandcentermapview"> <v1:width>800.0</v1:width> <v1:height>600.0</v1:height> <v1:zoomlevel uom="mile">3000.0</v1:zoomlevel> <v1:mapcenter srsname="epsg:4269"> <ns3:pos> 72

73 Understanding Layers <ns3:x> </ns3:x> <ns3:y> </ns3:y> </ns3:pos> </v1:mapcenter> </v1:mapview> <v1:map> <v1:layer xsi:type="v1:featurelayer"> <ns2:table xsi:type="ns2:namedtable" name="/samples/namedtables/usa" /> <v1:themelist> <ns5:theme xsi:type="ns5:rangetheme"> <ns5:startstyle xsi:type="ns6:namedstyle" name="/samples/namedstyles/areastyleblue" /> <ns5:endstyle xsi:type="ns6:namedstyle" name="/samples/namedstyles/areastylered" /> <ns5:rangethemeproperties xsi:type="ns5:rangethemeproperties" rangetype="equalcount" expression="pop_2000" numranges="6" /> </ns5:theme> </v1:themelist> </v1:layer> </v1:map> </v1:rendermaprequest> </S:Body> </S:Envelope> Individual Value Theme Individual value themes show points, lines, or boundaries that are shaded by individual values contained in a particular field or the result of an expression. You can use both numerical and nominal values in individual values maps. Each unique value is given its own color or symbol. When an individual values map uses symbol types, the symbols are taken from the base table. If you are shading your points, lines or boundaries using nominal data, you can shade only by individual values. Nominal data is either non-numerical data (name, type of cuisine served, or brand of automobile sold) or numeric data where the numbers represent non-numeric data like an ID number. Dates are considered numeric data and can be used in both ranged and individual values maps. 73

74 Understanding Layers Individual Value Theme SOAP Request This is an example of a SOAP mapping service request for a map containing an individual value theme. For a demo of the request, go to the Mapping Service Demo Page for your local installation at <?xml version="1.0"?> <S:Envelope xmlns:s=" xmlns:v1=" xmlns:ns2=" xmlns:ns3=" xmlns:ns5=" xmlns:ns6=" xmlns:ns7=" xmlns:xsi=" <S:Header/> <S:Body> <v1:rendermaprequest imagemimetype="image/png" returnimage="false"> <v1:mapview xsi:type="v1:zoomandcentermapview"> <v1:width>800.0</v1:width> <v1:height>600.0</v1:height> <v1:zoomlevel uom="mile">3000.0</v1:zoomlevel> <v1:mapcenter srsname="epsg:4269"> <ns3:pos> <ns3:x> </ns3:x> <ns3:y> </ns3:y> </ns3:pos> </v1:mapcenter> </v1:mapview> <v1:map> 74

75 Understanding Layers <v1:layer xsi:type="v1:featurelayer"> <ns2:table xsi:type="ns2:namedtable" name="/samples/namedtables/usa"/> <v1:themelist> <ns5:theme expression="state" xsi:type="ns5:individualvaluetheme"> <ns5:binlist> <ns5:bin> <ns5:value xsi:type="ns7:stringvalue"> <ns7:value>ca</ns7:value> </ns5:value> <ns6:style xsi:type="ns6:namedstyle" name="/samples/namedstyles/areastyleblue"/> </ns5:bin> <ns5:bin> <ns5:value xsi:type="ns7:stringvalue"> <ns7:value>tx</ns7:value> </ns5:value> <ns6:style xsi:type="ns6:namedstyle" name="/samples/namedstyles/areastylegreen"/> </ns5:bin> </ns5:binlist> <ns5:allothers xsi:type="ns6:namedstyle" name="/samples/namedstyles/areastylered"/> </ns5:theme> </v1:themelist> </v1:layer> </v1:map> </v1:rendermaprequest> </S:Body> Dot Density Theme Dot density themes use dots to represent the data value associated with a boundary or region. The total number of dots in a region represents that region's data value. If you have 10,000 senior citizens in a county, and each dot represents 100 senior citizens, there would be 100 dots in the county boundary. Dot density is particularly useful for showing raw data where one dot represents a large number of something: population, number of fast food restaurants, number of distributors who carry a brand of soda, etc. Distribution of dots is random within the region. If you shade states according to population, the dots for New York are spread out throughout the state; they are not concentrated in New York City, where the majority of the state's population lives. 75

76 Understanding Layers Named Layer with Dot Density Theme A dot density theme is a style modifier theme called a FeatureStyleDotDensityTheme. The schema is contained in MXP_MapTheme_1_5.xsd. A dot density theme is stored in the Spectrum Spatial repository as part of a named layer. The theme is defined by an expression whose value is the density for each feature; a value per dot, and a dot style. Dot density themes contain optional data for defining an associated legend, including style overrides and controlling visibility. For the schema see MXP_MapLegend_1_5.xsd. Dot Density Theme Definition This is an example of a definition for a dot density theme: <FeatureLayer id="id5" name="usa" alias="usa" volatile="unknown"> <DataSourceRef ref="id4"/> <FeatureStyleModifierThemeList> <FeatureStyleDensityTheme id="id6" alias="dot Density Theme id6" name="dot Density with Pop_1990"> <DensityValueExpression> <NumericValueExpression> <AttributeName>Pop_1990</AttributeName> </NumericValueExpression> </DensityValueExpression> <ValuePerDot>600000</ValuePerDot> <DotStyle> <PointStyle> <FontSymbol text=""" size="4" size-unit="mapinfo:length pt" stroke="rgb(255,0,0)" stroke-opacity="1" family="mapinfo 3.0 Compatible"/> </PointStyle> </DotStyle> </FeatureStyleDensityTheme> </FeatureStyleModifierThemeList> </FeatureLayer> 76

77 Understanding Layers Dot Density Theme SOAP Request This is an example of a SOAP mapping service request for a map containing a dot density theme. <?xml version="1.0"?> <S:Envelope xmlns:s=" xmlns:v1=" xmlns:ns3=" xmlns:xsi=" <S:Header/> <S:Body> <v1:rendermaprequest imagemimetype="image/png" returnimage="false"> <v1:mapview xsi:type="v1:zoomandcentermapview"> <v1:width>800.0</v1:width> <v1:height>600.0</v1:height> <v1:zoomlevel uom="mile">3700.0</v1:zoomlevel> <v1:mapcenter srsname="epsg:4269"> <ns3:pos> <ns3:x>-100.0</ns3:x> <ns3:y>42.0</ns3:y> </ns3:pos> </v1:mapcenter> </v1:mapview> <v1:map> <v1:layer xsi:type="v1:namedlayer" name="/test/dotdensity/usdotslayer" xmlns:xsi=" </v1:map> </v1:rendermaprequest> </S:Body> </S:Envelope> 77

78 6 - Using Styles 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. You specify the styles you want to use to display a map when you submit the XML request for the map. In this section Types of Styles 79 Pattern Codes 131 Symbol Codes 133

79 Using Styles Types of Styles There are three types of styles you can specify. The first way is to specify the styles for lines, filled areas, and so on, by listing them directly in the XML request. The second way is to define a named style in a file, then add the file to a JCR repository that is accessible to the Repository Service. You can then refer to the named style file in your XML request. For requests including a GridLayer, a third method to specify the style is to use GridStyle. GridStyle takes a list of inflections where each inflection contains a color and value. Note: This GridStyle is an extension of Style. There is also a GridStyle named style that takes a GridInflectionList. MapBasic Styles MapBasic styles are based on the style clauses for Pen, Brush and Symbol available in the MapBasic language. To specify a MapBasic style when requesting a map, you add the MapBasic style settings directly into the XML request. For example, to display a ranged theme using a <MapBasicPen> style, your XML request would contain lines such as the following: <ns5:startstyle xsi:type="ns6:mapbasiclinestyle"> <ns6:mapbasicpen> <ns6:width>1</ns6:width> <ns6:pattern>81</ns6:pattern> <ns6:color>red</ns6:color> </ns6:mapbasicpen> </ns5:startstyle> For information about the MapBasic style elements you can add to an XML request, see MapBasic Styles on page 79. MapBasic Styles When you want to specify MapBasic style elements in an XML request, you provide your style element (such as a <StartStyle> element) with a type attribute that has one of the following values: MapBasicLineStyle 79

80 Using Styles MapBasicAreaStyle MapBasicPointStyle MapBasicTextStyle MapBasicCompositeStyle For example: <ns5:startstyle xsi:type="ns6:mapbasiclinestyle"> <ns6:mapbasicpen> <ns6:width>1</ns6:width> <ns6:pattern>81</ns6:pattern> <ns6:color>red</ns6:color> </ns6:mapbasicpen> </ns5:startstyle> MapBasicLineStyle A style of type MapBasicLineStyle specifies the visual characteristics of a line. The style can contain a MapBasicPen element. MapBasicPen Description The MapBasicPen element defines a style for a linear object such as a line, polyline arc, or the border of a region. Elements Table 3: Elements on page 80 lists the elements that can be contained by a MapBasicPen element. Table 3: Elements Element Description Width An integer value from 0 to 7 specifying the thickness of the line (in pixels). To create an invisible line style, specify a width of 0 and a pattern value of 1. Pattern An integer value from 1 to 118 specifying the line pattern. The available line patterns, and corresponding pattern codes, are shown in Line Pattern Codes on page

81 Using Styles Element Description Color A string value specifying the color of the pen stroke. The value can be any valid CSS color. (See Example This example specifies a solid red line that is two pixels wide. <ns6:mapbasicpen> <ns6:width>2</ns6:width> <ns6:pattern>2</ns6:pattern> <ns6:color>red</ns6:color> </ns6:mapbasicpen> MapBasicAreaStyle A style of type MapBasicAreaStyle specifies the visual characteristics of a filled area. The style can contain a MapBasicPen element or a MapBasicBrush element or both. MapBasicPen Description The MapBasicPen element defines a style for a linear object such as a line, polyline arc, or the border of a region. Elements Table 4: Elements on page 81 lists the elements that can be contained by a MapBasicPen element. Table 4: Elements Element Description Width An integer value from 0 to 7 specifying the thickness of the line (in pixels). To create an invisible line style, specify a width of 0 and a pattern value of 1. Pattern An integer value from 1 to 118 specifying the line pattern. 81

82 Using Styles Element Description The available line patterns, and corresponding pattern codes, are shown in Line Pattern Codes on page 131. Color A string value specifying the color of the pen stroke. The value can be any valid CSS color. (See Example This example specifies a solid red line that is two pixels wide. <ns6:mapbasicpen> <ns6:width>2</ns6:width> <ns6:pattern>2</ns6:pattern> <ns6:color>red</ns6:color> </ns6:mapbasicpen> MapBasicBrush Description The MapBasicBrush element defines a style for a filled object, such as a circle or region. Elements Table 5: Elements on page 82 lists the elements that can be contained by a MapBasicBrush element. Table 5: Elements Element Description Pattern An integer value from 1 to 8 and from 12 to 175 specifying the fill pattern. Note: Pattern codes 9 to 11 are reserved. The available fill patterns, and corresponding pattern codes, are shown in Fill Pattern Codes on page 132. ForegroundColor A string value specifying the foreground color. 82

83 Using Styles Element Description The value can be any valid CSS color. (See BackgroundColor A string value specifying the background color. The value can be any valid CSS color. (See Note: Omitting this element will yield a transparent background. Example This example specifies a fill pattern of blue horizontal lines on a yellow background. <ns6:mapbasicbrush> <ns6:pattern>3</ns6:pattern> <ns6:foregroundcolor>blue</ns6:foregroundcolor> <ns6:backgroundcolor>yellow</ns6:backgroundcolor> </ns6:mapbasicbrush> MapBasicPointStyle A style of type MapBasicPointStyle specifies the visual characteristics of a symbol. The style can contain a MapBasicSymbol element. MapBasicSymbol The MapBasicSymbol element has a type attribute that specifies one of the following types of symbol. MapBasic30Symbol MapBasicFontSymbol MapBasicBitmapSymbol MapBasic30Symbol Description A MapBasicSymbol element of type MapBasic30Symbol specifies the size, color, and code of a symbol taken from the MapInfo 3.0 symbol set. 83

84 Using Styles Elements Table 6: Elements on page 84 lists the elements that can be contained by a MapBasicSymbol element of type MapBasic30Symbol. Table 6: Elements Element Description Shape An integer value from 31 to 67 specifying the symbol code to use from the MapInfo 3.0 symbol set. The MapInfo 3.0 symbol set, and corresponding code for each symbol, is shown in MapInfo 3.0 Symbol Codes on page 133. Color A string value specifying the color of the symbol. The value can be any valid CSS color. (See Size An integer value from 1 to 255 specifying the point size of the symbol. Example <ns6:mapbasicsymbol xsi:type="ns6:mapbasic30symbol"> <ns6:shape>56</ns6:shape> <ns6:color>blue</ns6:color> <ns6:size>12</ns6:size> </ns6:mapbasicsymbol> MapBasicFontSymbol Description A MapBasicSymbol element of type MapBasicFontSymbol specifies the character code of a symbol taken from a TrueType symbol font, as well as various other attributes of the symbol. Elements Table 7: Elements on page 85 lists the elements that can be contained by a MapBasicSymbol element of type MapBasicFontSymbol. 84

85 Using Styles Table 7: Elements Element Description Shape An integer value of 32 or larger specifying the character to use from a TrueType symbol font. Note: To specify an invisible symbol, use 32 (the space character). The MapBasic font symbol sets, and corresponding code for each symbol, is shown in MapBasic Font Symbol Codes on page 134. Color A string value specifying the color of the symbol. The value can be any valid CSS color. (See Size An integer value from 1 to 255 specifying the point size of the symbol. FontName A string value specifying the name of the TrueType symbol font to use (for example, "WingDings"). You can also specify a MapBasic font symbol set such as "MapInfo Symbols" or "MapInfo Arrows". The MapBasic font symbol sets, and corresponding code for each symbol, is shown in MapBasic Font Symbol Codes on page 134. Bold A boolean value (true or false) specifying whether the symbol should be bold (true) or plain (false). The default value is false. Border An enumeration value specifying the type of border to draw around the symbol. Possible values are: normal halo The value normal draws a regular black border around the symbol. The value halo draws a white halo border around the symbol. DropShadow A boolean value (true or false) specifying whether to have a drop-shadow drawn behind the symbol. A value of false (the default) specifies no drop-shadow. 85

86 Using Styles Element Description Rotation A floating-point value from 0 to 360 specifying the rotation angle of the symbol in degrees. Example <ns6:mapbasicsymbol xsi:type="ns6:mapbasicfontsymbol"> <ns6:shape>32</ns6:shape> <ns6:color>blue</ns6:color> <ns6:size>12</ns6:size> <ns6:fontname>wingdings</ns6:fontname> <ns6:bold>true</ns6:bold> <ns6:border>normal</ns6:border> <ns6:rotation>45</ns6:rotation> </ns6:mapbasicsymbol> MapBasicBitmapSymbol Description A MapBasicSymbol element of type MapBasicBitmapSymbol specifies the name of a bitmap symbol file, as well as the size and color of the symbol. Elements Table 8: Elements on page 86 lists the elements that can be contained by a MapBasicSymbol element of type MapBasicBitmapSymbol. Table 8: Elements Element Description URI A string value specifying the URI of the bitmap image file. Color A string value specifying the color of the symbol. Any non-white pixels in the bitmap are set to this color. The value can be any valid CSS color. (See Size An integer value from 1 to 255 specifying the point size of the symbol. 86

87 Using Styles Element Description If this element is omitted, the image is rendered at its native width and height in pixels. Transparent A boolean value (true or false) specifying whether white pixels in the bitmap should be set to transparent (true) or left as opaque white (false). The default value is true. MapBasicTextStyle A style of type MapBasicTextStyle specifies the visual characteristics of a text style. The complextype style contains the element MapBasicFontStyle. MapBasicFontStyle Description The MapBasicFontStyle element defines the font style portion of a MapBasicTextStyle. Elements Table 9: Elements on page 87 lists the elements that can be contained by a MapBasicFontStyle element. Table 9: Elements Element Description FontName Identifies the name of the font to use. For example, Arial or MapInfo Symbols, etc. MapInfo Fonts are installed with the product while other fonts are used from the system. Style Controls text attributes, according to the following list: 0 - Plain 1 - Bold 2 - Italic 4 - Underline 8 - Strikethrough 32 - Shadow Halo All Caps Expanded Size The height of the characters in points. 87

88 Using Styles Element Description ForegroundColor A string value specifying the foreground color of the text. The value can be any valid CSS color. (See BackgroundColor A string value specifying the background color of the text. The value can be any valid CSS color. (See Example This example specifies a font style: Verdana 12 pt italic, black with red background. <ns6:mapbasicfontstyle> <ns6:fontname>verdana</ns6:fontname> <ns6:size>12</ns6:size> <ns6:style>2</ns6:style> <ns6:foregroundcolor>black</ns6:foregroundcolor> <ns6:backgroundcolor>red</ns6:backgroundcolor> </ns6:mapbasicfontstyle> MapBasicCompositeStyle A style of type MapBasicCompositeStyle specifies the visual characteristics of a mixed set of geometry types such as lines and areas. The style can contain any or all of the following elements: LineStyle, AreaStyle, and PointStyle. LineStyle The LineStyle element is used within a style of type MapBasicCompositeStyle to contain a MapBasicPen element. AreaStyle The AreaStyle element is used within a style of type MapBasicCompositeStyle to contain a MapBasicPen element or a MapBasicBrush element or both. PointStyle The PointStyle element is used within a style of type MapBasicCompositeStyle to contain a MapBasicSymbol element. 88

89 Using Styles Named Styles A named style is a collection of related style settings that have been placed in a file. The file, in turn, is added to a JCR content repository that is accessible to the Repository Service. When you are requesting a map, and you want the map to use a named style, you add a reference to the file that contains the named style in the XML request. For example, to display a map overlay using an <AreaStyle> that is contained in a file named AreaStyleGreen and which has been added to a JCR repository under a directory named NamedStyles, your XML request would contain a line such as the following: <v3:style xsi:type="v3:namedstyle" name="/namedstyles/areastylegreen" xmlns:v3=" For information about the elements you can add to a named style, see Named Styles. Defining Named Styles To define a named style: 1. Add the relevant named style elements, and the desired content for each element, into an XML file. Note: The root element of the XML file must be <NamedStyle version="mxp_workspace_1_5" xmlns=" 2. Add the file into a JCR repository that is accessible to the Repository Service. An example of a typical named style file is shown here: <?xml version="1.0" encoding="utf-8"?> <NamedStyle version="mxp_workspace_1_5" xmlns=" <LineStyle stroke="black" stroke-opacity="1" width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 9</Pen> </LineStyle> </NamedStyle> 89

90 Using Styles After you have added the named style file to the repository, you can reference the named style in your XML request by specifying the path and filename of the XML file. Line Styles A line style specifies the visual characteristics of a line. LineStyle Description The LineStyle element defines a style for a line. Context Table 10: Context on page 90 lists the elements that can contain, or be contained by, a LineStyle element. Table 10: Context Contained by Element Contains NamedStyle or CompositeStyle or AreaStyle LineStyle Pen Attributes Table 11: Attributes on page 90 lists the attributes of a LineStyle element. Table 11: Attributes Attribute Description id A unique identifier for the element. name A descriptive name for the element. stroke A string value specifying the color of the line. 90

91 Using Styles Attribute Description The value can be any valid CSS color. (See The stroke attribute is optional. The default value is black. stroke-opacity A floating-point value from 0 to 1 specifying the opacity of the line. A value of 0 means that the line is totally transparent. A value of 1 means that the line is totally opaque. A value of 0.5 means that the line is 50% translucent. The stroke-opacity attribute is optional. The default value is 1. width An integer value specifying the width of the line. The width attribute is optional. The default value is 1. width-unit A reference to an imagesize in the mapinfo codespace, which specifies a width unit. The width-unit attribute is optional. The default value is mapinfo:imagesize pixel. miterlimit A limit on the ratio of the miter length to the line width for linejoins of type miter. When two line segments meet at a sharp angle and miter joins have been specified for linejoin, it is possible for the miter to extend far beyond the thickness of the line stroking the path. The miterlimit attribute is optional. The default value is 10. linecap An enumeration value specifying the decorative shape to be used at the end of open subpaths when they are stroked. Possible values are: butt round square The value butt means no decoration is used. The value round means the line ends with a semicircle whose radius is half the line width. The value square means the line ends with a rectangle whose length is half the line width. The linecap attribute is optional. The default value is round. linejoin An enumeration value specifying the shape to be used at the corners of paths or basic shapes when they are stroked. Possible values are: 91

92 Using Styles Attribute Description miter bevel round The value miter means the outer edges of lines extend until they intersect. If the miter is longer than the miterlimit, the type bevel is substituted. The value bevel means lines are joined by connecting the outer edges of their ends. The value round means each line segment is ended with a semicircle whose radius is half the line width. The linejoin attribute is optional. The default value is round. marker-placement An enumeration value specifying the placement style for markers. Possible values are: LEFT CENTER RIGHT HORIZONTAL MATCH_SEGMENT none Note: Currently only none is supported for marker placement. Markers can be placed at the start, end, or middle nodes of line segments and can be drawn along line segments continuously. The values LEFT, CENTER, and RIGHT specify the horizontal justification for a multi-line text marker. The values HORIZONTAL and MATCH_SEGMENT specify the rotational orientation of a symbol marker relative to the line segment. The marker-placement attribute is optional. The default value is none. dasharray An array of comma or whitespace delimited integer values that specify the lengths (in pixels) of alternating dashes and spaces for a dashed line. For example, or 10,20,30,10. The array must contain an even number of positive integers, or the special value none. The first integer in the array specifies the length of the first dash, the second integer specifies the length of the first space, and so on through the array. For example, the following value 10,20,30,10 specifies a dashed line in which the first dash is 10 pixels long, followed by a space 20 pixels long, followed by a dash 30 pixels long, followed by a space 10 pixels long. The pattern then repeats for the length of the dashed line. 92

93 Using Styles Attribute Description The dasharray attribute is optional. The default value is none, which is equivalent to the array 1,1. dashoffset A positive integer value specifying the number of units (in pixels) from the start of the line segment at which the first dash of a dashed line will be drawn. The dashoffset attribute is optional. The default value is 0. Example This example specifies a dashed black line that is one pixel wide. <?xml version="1.0" encoding="utf-8"?> <NamedStyle version="mxp_workspace_1_5" xmlns=" <LineStyle stroke="black" stroke-opacity="1" width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 9</Pen> </LineStyle> </NamedStyle> Pen Description The content of the Pen element is a reference to a pen in the mapinfo codespace, which specifies a line pattern code. For example: mapinfo:pen 5 The available line patterns, and corresponding pattern codes, are shown in Line Pattern Codes on page 131. Context Table 12: Context on page 94 lists the elements that can contain, or be contained by, a Pen element. 93

94 Using Styles Table 12: Context Contained by Element Contains LineStyle Pen (text) Attributes The Pen element has no attributes. Example This example specifies a dashed black line that is one pixel wide. <?xml version="1.0" encoding="utf-8"?> <NamedStyle version="mxp_workspace_1_5" xmlns=" <LineStyle stroke="black" stroke-opacity="1" width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 9</Pen> </LineStyle> </NamedStyle> Fill Styles A fill style specifies the visual characteristics of a filled area. Interior Description The Interior element defines a style for a filled area. Context Table 13: Context on page 95 lists the elements that can contain, or be contained by, an Interior element. 94

95 Using Styles Table 13: Context Contained by Element Contains NamedStyle or AreaStyle Interior Defs or Pattern Attributes Table 14: Attributes on page 95 lists the attributes of an Interior element. Table 14: Attributes Attribute Description id A unique identifier for the element. name A descriptive name for the element. fill The fill color or pattern. The value can be one of five different forms of defining a color, or the id of an underlying Pattern element, or the special value none to indicate no value. Examples: blue #F80 #EE97A2 rgb(255,0,30) rgb(21.5%, 90%, 3.1%) (#id20) none The fill attribute is optional. The default value is black. fill-opacity A floating-point value from 0 to 1 specifying the opacity of the fill. A value of 0 means that the fill is totally transparent. A value of 1 means that the fill is totally opaque. A value of 0.5 means that the fill is 50% translucent. The fill-opacity setting is multiplicative to any opacity setting in an underlying ColorAdjustment element. For example, if the Interior element has a fill-opacity setting of 0.5, and an underlying ColorAdjustment element has an opacity setting of 0.4, then the final opacity would be , or 0.2. The fill-opacity attribute is optional. The default value is 1. 95

96 Using Styles Example This example specifies a solid fill pattern. <?xml version="1.0" encoding="utf-8"?> <NamedStyle version="mxp_workspace_1_5" xmlns=" <Interior fill-opacity="1" fill="(#id7)"> <Defs> <Pattern id="id7"> <Bitmap uri="mapinfo:brush 2"> <ColorAdjustmentSet> <ColorAdjustment color-1="nonwhite" color-2="rgb(224,255,176)" opacity="1"/> <ColorAdjustment color-1="white" color-2="white" opacity="1"/> </ColorAdjustmentSet> </Bitmap> </Pattern> </Defs> </Interior> </NamedStyle> Defs Description The Defs element serves as a container for a Pattern element that is referred to by an Interior element. Context Table 15: Context on page 96 lists the elements that can contain, or be contained by, a Defs element. Table 15: Context Contained by Element Contains Interior Defs Pattern 96

97 Using Styles Attributes The Defs element has no attributes. Example This example shows a Pattern element contained within a Defs element, which is in turn contained within an Interior element. Note how the Interior element's fill attribute refers to the underlying Pattern element by its id attribute. <?xml version="1.0" encoding="utf-8"?> <NamedStyle version="mxp_workspace_1_5" xmlns=" <Interior fill-opacity="1" fill="(#id7)"> <Defs> <Pattern id="id7"> <Bitmap uri="mapinfo:brush 2"> <ColorAdjustmentSet> <ColorAdjustment color-1="nonwhite" color-2="rgb(224,255,176)" opacity="1"/> <ColorAdjustment color-1="white" color-2="white" opacity="1"/> </ColorAdjustmentSet> </Bitmap> </Pattern> </Defs> </Interior> </NamedStyle> Pattern Description The Pattern element defines a pattern used to fill an area. Context Table 16: Context on page 98 lists the elements that can contain, or be contained by, a Pattern element. 97

98 Using Styles Table 16: Context Contained by Element Contains Interior or Defs Pattern Bitmap Attributes Table 17: Attributes on page 98 lists the attributes of a Pattern element. Table 17: Attributes Attribute Description id A unique identifier for the element. Note: This attribute is required. name A descriptive name for the element. Example This example specifies a solid fill pattern. <?xml version="1.0" encoding="utf-8"?> <NamedStyle version="mxp_workspace_1_5" xmlns=" <Interior fill-opacity="1" fill="(#id7)"> <Defs> <Pattern id="id7"> <Bitmap uri="mapinfo:brush 2"> <ColorAdjustmentSet> <ColorAdjustment color-1="nonwhite" color-2="rgb(224,255,176)" opacity="1"/> <ColorAdjustment color-1="white" color-2="white" opacity="1"/> </ColorAdjustmentSet> </Bitmap> </Pattern> 98

99 Using Styles </Defs> </Interior> </NamedStyle> Bitmap Description The Bitmap element specifies a particular bitmap image, and the image's width and height. Context Table 18: Context on page 99 lists the elements that can contain, or be contained by, a Bitmap element. Table 18: Context Contained by Element Contains Pattern or PointStyle Bitmap ColorAdjustmentSet Attributes Table 19: Attributes on page 99 lists the attributes of a Bitmap element. Table 19: Attributes Attribute Description id A unique identifier for the element. name A descriptive name for the element. uri Any of the following: A network protocol, and the network location of a bitmap image to fetch using that protocol. The available protocols are: ftp, http, file, or the URI scheme name of a custom protocol. A reference to a brush in the mapinfo codespace, which specifies a fill pattern code. For example: mapinfo:brush 71. The available fill patterns, and corresponding pattern codes, are shown in Fill Pattern Codes on page

100 Using Styles Attribute Description The filename of a bitmap image. The image file must be contained in a JAR file that is in the CLASSPATH. If the image file is located in the top-level internal directory of the JAR file, then the attribute value is the image filename only. If the image file is located in a lower-level internal directory in the JAR file, then the attribute value is the internal path to the image file within the JAR file, with a forward slash used to separate each directory level. Note that in either case, you do not use a forward slash at the beginning of the attribute value. height A floating-point value specifying with height of the bitmap image. Alternatively, the special value native can be used to specify the native height of the bitmap image. width A floating-point value specifying with width of the bitmap image. Alternatively, the special value native can be used to specify the native width of the bitmap image. unit A reference to an imagesize in the mapinfo codespace, which specifies a unit. The unit attribute is optional. The default value is mapinfo:imagesize pixel. Example This example uses a reference to a brush in the mapinfo codespace to specify a solid fill pattern. <?xml version="1.0" encoding="utf-8"?> <NamedStyle version="mxp_workspace_1_5" xmlns=" <Interior fill-opacity="1" fill="(#id7)"> <Defs> <Pattern id="id7"> <Bitmap uri="mapinfo:brush 2"> <ColorAdjustmentSet> <ColorAdjustment color-1="nonwhite" color-2="rgb(224,255,176)" opacity="1"/> <ColorAdjustment color-1="white" color-2="white" opacity="1"/> </ColorAdjustmentSet> </Bitmap> </Pattern> </Defs> 100

101 Using Styles </Interior> </NamedStyle> ColorAdjustmentSet Description The ColorAdjustmentSet element serves as a container for one or more ColorAdjustment elements. Context Table 20: Context on page 101 lists the elements that can contain, or be contained by, a ColorAdjustmentSet element. Table 20: Context Contained by Element Contains Bitmap ColorAdjustmentSet ColorAdjustment Attributes The ColorAdjustmentSet element has no attributes. Example This example shows a ColorAdjustmentSet element that contains two ColorAdjustment elements. <?xml version="1.0" encoding="utf-8"?> <NamedStyle version="mxp_workspace_1_5" xmlns=" <Interior fill-opacity="1" fill="(#id7)"> <Defs> <Pattern id="id7"> <Bitmap uri="mapinfo:brush 2"> <ColorAdjustmentSet> <ColorAdjustment color-1="nonwhite" color-2="rgb(224,255,176)" opacity="1"/> 101

102 Using Styles <ColorAdjustment color-1="white" color-2="white" opacity="1"/> </ColorAdjustmentSet> </Bitmap> </Pattern> </Defs> </Interior> </NamedStyle> ColorAdjustment Description The ColorAdjustment element replaces color-1 with color-2 at the given opacity. If color-2 is absent, the only effect is to change the opacity of color-1. If opacity is absent, the effect is to change color-1 to color-2 and retain the opacity. If both color-2 and opacity are absent, this element has no effect. Context Table 21: Context on page 102 lists the elements that can contain, or be contained by, a ColorAdjustment element. Table 21: Context Contained by Element Contains ColorAdjustmentSet ColorAdjustment (empty) Attributes Table 22: Attributes on page 102 lists the attributes of a ColorAdjustment element. Table 22: Attributes Attribute Description color-1 A string value specifying the color to be changed to the value of color-2, or whose opacity is to be changed to the value of opacity. 102

103 Using Styles Attribute Description The value can be any valid CSS color. (See Alternatively, the special value nonwhite can be used to specify every color except white (rgb(255,255,255)). Note: This attribute is required. color-2 A string value specifying the color to which color-1 is to be changed. The value can be any valid CSS color. (See opacity A floating-point value from 0 to 1 specifying opacity to which color-1 is to be changed. Example This example changes all colors that are not white to light green at full opacity. <?xml version="1.0" encoding="utf-8"?> <NamedStyle version="mxp_workspace_1_5" xmlns=" <Interior fill-opacity="1" fill="(#id7)"> <Defs> <Pattern id="id7"> <Bitmap uri="mapinfo:brush 2"> <ColorAdjustmentSet> <ColorAdjustment color-1="nonwhite" color-2="rgb(224,255,176)" opacity="1"/> </ColorAdjustmentSet> </Bitmap> </Pattern> </Defs> </Interior> </NamedStyle> Point Styles A point style specifies the visual characteristics of a point. 103

104 Using Styles PointStyle Description A PointStyle element defines a style for a point geometry. Context Table 23: Context on page 104 lists the elements that can contain, or be contained by, a PointStyle element. Table 23: Context Contained by Element Contains NamedStyle or CompositeStyle PointStyle Bitmap or FontSymbol Attributes Table 24: Attributes on page 104 lists the attributes of a PointStyle element. Table 24: Attributes Attribute Description id A unique identifier for the element. name A descriptive name for the element. Examples This example specifies an 18-point red push-pin symbol from the MapInfo 3.0 Symbols set. Note that the text attribute is set to C, which is decimal code 67 in the UTF-8 encoding, and the family attribute is set to MapInfo Symbols, which specifies the MapInfo 3.0 Symbols set. In the MapInfo 3.0 Symbols set, code 67 specifies a push-pin symbol. <?xml version="1.0" encoding="utf-8"?> <NamedStyle version="mxp_workspace_1_5" xmlns=" 104

105 Using Styles <PointStyle> <FontSymbol size="18" size-unit="mapinfo:length pt" stroke="red" stroke-opacity="1" text="c" family="mapinfo Symbols"/> </PointStyle> </NamedStyle> This example specifies a 14-point blue star symbol from the MapInfo 3.0 Symbols set. Note that the text attribute is set to #, which is decimal code 35 in the UTF-8 encoding, and the family attribute is set to MapInfo Symbols, which specifies the MapInfo 3.0 Symbols set. In the MapInfo 3.0 Symbols set, code 35 specifies a star symbol. <?xml version="1.0" encoding="utf-8"?> <NamedStyle version="mxp_workspace_1_5" xmlns=" <PointStyle> <FontSymbol size="14" size-unit="mapinfo:length pt" stroke="blue" stroke-opacity="1" text="#" family="mapinfo Symbols"/> </PointStyle> </NamedStyle> Font Styles A font style specifies the visual characteristics of a string of text. FontStyle Description The FontStyle element defines a style for a text string. 105

106 Using Styles Context Table 25: Context on page 106 lists the elements that can contain, or be contained by, a FontStyle element. Table 25: Context Contained by Element Contains NamedStyle or CompositeStyle FontStyle (empty) Attributes Table 26: Attributes on page 106 lists the attributes of a FontStyle element. Table 26: Attributes Attribute Description id A unique identifier for the element. name A descriptive name for the element. family A string value specifying the name of a TrueType font. The family attribute is optional. The default value is arial. size A floating-point value specifying the font size. The size attribute is optional. The default value is 12. size-unit A reference to a length in the mapinfo codespace, which specifies the unit of measurement used for the size attribute. The size-unit attribute is optional. The default value is mapinfo:length pt. stroke A string value specifying the color of the font. The value can be any valid CSS color. (See The stroke attribute is optional. The default value is black. 106

107 Using Styles Attribute Description stroke-opacity A floating-point value from 0 to 1 specifying the opacity of the font. A value of 0 means that the font is totally transparent. A value of 1 means that the font is totally opaque. A value of 0.5 means that the font is 50% translucent. The stroke-opacity attribute is optional. The default value is 1. font-style An enumeration value specifying the font style. Possible values are: normal italic oblique The font-style attribute is optional. The default value is normal. effect A string value specifying the color of the text effect provided by the effect-type attribute. The value can be any valid CSS color. (See The effect attribute is optional. The default value is none. effect-opacity A floating-point value from 0 to 1 specifying the opacity of the text effect. A value of 0 means that the effect is totally transparent. A value of 1 means that the effect is totally opaque. A value of 0.5 means that the effect is 50% translucent. The effect-opacity attribute is optional. The default value is 1. effect-type An enumeration value specifying the text effect type. Possible values are: box halo glyph-outline none The effect-type attribute is optional. The default value is none. font-weight An enumeration value specifying the font weight. Possible values are: normal bold

108 Using Styles Attribute Description Note: normal is equivalent to 200; bold is equivalent to 400. The font-weight attribute is optional. The default value is normal. text-decoration A string value specifying the text decoration. The value must have the following pattern: a choice of one or more of (underline line-through) separated by a single space or the single value none. Examples: line-through underline, underline, none. The text-decoration attribute is optional. The default value is none. text-case An enumeration value specifying the text case. Possible values are: upper lower default Note: default means 'retain the current case'. The text-case attribute is optional. The default value is default. shadow A boolean value (true or false) specifying whether to have a drop-shadow drawn behind the font. A value of false (the default) specifies no drop-shadow. The shadow attribute is optional. The default value is false. expand A boolean value (true or false) specifying whether a space character should be inserted between each pair of visible characters in the text string. The expand attribute is optional. The default value is false. 108

109 Using Styles Example This example specifies a 12-point black sans serif font. <?xml version="1.0" encoding="utf-8"?> <NamedStyle version="mxp_workspace_1_5" xmlns=" <FontStyle family="microsoft Sans Serif" font-style="normal" effect="white" effect-opacity="1" effect-type="none" font-weight="normal" text-decoration="none" text-case="default" shadow="false" expand="false" size="12" size-unit="mapinfo:length pt" stroke="black"/> </NamedStyle> Symbol Styles A symbol style specifies the visual characteristics of a symbol. FontSymbol Description The FontSymbol element defines a style for a font symbol. Context Table 27: Context on page 109 lists the elements that can contain, or be contained by, a FontSymbol element. Table 27: Context Contained by Element Contains NamedStyle or PointStyle FontSymbol (empty) 109

110 Using Styles Attributes Table 28: Attributes on page 110 lists the attributes of a FontSymbol element. Table 28: Attributes Attribute Description id A unique identifier for the element. name A descriptive name for the element. text A one-character string value specifying the symbol character to use. If the family attribute is set to the name of a TrueType font, set this attribute to the character for the font symbol. If the family attribute is set to MapInfo 3.0 Compatible or MapInfo Symbols, refer to the set of symbols and symbol codes shown in MapInfo 3.0 Symbol Codes on page 133. family Either of the following: A string value specifying the name of a TrueType symbol font (for example, "WingDings"). The string value MapInfo 3.0 Compatible or MapInfo Symbols, specifying the symbols shown in MapInfo 3.0 Symbol Codes on page 133. The family attribute is optional. The default value is arial. size A floating-point value specifying the size of the symbol. The size attribute is optional. The default value is 12. size-unit A reference to a length in the mapinfo codespace, which specifies the unit of measurement used for the size attribute. The size-unit attribute is optional. The default value is mapinfo:length pt. stroke A string value specifying the color of the symbol. The value can be any valid CSS color. (See The stroke attribute is optional. The default value is black. 110

111 Using Styles Attribute Description stroke-opacity A floating-point value from 0 to 1 specifying the opacity of the symbol. A value of 0 means that the symbol is totally transparent. A value of 1 means that the symbol is totally opaque. A value of 0.5 means that the symbol is 50% translucent. The stroke-opacity attribute is optional. The default value is 1. font-style An enumeration value specifying the font style. Possible values are: normal italic oblique The font-style attribute is optional. The default value is normal. effect A string value specifying the color of the text effect provided by the effect-type attribute. The value can be any valid CSS color. (See The effect attribute is optional. The default value is none. effect-opacity A floating-point value from 0 to 1 specifying the opacity of the text effect. A value of 0 means that the effect is totally transparent. A value of 1 means that the effect is totally opaque. A value of 0.5 means that the effect is 50% translucent. The effect-opacity attribute is optional. The default value is 1. effect-type An enumeration value specifying the text effect type. Possible values are: box halo glyph-outline none The effect-type attribute is optional. The default value is none. font-weight An enumeration value specifying the font weight. Possible values are: normal bold

112 Using Styles Attribute Description Note: normal is equivalent to 200; bold is equivalent to 400. The font-weight attribute is optional. The default value is normal. text-decoration A string value specifying the text decoration. The value must have the following pattern: a choice of one or more of (underline line-through) separated by a single space or the single value none. Examples: line-through underline, underline, none. The text-decoration attribute is optional. The default value is none. text-case An enumeration value specifying the text case. Possible values are: upper lower default Note: default means 'retain the current case'. The text-case attribute is optional. The default value is default. shadow A boolean value (true or false) specifying whether to have a drop-shadow drawn behind the symbol. A value of false (the default) specifies no drop-shadow. The shadow attribute is optional. The default value is false. expand A boolean value (true or false) specifying whether a space character should be inserted between each pair of visible characters in the text string. The expand attribute is optional. The default value is false. 112

113 Using Styles Attribute Description angle A floating-point value specifying the rotation angle of the symbol. angle-unit A string value specifying the unit of measurement used for the angle attribute. Examples This example specifies an 18-point red push-pin symbol from the MapInfo 3.0 Symbols set. Note that the text attribute is set to C, which is decimal code 67 in the UTF-8 encoding, and the family attribute is set to MapInfo Symbols, which specifies the MapInfo 3.0 Symbols set. In the MapInfo 3.0 Symbols set, code 67 specifies a push-pin symbol. <?xml version="1.0" encoding="utf-8"?> <NamedStyle version="mxp_workspace_1_5" xmlns=" <FontSymbol size="18" size-unit="mapinfo:length pt" stroke="red" stroke-opacity="1" text="c" family="mapinfo Symbols"/> </NamedStyle> This example specifies a 14-point blue star symbol from the MapInfo 3.0 Symbols set. Note that the text attribute is set to #, which is decimal code 35 in the UTF-8 encoding, and the family attribute is set to MapInfo Symbols, which specifies the MapInfo 3.0 Symbols set. In the MapInfo 3.0 Symbols set, code 35 specifies a star symbol. <?xml version="1.0" encoding="utf-8"?> <NamedStyle version="mxp_workspace_1_5" xmlns=" <FontSymbol size="14" size-unit="mapinfo:length pt" stroke="blue" stroke-opacity="1" 113

114 Using Styles text="#" family="mapinfo Symbols"/> </NamedStyle> Image Styles An image style specifies the visual characteristics of an image. RasterStyle Description A RasterStyle element defines a style for a raster image. Context Table 29: Context on page 114 lists the elements that can contain, or be contained by, a RasterStyle element. Table 29: Context Contained by Element Contains NamedStyle or CompositeStyle RasterStyle (empty) Attributes Table 30: Attributes on page 114 lists the attributes of a RasterStyle element. Table 30: Attributes Attribute Description id A unique identifier for the element. name A descriptive name for the element. contrast A floating-point value from 0 to 1 specifying the contrast of the image. A value of 0 means that the image has minimum contrast. A value of 1 means that the image has maximum contrast. A value of 0.5 means that the image has 50% contrast. 114

115 Using Styles Attribute Description The contrast attribute is optional. The default value is 0.5. brightness A floating-point value from 0 to 1 specifying the brightness of the image. Brightness is a measure of the lightness of darkness of the image. A value of 0 means that the image has minimum brightness. A value of 1 means that the image has maximum brightness. A value of 0.5 means that the image has 50% brightness. The brightness attribute is optional. The default value is 0.5. opacity A floating-point value from 0 to 1 specifying the opacity of the image. A value of 0 means that the image is totally transparent. A value of 1 means that the image is totally opaque. A value of 0.5 means that the image is 50% translucent. The opacity attribute is optional. The default value is 1. grayscale A boolean value (true or false) specifying whether the image should be displayed using only shades of gray, ranging from white to black. The grayscale attribute is optional. The default value is false. transparent A boolean value (true or false) specifying whether the color identified by transparent-color should be displayed with an opacity of 0 (transparent). The transparent attribute is optional. The default value is false. transparent-color A string value specifying the color to be displayed with an opacity of 0 if transparent is set to true. The value can be any valid CSS color. (See The default color is black. Example This example specifies a raster image style that sets any red areas to transparent. <?xml version="1.0" encoding="utf-8"?> <NamedStyle version="mxp_workspace_1_5" xmlns=" <RasterStyle 115

116 Using Styles id="mirasterstyle" name="mirasterstyle" contrast="0.5" brightness="0.5" opacity="1" grayscale="false" transparent="true" transparent-color="red"/> </NamedStyle> GridStyle Description A GridStyle element defines a style for a MapInfo grid image. Context Table 31: Context on page 116 lists the elements that can contain, or be contained by, a GridStyle element. Table 31: Context Contained by Element Contains NamedStyle or CompositeStyle GridStyle GridInflectionList Attributes Table 32: Attributes on page 116 lists the attributes of a GridStyle element. Table 32: Attributes Attribute Description id A unique identifier for the element. name A descriptive name for the element. contrast A floating-point value from 0 to 1 specifying the contrast of the image. 116

117 Using Styles Attribute Description A value of 0 means that the image has minimum contrast. A value of 1 means that the image has maximum contrast. A value of 0.5 means that the image has 50% contrast. The contrast attribute is optional. The default value is 0.5. brightness A floating-point value from 0 to 1 specifying the brightness of the image. Brightness is a measure of the lightness or darkness of the image. A value of 0 means that the image has minimum brightness. A value of 1 means that the image has maximum brightness. A value of 0.5 means that the image has 50% brightness. The brightness attribute is optional. The default value is 0.5. opacity A floating-point value from 0 to 1 specifying the opacity of the image. A value of 0 means that the image is totally transparent. A value of 1 means that the image is totally opaque. A value of 0.5 means that the image is 50% translucent. The opacity attribute is optional. The default value is 1. grayscale A boolean value (true or false) specifying whether the image should be displayed using only shades of gray, ranging from white to black. The grayscale attribute is optional. The default value is false. show-hillshade A boolean value (true or false) specifying whether to display the grid image with relief shading in order to provide a more 3D appearance. The show-hillshade attribute is optional. The default value is false. null-color A string value specifying the color used to indicate that a value is null. The value can be any valid CSS color. (See The null-color attribute is optional. The default value is black. Note: This attribute has no effect if null-transparent is true. null-transparent A boolean value (true or false) specifying whether null values should be displayed as transparent (true) or displayed as the color specified in null-color (false). The null-transparent attribute is optional. The default value is false. 117

118 Using Styles Example This example specifies a grid image style that contains a collection of three grid inflection points. <?xml version="1.0" encoding="utf-8"?> <NamedStyle version="mxp_workspace_1_5" xmlns=" <GridStyle id="migridstyle" name="migridstyle" contrast="0.5" brightness="0.5" opacity="1" grayscale="false" show-hillshade="false" null-color="black" null-transparent="true"/> <GridInflectionList> <GridInflection value="0.4" color="yellow"/> <GridInflection value="0.5" color="green"/> <GridInflection value="0.6" color="blue"/> </GridInflectionList> </GridStyle> </NamedStyle> GridInflectionList Description A GridInflectionList element defines an ordered collection of inflection points (as defined by a series of zero or more GridInflection elements) used to interpret a Grid file. The contained collection of GridInflection elements must be ordered in ascending order of the value attribute. A value in the data that lies between two GridInflections will have its color determined by blending the colors at the two inflection points. Context Table 33: Context on page 119 lists the elements that can contain, or be contained by, a GridInflectionList element. 118

119 Using Styles Table 33: Context Contained by Element Contains GridStyle GridInflectionList GridInflection Attributes The GridInflectionList element has no attributes. Example This example specifies a grid image style that contains a collection of three grid inflection points. <?xml version="1.0" encoding="utf-8"?> <NamedStyle version="mxp_workspace_1_5" xmlns=" <GridStyle id="migridstyle" name="migridstyle" contrast="0.5" brightness="0.5" opacity="1" grayscale="false" show-hillshade="false" null-color="black" null-transparent="true"/> <GridInflectionList> <GridInflection value="0.4" color="yellow"/> <GridInflection value="0.5" color="green"/> <GridInflection value="0.6" color="blue"/> </GridInflectionList> </GridStyle> </NamedStyle> 119

120 Using Styles GridInflection Description A GridInflection element defines a style for a grid inflection point. A grid inflection point indicates that a cell with the specified value should be rendered with the specified color. Context Table 34: Context on page 120 lists the elements that can contain, or be contained by, a GridInflection element. Table 34: Context Contained by Element Contains GridInflectionList GridInflection (empty) Attributes Table 35: Attributes on page 120 lists the attributes of a GridInflection element. Table 35: Attributes Attribute Description value A floating-point value specifying the value of the grid inflection point. Note: This attribute is required. color A string value specifying the color of the grid inflection point. The value can be any valid CSS color. (See Note: This attribute is required. Example This example specifies a grid image style that contains a collection of three grid inflection points. <?xml version="1.0" encoding="utf-8"?> <NamedStyle 120

121 Using Styles version="mxp_workspace_1_5" xmlns=" <GridStyle id="migridstyle" name="migridstyle" contrast="0.5" brightness="0.5" opacity="1" grayscale="false" show-hillshade="false" null-color="black" null-transparent="true"/> <GridInflectionList> <GridInflection value="0.4" color="yellow"/> <GridInflection value="0.5" color="green"/> <GridInflection value="0.6" color="blue"/> </GridInflectionList> </GridStyle> </NamedStyle> Composite Styles A composite style specifies the visual characteristics of a set of other geometry types such as lines and areas. MapinfoTextObjectStyle Description A MapinfoTextObjectStyle element defines a composite style for a legacy MapInfo text object. Legacy MapInfo text objects can be defined only in a MapInfo native data file, also known as a TAB file. A MapinfoTextObjectStyle element contains styles for the text content (defined by a FontStyle element) and the optional callout line (defined by an LineStyle element). Context Table 36: Context on page 122 lists the elements that can contain, or be contained by, a MapinfoTextObjectStyle element. 121

122 Using Styles Table 36: Context Contained by Element Contains NamedStyle or CompositeStyle MapinfoTextObjectStyle FontStyle and LineStyle Attributes Table 37: Attributes on page 122 lists the attributes of a MapinfoTextObjectStyle element. Table 37: Attributes Attribute Description id A unique identifier for the element. name A descriptive name for the element. Example This example specifies a 12-point sans serif font for the text content, and 1-pixel black line for the callout line. <?xml version="1.0" encoding="utf-8"?> <NamedStyle version="mxp_workspace_1_5" xmlns=" <MapinfoTextObjectStyle> <FontStyle family="microsoft Sans Serif" font-style="normal" effect="white" effect-opacity="1" effect-type="none" font-weight="normal" text-decoration="none" text-case="default" shadow="false" expand="false" size="12" size-unit="mapinfo:length pt" stroke="black"/> <LineStyle 122

123 Using Styles stroke="black" stroke-opacity="1" width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 2</Pen> </LineStyle> </MapinfoTextObjectStyle> </NamedStyle> AreaStyle Description An AreaStyle element defines a composite style comprising a line style (as defined by a LineStyle element) and a fill style (as defined by an Interior element). Context Table 38: Context on page 123 lists the elements that can contain, or be contained by, an AreaStyle element. Table 38: Context Contained by Element Contains NamedStyle or CompositeStyle AreaStyle LineStyle and Interior Attributes Table 39: Attributes on page 123 lists the attributes of an AreaStyle element. Table 39: Attributes Attribute Description id A unique identifier for the element. name A descriptive name for the element. 123

124 Using Styles Example This example specifies an area filled with a solid light green color, bounded by a 1-pixel dashed black line. <?xml version="1.0" encoding="utf-8"?> <NamedStyle version="mxp_workspace_1_5" xmlns=" xmlns:gml=" <AreaStyle> <LineStyle width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 9</Pen> </LineStyle> <Interior fill-opacity="1" fill="(#id7)"> <Defs> <Pattern id="id7"> <Bitmap uri="mapinfo:brush 2"> <ColorAdjustmentSet> <ColorAdjustment color-1="nonwhite" color-2="rgb(224,255,176)" opacity="1"/> <ColorAdjustment color-1="white" color-2="white" opacity="1"/> </ColorAdjustmentSet> </Bitmap> </Pattern> </Defs> </Interior> </AreaStyle> </NamedStyle> CompositeStyle Description A CompositeStyle element defines a composite style that comprises zero or one of each of the following: AreaStyle, LineStyle, RasterStyle, FontStyle, GridStyle, PointStyle, and MapinfoTextObjectStyle. 124

125 Using Styles Context Table 40: Context on page 125 lists the elements that can contain, or be contained by, a CompositeStyle element. Table 40: Context Contained by Element Contains NamedStyle CompositeStyle Zero or one of each of the following: AreaStyle LineStyle RasterStyle FontStyle GridStyle PointStyle MapinfoTextObjectStyle Attributes Table 41: Attributes on page 125 lists the attributes of a CompositeStyle element. Table 41: Attributes Attribute Description id A unique identifier for the element. name A descriptive name for the element. Example This example specifies a composite style that has these features: An area filled with a solid light green color, bounded by a 1-pixel dashed black line. A 12-point sans serif font for the text content, and 1-pixel black line for the callout line. <?xml version="1.0" encoding="utf-8"?> <NamedStyle version="mxp_workspace_1_5" xmlns=" 125

126 Using Styles xmlns:gml=" <CompositeStyle> <AreaStyle> <LineStyle width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 9</Pen> </LineStyle> <Interior fill-opacity="1" fill="(#id7)"> <Defs> <Pattern id="id7"> <Bitmap uri="mapinfo:brush 2"> <ColorAdjustmentSet> <ColorAdjustment color-1="nonwhite" color-2="rgb(224,255,176)" opacity="1"/> <ColorAdjustment color-1="white" color-2="white" opacity="1"/> </ColorAdjustmentSet> </Bitmap> </Pattern> </Defs> </Interior> </AreaStyle> <MapinfoTextObjectStyle> <FontStyle family="microsoft Sans Serif" font-style="normal" effect="white" effect-opacity="1" effect-type="none" font-weight="normal" text-decoration="none" text-case="default" shadow="false" expand="false" size="12" size-unit="mapinfo:length pt" stroke="black"/> <LineStyle stroke="black" stroke-opacity="1" width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 2</Pen> </LineStyle> </MapinfoTextObjectStyle> </CompositeStyle> </NamedStyle> 126

127 Using Styles GridStyle GridStyle is a Style that takes a list of inflections for a GridLayer. Each inflection is made up of a value, color, and optionally, a description. SOAP Example The following SOAP request creates a map with a GridLayer that is styled according to the GridStyle (the color and value for each inflection is provided in an inflection list). package com.pb; import com.mapinfo.midev.service.mappingcommon.v1.aggregationmethod; import com.mapinfo.midev.service.units.v1.distance; import com.mapinfo.midev.service.units.v1.distanceunit; import com.mapinfo.midev.service.mapping.v1.gridlayer; import com.mapinfo.midev.service.mappingcommon.v1.idwinterpolator; import com.mapinfo.midev.service.mapping.v1.map; import com.mapinfo.midev.service.mapping.v1.mapimage; import com.mapinfo.midev.service.mapping.ws.v1.mappingservice; import com.mapinfo.midev.service.mapping.ws.v1.mappingserviceinterface; import com.mapinfo.midev.service.table.v1.namedtable; import com.mapinfo.midev.service.geometries.v1.point; import com.mapinfo.midev.service.geometries.v1.pos; import com.mapinfo.midev.service.mapping.v1.rendermaprequest; import com.mapinfo.midev.service.mapping.v1.rendermapresponse; import com.mapinfo.midev.service.mapping.ws.v1.serviceexception; import com.mapinfo.midev.service.mapping.v1.zoomandcentermapview; import com.mapinfo.midev.service.style.v1.gridstyle; import com.mapinfo.midev.service.style.v1.inflection; import com.mapinfo.midev.service.style.v1.inflectionlisttype; import javax.xml.ws.bindingprovider; import java.io.file; import java.io.fileoutputstream; import java.io.ioexception; import java.io.outputstream; import java.util.list; public final class GridStyleInflectionExample { private static final File DESTINATION_PATH = new File("c:/temp/GridStyleInflectionExample.png"); // where the map image will be saved private static final String MIME_TYPE = "image/png"; // MIME type of the map image private static final String STATE_CAP_TABLE_NAME = 127

128 Using Styles "/Samples/NamedTables/USA_CAPS"; private static final String USERNAME = "admin"; access the Mapping Service private static final String PASSWORD = "admin"; access the Mapping Service // the username to // the password to public static void main(string[] args) throws ServiceException, IOException { MappingService mappingservice = new MappingService(); MappingServiceInterface mappingserviceinterface = mappingservice.getmappingserviceinterface(); // set credentials to access the service java.util.map<string, Object> requestcontext = ((BindingProvider) mappingserviceinterface).getrequestcontext(); requestcontext.put(bindingprovider.username_property, USERNAME); requestcontext.put(bindingprovider.password_property, PASSWORD); RenderMapRequest rendermaprequest = new RenderMapRequest(); GridLayer gridlayer = new GridLayer(); { NamedTable statecaptable = new NamedTable(); statecaptable.setname(state_cap_table_name); gridlayer.settable(statecaptable); } { InflectionListType inflectionlisttype = new InflectionListType(); List<Inflection> inflections = inflectionlisttype.getinflection(); Inflection inflection; inflection = new Inflection(); inflection.setvalue(5000); inflection.setcolor("yellow"); inflections.add(inflection); inflection = new Inflection(); inflection.setvalue(20000); inflection.setcolor("green"); inflections.add(inflection); inflection = new Inflection(); inflection.setvalue(50000); inflection.setcolor("blue"); inflections.add(inflection); inflection = new Inflection(); inflection.setvalue(100000); 128

129 Using Styles inflection.setcolor("red"); inflections.add(inflection); inflection = new Inflection(); inflection.setvalue(200000); inflection.setcolor("white"); inflections.add(inflection); GridStyle gridstyle = new GridStyle(); gridstyle.setinflectionlist(inflectionlisttype); gridlayer.setstyle(gridstyle); } { Distance cellwidth = new Distance(); cellwidth.setvalue(18.1); cellwidth.setuom(distanceunit.mile); gridlayer.setcellwidth(cellwidth); } gridlayer.setvalueexpression("pop_1990"); gridlayer.setspatialexpression("obj"); { IDWInterpolator interpolator = new IDWInterpolator(); interpolator.setsearchradius(1810); interpolator.setexponent(2); interpolator.setmaxpoints(20); interpolator.setaggregationmethod(aggregationmethod.average); gridlayer.setinterpolator(interpolator); } { Map map = new Map(); map.getlayer().add(gridlayer); rendermaprequest.setmap(map); } { ZoomAndCenterMapView mapview = new ZoomAndCenterMapView(); Point center = new Point(); center.setsrsname("epsg:4267"); Pos pos = new Pos(); pos.setx(-97); pos.sety(36); center.setpos(pos); mapview.setmapcenter(center); Distance zoom = new Distance(); zoom.setvalue(3350); zoom.setuom(distanceunit.mile); mapview.setzoomlevel(zoom); 129

130 Using Styles mapview.setwidth(800); mapview.setheight(600); rendermaprequest.setmapview(mapview); } { rendermaprequest.setimagemimetype(mime_type); } rendermaprequest.setreturnimage(true); RenderMapResponse rendermapresponse = mappingserviceinterface.rendermap(rendermaprequest); MapImage mapimage = rendermapresponse.getmapimage(); byte[] imagepng = mapimage.getimage(); } } OutputStream os = new FileOutputStream(DESTINATION_PATH); os.write(imagepng); os.close(); REST Example The following is the JSON object that describes the GridStyle InflectionList for a REST request. { "inflectionlist": { "inflection": [{ "color": "yellow", "description": "", "value": 5000 }, { "color": "green", "description": "", "value": }, { "color": "blue", "description": "", "value": }, { "color": "red", 130

131 Using Styles "description": "", "value": }, { "color": "white", "description": "", "value": }] } } Pattern Codes Pattern codes enable you to specify which line and fill patterns you want to be displayed in a map. Line Pattern Codes The following figure shows the line patterns, and corresponding pattern codes, available in Spectrum Technology Platform. Note: Pattern 1 is invisible. 131

132 Using Styles Fill Pattern Codes The following figure shows the fill patterns, and corresponding pattern codes, available in Spectrum Technology Platform. 132

133 Using Styles Symbol Codes Symbol codes enable you to specify which symbols you want to be displayed in a map. MapInfo 3.0 Symbol Codes The following figure shows the symbols, and corresponding symbol codes, available in the MapInfo 3.0 symbol set. Note: Symbol 31 is an invisible symbol. 133

134 Using Styles MapBasic Font Symbol Codes The following figures show the various MapBasic font symbol set available, and corresponding symbol codes. MapInfo Symbols MapInfo Arrows MapInfo Cartographic 134

135 Using Styles MapInfo Miscellaneous MapInfo OilandGas MapInfo RealEstate 135

136 Using Styles MapInfo Shields MapInfo Transportation MapInfo Weather 136

137 7 - Rasters and Grids This section provides information on how to use raster and grid images in Spectrum Technology Platform. Raster images are useful in mapping to provide additional context and reference information.grid images, which are a special type of raster, show a color gradation over an area representing the interpolation of data points. Raster images are typically used as a base layer in a map, while grid layers are used as overlays, on top of other layers. For example, aerial photographs that show real-world detail such as buildings, refineries, and vegetation are well-suited as base layers for a map. Scanned paper maps are another example of a raster image. Use a raster image as a base layer and overlay vector data such as street networks, point locations representing customers, and postal boundaries, to create useful and visually appealing maps. Raster and grid images used in Spectrum Technology Platform must be registered so that known geographic points on the image coincide with the same features on the vector data. Additionally, company logos and other art you wish to display must be registered to some location on earth, even though they are not true georeferenced data. Many raster images available today come with a registration file in MapInfo TAB format. To register a raster image, bring it into MapInfo Professional and register it there. Grid images can be created in MapInfo Professional. as well. In this section Supported Capabilities for Rasters and Grids 138 Using Rasters and Grids 140

138 Rasters and Grids Supported Capabilities for Rasters and Grids The following raster and grid capabilities are supported in Spectrum Technology Platform. Raster and grid images can be part of a map rendering request to the Mapping, Map Tiling, or WMS services. The metadata associated with rasters and grids can be queried via the Feature Service, WFS and CSW services. Map Projection A map including a raster or grid layer is projected using the coordinate system of the raster or grid image. Raster images are not reprojected to match the other layers in a map. Legend Support Responses containing raster and grid images can return legend information in a rendering request. The swatch that represents the raster layer displays a generic raster icon. For a grid layer, the inflection color is returned. See also Add a Legend to Your Map on page 156. Styles Raster or grid styles are supported as override themes on the named layer. Supported styles for raster include: grayscale, brightness, contrast, opacity and transparency color. Named styles that resolve to a Grid style can include an inflection color list. GridStyle that is of type Style takes a pre-calculated inflection list only at this time. Override Themes Raster images can include an override theme provided the theme is part of the named layer definition. Override themes are used to change the display of the raster or grid, such as brightness, contrast, transparency. In the case of grid, the inflection list can be overridden. The theme style of the override is defined as an MWS raster or grid style. Overlay Support Grid images can be used as an overlay in a named map. Raster images cannot. The grid image is contained in a GridLayer where the style, interpolation mode, bounds and points table are queryable. Supported Raster Formats The following raster and grid formats (64-bit only) are supported in Spectrum Technology Platform. Raster formats: 138

139 Rasters and Grids Format GIF PNG JPEG BMP TIFF GeoTiff Paint Targa Windows Metafile ECW (SDK v5) MrSID (SDK v9) Note: Supports MG4 (MrSID Generation 4) ADRG CADRG CIB NITF File Extension.gif.png.jpg/.jpeg.bmp,.wbmp.tif.geotif.pcx.tga.wmf,.emf.ecw.sid.gen.gen various.ntf Note: Solaris or AIX machines, whether installed with 32- or 64- bit JVM, do not support ECW and MrSID raster formats. Grid Formats Format MapInfo Grid Vertical Mapper Continuous Grid Vertical Mapper Classified Grid Defense Digital Terrain Elevation Data (DTED) File Extension.mig.grd.grc.dt0,.dt1,.dt2,.dt3 In order to use rasters and grids as a map layer, there must be an associated.tab file containing georeference information about the image, including the bounds, coordinate system and registration points. 139

140 Rasters and Grids Using Rasters and Grids Raster and grid images can be included in a named map that can be rendered via the Mapping Service or queried for its metadata via the Feature Service. This is done by creating a named layer or named table for the raster or grid, just as you would do for a vector layer. The overall process of using raster and grid images in Spectrum Technology Platform is to create the image as a named table or named layer and include it in a named map definition. Use either SOAP or REST to render the map or retrieve metadata about the image. Grid Layer Overlay Example The following code shows how to create a GridLayer overlay and use it in a request for a named map. Note the use of the CustomInflectionCollection whereby the colors are specified for each inflection. Alternatively you can use a ComputedInflectionCollection with a start and end color and number of inflections. The color is spread evenly across the number of inflections. For an explanation of the GridLayer elements, see GridLayer Elements. public class RenderNamedMapWithGridLayerOverlay { public static void main(string[] args) { try { MappingServiceInterface mapping = Preference.getServiceinterface(); Point mapcenter = BuildGeometry.buildPoint("mapinfo:coordsys 12, 62, 7, 0.0", 0, 0, null); MapView mapview = MappingView.getZoomAndCenterMapView(mapCenter,MappingUtility.buildDistance(19000, DistanceUnit.KILOMETER)); NamedTable namedtable = new NamedTable(); namedtable.setname("/samples/namedtables/worldcaptable"); Distance cellwidth = MappingUtility.buildDistance(50, DistanceUnit.MILE); IDWInterpolator interpolator = new IDWInterpolator(); interpolator.setaggregationmethod(aggregationmethod.average); interpolator.setexponent(2); interpolator.setmaxpoints(25); interpolator.setsearchradius(100); 140

141 Rasters and Grids CustomInflectionCollection inflectioncollection = new CustomInflectionCollection(); inflectioncollection.setinflectionmethod(inflectionmethod.equal_count); inflectioncollection.setroundby(0.1); InflectionColorBinList inbinlist = new InflectionColorBinList(); InflectionColorBin red = new InflectionColorBin(); red.setcolor("red"); inbinlist.getinflectioncolorbin().add(red); InflectionColorBin yellow = new InflectionColorBin(); yellow.setcolor("yellow"); inbinlist.getinflectioncolorbin().add(yellow); InflectionColorBin green = new InflectionColorBin(); green.setcolor("green"); inbinlist.getinflectioncolorbin().add(green); InflectionColorBin rgb = new InflectionColorBin(); rgb.setcolor("rgb(0,255,255)"); inbinlist.getinflectioncolorbin().add(rgb); InflectionColorBin blue = new InflectionColorBin(); blue.setcolor("blue"); inbinlist.getinflectioncolorbin().add(blue); inflectioncollection.setinflectioncolorbinlist(inbinlist); //Creating GridEnvelope List<Pos> pointlist = new ArrayList<Pos>(2); pointlist.add(buildgeometry.buildpos( e7, , null)); pointlist.add(buildgeometry.buildpos( e7, , null)); Envelope gridenvelope = BuildGeometry.buildEnvelope("mapinfo:coordsys 12, 62, 7, 0.0", pointlist); //Creating GridLayer Layer gridlayer = MappingUtility.buildGridLayer(namedTable, null, cellwidth, "Cap_Pop", "Obj", interpolator, inflectioncollection, gridenvelope); RenderNamedMapWithOverlayRequest request = 141

142 Rasters and Grids MappingServiceRequestBuilder.createRenderNamedMapOverlayRequest ("RenderNamedMapWithGridLayerOverlay","/Samples/NamedMaps/WorldMap", mapview, gridlayer); RenderNamedMapWithOverlayResponse response = mapping.rendernamedmapwithoverlay(request); PrintMappingResponse.printRenderNamedMapWithOverlayResponse(response); } catch (ServiceException se) { PrintMappingResponse.printError(se); } catch (Exception e) { e.printstacktrace(); } } } 142

143 8 - How To's This section contains instructions for commonly performed tasks. In this section Mapping 144 Accessing Data from a Database 158 Map Tiling 160 Web Service Authentication 179 WMS Configuration 184 Custom Symbols 195

144 How To's Mapping Design Your Map Spectrum Technology Platform supports a range of approaches to designing maps for use with the Mapping Service, from simple named maps that require no customization, to more complex maps where styles and themes can be created on the fly. The amount of customization to include in your map is tied to how you want your users to interact with it and how dynamic your data is. Render a Named Map The simplest map to render is a named map. A named map resides in the repository and includes all the data source, mapping and layer information needed to display a map image. A named map can be rendered in a SOAP or REST request. The only information to provide at runtime in addition to the named map is the map view, which is the location and the size of the map. The best way to create a named map is to use MapInfo Professional to interactively create your map content and settings. Saving this map as an MWS (MapInfo Workspace) provides the XML content for the Named Map Tool in Management Console to store the map and related items in the repository. It is then ready for use by the Mapping Service. For a SOAP example, go to the Spectrum Spatial SOAP Mapping Service Demo Page at choose Render Named Map from the drop-down list. For a REST example, see Render Named Map Given a Center and Zoom. and Render a Named Map with an Overlay If a named map is too restrictive, consider adding an overlay in your mapping request. An overlay is a way of customizing a named map that cannot be customized directly. Overlays can be layers or themes, and can be based on tables, inline tables and views. For example, an overlay of a feature layer can include features from an in-memory table as the result of a search query. Overlays are part of the mapping request. They are not stored in the repository. In a SOAP request the overlay is defined in an OverlayList. In a REST request, the overlay is defined in the JSON object. For a SOAP example, go to the Spectrum Spatial SOAP Mapping Service Demo Page at choose Render Named Map with BarLayer Overlay from the drop-down list. For a REST example, see Map with Pie Layer Overlay. and 144

145 How To's Render Map with Named Layers Using named layers in a map provides users with some level of interaction with the map. The named layers are listed in sequence in the request, which determines the draw order of the map image. This is a good option if you want your application logic or users to select and deselect layers to control the display of information on the map. Named layers are a very powerful capability for managing data. The purpose of a named layer is to indicate how the data in the table is styled. You can create reusable style definitions for a data set by building the complexity you want, such as themes, styles, and zoom level. To use it, you only need to call the layer by name. This option provides similiar functionality to WMS. Rendering a map with named layers allows you to point directly to the named layer, whereas with WMS, the named layer must be first set up in a configuration file. WMS includes GetFeatureInfo whereas the Mapping Service does not. For a SOAP example, go to the Spectrum Spatial SOAP Mapping Service Demo Page at choose Render Map1 example from the drop-down list. For a REST example, see Center and Zoom with Multiple Layers. and Render Map with Inline Layers For more flexibility when rendering a map you can use inline layers, which are layers that are defined in the request. Any supported layer type can be defined inline. Layers can be defined by named tables or memory tables. Named Table The simplest form of an inline layer is defined by a named table. For more dynamic data, consider adding themes, styles, and labels inline instead of building them into the named layer. For a SOAP example, go to the Spectrum Spatial SOAP Mapping Service Demo Page at and choose Render Map With FeatureLayer IVT from the drop-down list. This example includes an inline FeatureLayer that is defined by a named table (/Samples/NamedTables/USA) and an Individual Value theme defined with named styles. For a REST example, see Equal Count Range Theme with MapBasic Styles. This example shows the JSON section of the request that includes a FeatureLayer that is defined by a named table (/Samples/NamedTables/USA) and a Range theme. Memory Table An inline layer that is defined by a memory table is a powerful capability when rendering a map. This option is useful when the data to act upon is not accessible as a named table. Your application would generate a FeatureCollection, for example, a list of points, that can be passed in the request and rendered without accessing the actual data or referring to a named table. 145

146 How To's For a SOAP example, go to the Spectrum Spatial SOAP Mapping Service Demo Page at and choose Render Map2 from the drop-down list. This example includes an inline FeatureLayer that is defined by a memory table, where the FeatureCollection are point locations defined by strings. Use a Map Created in MapInfo Professional A typical early step when developing an application to interact with the Location Intelligence Module in Spectrum Technology Platform is to bring a map that you have created in MapInfo Professional into the Spectrum Spatial repository. This is done by using a MapInfo Professional workspace (MWS) in Management Console. An.MWS is an XML-based workspace containing the map layers and settings that are used to render a map. Using the Management Console, the MWS content is used to add named resources to the repository. For more information on Management Console, see the application's online help. Important: The capabilities for managing named resources are being moved to the Spectrum Spatial Manager and to a MapInfo Professional plug-in called Map Uploader. The Spectrum Spatial Manager allows you to view, rename, move, and delete resources safely, as well as create and modify named connections and named tables. We recommend you use it for these tasks. Adding named maps, as well as adding and modifying named tiles, can be done using Management Console, while adding named maps, tables, and layers can be done using the Map Uploader. However, future enhancements will only be added to the plug-in or the Spectrum Spatial Manager. You can download the Map Uploader installer and view its documentation on the Spectrum Spatial section of the Welcome Page, under the Utilities tab. Documentation for the Map Uploader is also located at support.pb.com. To preserve connections between resources, use the Spectrum Spatial Manager to rename, move, and delete named resources. Adding a Named Map and Named Tables Adding a Named Map and Named Tables Important: The capabilities for managing named resources are being moved to the Spectrum Spatial Manager and to a MapInfo Professional plug-in called Map Uploader. The Spectrum Spatial Manager allows you to view, rename, move, and delete resources safely, as well as create and modify named connections and named tables. We recommend you use it for these tasks. Adding named maps, as well as adding and modifying named tiles, can be done using Management Console, while adding named maps, tables, and layers can be done using the Map Uploader. However, future enhancements will only be added to the plug-in or the Spectrum Spatial Manager. You can download the Map Uploader installer and view its documentation on the Spectrum Spatial section of the Welcome Page, under the Utilities tab. Documentation for the Map Uploader is also located at support.pb.com. To preserve connections 146

147 How To's between resources, use the Spectrum Spatial Manager to rename, move, and delete named resources. To add named maps and named tables to the repository: 1. Open Management Console. 2. Expand Modules > Location Intelligence > Tools then click Named Maps. 3. Click Add. The Add Named Map dialog box appears. 4. Select the MWS file in the MWS source field using the browser button. This MWS file will be used to define the named map. 5. In the Named Map name field enter the name for the named map to be created. You can either use the repository browser button and select the directory in the repository and enter the named map name, or enter the repository path and named map name information in the field. For example, if you are entering the information in the field and creating the nymap named map in the Maps folder in the repository, the name you would enter in the Named map name field would be /Maps/nymap. 6. Select one of the following methods to generate the table information for the named map: 147

148 How To's The Use inline tables option generates a named map with table definitions inline. This means that no named tables are used, rather the named map will contain all relevant table information. Choose this option if you will not be querying data but are merely planning to create tiles from StreetPro data. The Create named tables option generates new named tables in the repository in the specified folder that you define in the Named tables path field. You must choose this option if you are planning to query StreetPro data that you are uploading. If the named table already exists in that folder, it will use the existing one, unless you have selected the Overwrite named tables option. In this case, all named tables will be overwritten with new named table definitions. Note: The Use existing named table option updates the named map by populating the tables in the map using already existing named tables in the repository. The list of named tables are populated in the list and you must verify that each of the named tables is valid in the named map. This option is useful if you have only modified styles and not tables in the MWS in MapInfo Professional, for example. 7. For the Use inline tables and Create named tables options, leave the Local data path blank. 8. For the Use inline tables and Create named tables options, specify the best server path from the server's perspective. The Server data path is used to define the new path from the machine on which you are using Management Console to upload the MWS file (local path), to the new table files located on the hosting machine (server path). For example, if the server is on a machine you remote to, use the mapped drive that is on the server if applicable, not the mapped drive on your own machine. Also a mapped drive address is more efficient than a UNC address, such as \\server-name\directory\filename. This will replace all data paths in the MWS file (up to the name of the table) with the new path specified. This includes both relative or full paths. 9. Click OK. The new named map appears in the tree in the Named Maps dialog. 10. To verify that you successfully uploaded all named tables for the Use inline tables option, open the named map using WebDAV to inspect that the named tables appear inline: 148

149 How To's 11. To verify that you successfully created all named tables for the Create named tables option, click Modify. You can now see the named tables: 12. To verify that you can render a map using the new named map, select the Render Named Map request on the Mapping Service Demo Page at 149

150 How To's modify the named map in the request to match the one you created (as well as the X, Y, and Zoom as needed), then submit. A map image appears on the right side of the page. Note: For the Create named tables option, the tab files referenced in the MWS must exist in the server path or you get an error on loading; for the Use inline tables option, you will not get the error. In the latter case, the named map you create will error at render time. 150

151 How To's Render a Map Once your named resources from the MWS are available in the repository, you are ready to use them in Location Intelligence Module. Rendering a map involves making a RenderMap request to the Spectrum Spatial server. For learning purposes, we will use the Mapping Demo Page that include a list of common SOAP requests. To render a map: 1. Go to the Spectrum Spatial SOAP Mapping Service Demo Page at 2. Choose Render Named Map from the drop-down list of mapping requests and click Submit. The Spectrum Spatial Mapping Service will process the request and return a SOAP response and an image of the named map. The named map associated with this demo request is using a sample named map that was uploaded to the repository at installation time. 3. To view the response and image for one of your named maps, edit the request and replace the text /Samples/NamedMaps/USA with your named map and click Submit. You may need to change the map request to use the center and zoom width appropriate for your data. Create a Thematic Map Important: The capabilities for managing named resources are being moved to the Spectrum Spatial Manager and to a MapInfo Professional plug-in called Map Uploader. The Spectrum Spatial Manager allows you to view, rename, move, and delete resources safely, as well as create and modify named connections and named tables. We recommend you use it for these tasks. Adding named maps, as well as adding and modifying named tiles, can be done using Management Console, while adding named maps, tables, and layers can be done using the Map Uploader. However, future enhancements will only be added to the plug-in or the Spectrum Spatial Manager. You can download the Map Uploader installer and view its documentation on the Spectrum Spatial section of the Welcome Page, under the Utilities tab. Documentation for the Map Uploader is also located at support.pb.com. To preserve connections between resources, use the Spectrum Spatial Manager to rename, move, and delete named resources. To create a named layer that has a theme, or a named map that contains named theme layers, you have to create the definition file for the named layer or named map. The easiest way to gather the information for the named definition is to start in MapInfo Professional. There you create a map with the required theme layers and save it as a MapInfo Workspace (MWS) file. The elements in the MWS serve as the source of information that you will copy and paste into the named layer or named maps containing named layers. Apart from the relative ease with which 151

152 How To's you can create the definition file, this method has the advantage of enabling you to preview the visual appearance of the thematic map and make adjustments in MapInfo Professional before you save the MWS file. Note: While MapInfo Professional can save a map as an MWS file, it cannot always read an MWS file reliably. This means that if you later need to modify the thematic map layers, you may not be able to read the source MWS file back into MapInfo Professional to make the changes. If you need to modify a named layer or named map definition that contains a named theme, you will have to go into MapInfo Professional again to save it as an MWS again. Creating a Theme Using MapInfo Professional For detailed instructions on creating themes in MapInfo Professional, see the MapInfo Professional online help. To create a theme for a map: 1. In MapInfo Professional, open the map in which you want to create the theme layer. If the map does not yet exist, create it. 2. In the map, select the layer to which you want to apply a theme. If the layer does not yet exist, create it. 3. Apply the desired theme to the map layer. 4. Save the map to a MapInfo Workspace (MWS) file. It is also a good idea to save the workspace as a.wor. If you need to make changes to the map, re-open the.wor in MapInfo Professional. MapInfo Professional may not read the.mws file reliably. The MWS will be used to create a named layer and a named map in the following steps. Creating a Named Layer that Has a Theme To create a named layer definition that contains a theme: 1. Create a new empty XML file, and paste the following lines into it: <?xml version="1.0" encoding="utf-8"?> <NamedLayer version="mxp_namedresource_1_5" xmlns=" <ConnectionSet /> <DataSourceDefinitionSet> </DataSourceDefinitionSet> </NamedLayer> This will become the definition file for the new named layer. 152

153 How To's 2. Using the MWS you created in Creating a Theme Using MapInfo Professional on page 152, open it in an XML editor. Find the element that defines the theme layer you want to save as a named layer. This element will have the name <FeatureLayer> or <ObjectThemeLayer>, depending on the type of theme you applied. See the note below. For simplicity, this procedure assumes that the theme layer is defined within a <FeatureLayer> element. 3. Copy all the lines from the open <FeatureLayer> element tag to the close </FeatureLayer> element tag, and paste them into the new definition file immediately above the close </NamedLayer> element tag, as show in the following example: <?xml version="1.0" encoding="utf-8"?> <NamedLayer version="mxp_namedresource_1_5" xmlns=" <ConnectionSet /> <DataSourceDefinitionSet> </DataSourceDefinitionSet> <FeatureLayer>... <DataSourceRef ref="id4" />... </FeatureLayer> </NamedLayer> Note: If you applied a bar chart, pie chart or graduated symbol theme to the map layer, then the layer is defined within an <ObjectThemeLayer> element. If you applied a dot density, individual value, or ranged theme, then the layer is defined within a <FeatureLayer> element. 4. The <FeatureLayer> element you just copied will contain a <DataSourceRef> child element. Take note of the <DataSourceRef> element's ref attribute value. 5. In the MWS file, find the <DataSourceDefinition> element that has the same id attribute value as the <DataSourceRef>'s ref attribute value noted in the previous step. The <DataSourceDefinition> element is a child of the <DataSourceDefinitionSet> element, and has different names depending on the type of the data source. For example, if the data source is a TAB file, then the element name will be <TABFileDataSourceDefinition>. 6. Once you find the corresponding <DataSourceDefinition> element (for example, <TABFileDataSourceDefinition>), copy all the lines from the open element tag to the close element tag, and paste them between the open and close tags of the <DataSourceDefinitionSet> element, as shown in the following example: <?xml version="1.0" encoding="utf-8"?> 153

154 How To's <NamedLayer version="mxp_namedresource_1_5" xmlns=" <ConnectionSet /> <DataSourceDefinitionSet> <TABFileDataSourceDefinition id="id4">... </TABFileDataSourceDefinition> </DataSourceDefinitionSet> <FeatureLayer>... <DataSourceRef ref="id4" />... </FeatureLayer> </NamedLayer> 7. Save the new named layer definition file as a UTF-8 encoded file without the BOM (byte order mark). 8. If you have not already done so, download the schema files to your local machine. The schema files are available for download at support.pb.com. 9. In your XML editor, associate the new definition file with the MXP_NamedResource_1_5.xsd schema you downloaded in step 8 on page Check that the new definition file is valid against the MXP_NamedResource_1_5.xsd schema. If there are any errors, correct them. 11. Once the new definition file passes validation, remove the schemalocation attribute that was added to the root element by your XML editor when you associated the new definition file with the MXP_NamedResource_1_5.xsd schema in step 9 on page Save the definition file and add it to the Location Intelligence Module repository using the Named Resource Service, WebFolders or DAVExplorer. The new named layer, with theme applied, can now be added to your named maps. Creating a Named Map that Contains Theme Layers To create a named map definition that contains theme layers: 1. Create a new empty XML file, and paste the following lines into it: <?xml version="1.0" encoding="utf-8"?> <NamedMapDefinition version="mxp_namedresource_1_5" xmlns=" xmlns:gml=" <ConnectionSet /> <DataSourceDefinitionSet> </DataSourceDefinitionSet> 154

155 How To's </NamedMapDefinition> This will become the definition file for the new named map. 2. Using the MWS you created in Creating a Theme Using MapInfo Professional on page 152, open the MWS file in an XML editor, and find the <MapDefinition> element that defines the map you want to save as a named map. 3. Copy all the lines from the open <MapDefinition> element tag to the close </MapDefinition> element tag, and paste them into the new definition file immediately above the close </NamedMapDefinition> element tag, as show in the following example: <?xml version="1.0" encoding="utf-8"?> <NamedMapDefinition version="mxp_namedresource_1_5" xmlns=" xmlns:gml=" <ConnectionSet /> <DataSourceDefinitionSet> </DataSourceDefinitionSet> <MapDefinition>... </MapDefinition> </NamedMapDefinition> 4. In the MWS file, find the <DataSourceDefinitionSet> element and copy all its child <DataSourceDefinition> elements into the new definition file under the <DataSourceDefinitionSet> element. Note: The <DataSourceDefinition> elements will have different names depending on the type of the data source. For example, if the data source is a TAB file, then the element name will be <TABFileDataSourceDefinition>. 5. Save the new named map definition file as a UTF-8 encoded file without the BOM (byte order mark). 6. If you have not already done so, download the schema files to your local machine. The schema files are available for download at support.pb.com. 7. In your XML editor, associate the new definition file with the MXP_NamedResource_1_5.xsd schema you downloaded in step 6 on page Check that the new definition file is valid against the MXP_NamedResource_1_5.xsd schema. If there are any errors, correct them. 155

156 How To's 9. Once the new definition file passes validation, remove the schemalocation attribute that was added to the root element by your XML editor when you associated the new definition file with the MXP_NamedResource_1_5.xsd schema in step 7 on page Save the definition file and add it to the Location Intelligence Module repository using the Named Resource Service, WebFolders or DAVExplorer. Add a Legend to Your Map Unlike other map components such as themes and styles, legends cannot be included as part of the static definition of a named map. That is, the named resource schemas do not provide any elements for including a legend in a named map's definition file. Instead, legends are always generated 'on-the-fly' when the named map is requested, based on the defined themes and styles of the map's layers. A map legend is composed of individual legend entries or rows. Each legend entry in turn is composed of a symbol or color swatch followed by a text description. When you submit a request for the legend of a named map, zero, one, or more legend entries are returned for each layer in the named map. When you want to request a legend for a map, the request must be submitted to the Mapping Service. You can submit the Mapping Service request directly through either the SOAP interface or the REST interface, or indirectly through the RIA controls. Requesting a Legend Using SOAP To request a map legend using the Mapping Service SOAP interface, you submit (via HTTP POST) a GetNamedMapLegendsRequest request message to the Mapping Service SOAP interface. The Mapping Service will then return a GetNamedMapLegendsResponse response message that contains the requested legend data. For more information on the Mapping Service SOAP interface GetNamedMapLegendsRequest request message and GetNamedMapLegendsResponse response message, see the Services section in the Spectrum Technology Platform Spectrum Spatial Guide on support.pb.com. Legend Examples Using SOAP After you have installed the Location Intelligence Module web services, you can open the Mapping Service Demo Page at and try submitting various SOAP requests for map legends. Requesting a Legend Using REST To request a map legend using the Mapping Service REST interface, you submit an HTTP GET request to the corresponding REST URL. The request URL will have this general form: HTTP GET /maps/mapname/legend.type;w=width;h=height;t=imagetype; 156

157 How To's [r=resolution];[l=locale]?[inlineswatch=boolean] For more information on the Mapping Service REST interface method to request a map legend, see the topic Get Legend for a Named Map in this guide. Legend Examples Using REST After you have installed the Location Intelligence Module web services, you can try submitting the following REST interface URLs to request map legends. Note: In the follow examples, the map legend data is returned in the form of a JSON object. /WorldMap/legends.json;w=16;h=16;t=png /WorldMap/legends.json;w=16;h=16;t=png?inlineSwatch=false /WorldMap/legends.json;w=16;h=16;t=png;r=50 /WorldMap/legends.json;w=16;h=16;t=png;r=50;l=demo Requesting a Legend Using 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. Built entirely in JavaScript, the controls work without the need for any browser plug-ins and without having to write any server-side code. One of the RIA controls, the LegendControl, enables you to easily add a legend for your map. When your map is displayed in the browser, the LegendControl calls on the Mapping Service to provide the legend data for the map. The RIA controls are included when you install the Location Intelligence Module web services. For more information on the RIA controls, see What Are the RIA Controls? on page 17. For information on the RIA JavaScript API, see the support.pb.com. Legend Examples Using RIA Controls After you have installed the Location Intelligence Module web services, you can open the RIA Examples page on the Spectrum Welcome Page at to see the various RIA controls in action. To try the RIA LegendControl, click Map Legend on the left menu. 157

158 How To's Accessing Data from a Database The Location Intelligence Module supports several methods to access data stored in a database management system: Create an XML document that represents the data source. See the Resources and Data section in the Spectrum Technology Platform Spectrum Spatial Guide on support.pb.com for information on how to upload to the repository. Upload a workspace using the Map Uploader or Management Console. Recommended method: Add a JDBC connection to the data source using Spectrum Spatial Manager. Creating a Connection Spectrum Spatial Manager allows you to create database (JDBC) or file-system named connections. To create a connection in Spectrum Spatial Manager: 1. Navigate to the location in the repository where you want to create the connection. This location must be a folder that contains the datasources (such as TAB files) that will use the connection; that is, it must be located above the resources and not below. 2. From the Create drop-down located in the toolbar, select Connection. Note: This is disabled if you do not have sufficient permissions. The Create Connection page appears. 3. Type the name for the connection. The Spectrum Spatial Manager will warn you if another connection exists with that name, in which case you will have to enter another name. Names are case sensitive and cannot contain the following characters: / \ : [ ] * { } " 4. Select the connection type, File System or Database. Use the file-system type for file-based datasources such as TAB files. Use the database type if you have a JDBC database (Oracle, PostGIS, SAP HANA, or SQL Server) as a datasource. 5. If you selected File System, follow the steps below then continue to step 7. a) Click the Browse button to locate it on your server file system. b) In the Select a Folder dialog, you can use the drop-down to select a drive or type a UNC path (for example, \\localhost\share) and press Enter. UNC paths are supported for Windows. You can double-click folders to see the contents underneath. c) Click the folder you want so that it appears in the Folder field, then click Select. Note: If you cannot locate a folder, check with your Spectrum Technology Platform administrator to determine if restrictions have been placed at the file-server level. 158

159 How To's 6. If you selected Database, complete these fields then continue to step 7. a) Specify the JDBC connection URL to the database. This URL is in the format jdbc:subprotocol:subname. For example: Oracle SQL Server Postgres/PostGIS SAP HANA Generic JDBC Note: Spectrum Spatial Manager does not allow backslashes in JDBC URLs, even though SQL Server allows JDBC URLs of the following form, jdbc:sqlserver://<servername>\<instancename> Use an alternative URL format such as: jdbc:sqlserver://<servername>:<portnumber>;databasename=<nameofdatabase> or jdbc:sqlserver://<servername>;instancename=<instancename>; databasename=<nameofdatabase> For more information, see and b) In the Username field, optionally specify the user for connecting to the database resource. c) In the Password field, optionally specify the password for the user connecting to the database resource. d) In the Properties field, optionally specify any database specific connection properties. Consult the database documentation for property names and value types that can be appended to a connection string. For example, property value networkprotocol and key tcp. e) Click Test to make sure your connection is valid. 7. Click Create. The details page for the named connection appears. A message also appears at the top of the page if there are named tables using inline references that could be updated to use this connection instead. Click the link to update named tables with this connection (see Benefits of Using a Connection for more information on why you should use connections and Applying a Connection to Inline Named Tables for instructions). 159

160 How To's Map Tiling Map tiles are portions of a map that are seamlessly joined on the fly while you are panning and zooming in the map window. Each pan and zoom is a call to the server to request the appropriate map tile(s). Only those that fit the bounds of the map view and match the zoom level are returned. Google Maps and Bing Maps are examples of applications that use map tiles. Spectrum Technology Platform includes a Map Tiling Service that returns map tiles on the fly or from a tile cache at the user's request. Through the Map Tiling REST Interface, the mapping client can determine the maps that are available from the server, query the metadata of each map and return a map comprised of tiles. MapInfo StreetPro data is well-suited for use as map tiles. StreetPro is typically used as reference layers for a map. Configuring map tiling for use in Spectrum Technology Platform involves creating a named tile definition that describes your named map and adding it to the repository. To request tiles, use the Tile method from the REST interface. Tiles will be created on the fly. For greater rendering efficiency, consider pre-generating the map tiles or setting up a tile cache for on-the-fly tiles. Configuring the Map Tile Service The Map Tiling Service configuration file MapTilingConfiguration is located in the Configuration directory under the root repository. For example, a default installation will place the Map Tiling Service configuration file at To configure the Map Tiling Service: 1. From the machine hosting Spectrum Technology Platform and the repository, copy the configuration file from the repository to a directory on your local machine using a standard WebDAV protocol tool. 2. Make changes to the local MapTilingConfiguration file. For parameter descriptions for the configuration file, see Global Configuration Parameters on page Upload the modified configuration file to the same location (and name) in the repository using your WebDAV tool. 4. Use the Spectrum Technology Platform JMX Console to invoke the new configuration for the service. For instructions on how to reload the configuration using the JMX Console, see Reload the Service Configuration using JMX Console on page

161 How To's Accessing the Repository using WebDAV Configuration files are pre-loaded in the repository for each service. These configuration files are located at To configure the services, you must use a WebDAV protocol tool to access the JCR repository, make changes to the configuration file, and reload the configuration using the JMX Console. There are many tools available to accomplish the WebDAV connection tasks. We have provided examples using WebFolders and DAVExplorer. Global Configuration Parameters The Map Tiling Service configuration consists of a set of global parameters that define how tiles are generated. These parameters are used if optional parameters defined in the named tiles are not specified. If a named tile has defined these parameters, then the parameters in the global configuration will be overwritten. The following are global configuration paramters: Parameter Type Required Description RepositoryURL string yes The URL defines the location of your local repository where resource are stored that are accessed by the Map Tiling service. This URL should point to the Repository Service rmi, for example: Note: In most instances, this URL should not be changed. ExpirationDate string no The date on which the client should delete the map tile from the cache, and request a new copy from the server. The ExpirationDate value must be specified as a W3C formatted date string (for example, ). Note: The ExpirationDate parameter has effect only when using external caching software such as Squid or Apache. MimeList string no The available types of tiles generated by the tile server for named tiles when the MimeList is not specified. MapResolution integer no The resolution of the tile images in dots per inch (the number of individual dots that can be placed within the span of one linear inch). The minimum dpi you can define is 72, anything less would render a poor quality image. If a value less than 72 is defined, the service will throw an exception. 161

162 How To's Parameter Type Required Description MapRendering string no The rendering quality (anti-alias) of the tile images generated. You can specify either Speed or Quality. If MapRendering is not specified in either the global configuration or in a named tile, the default rendering quality is Speed. RenderLabels boolean no Tells the service not to render LabelLayers when generating a tile. The value is case-insensitive. If RenderLabels is not specified in either the global configuration or in a named tile, the default is 'true'. PadFactor integer no Used to prevent the clipping of labels when a label crosses a tile boundary. The PadFactor controls the amount of space is rendered around the requested tile with 0 meaning no padding, 1 meaning padding of 1 tile around the requested tile and so on. If PadFactor is not specified in either the global configuration or in a named tile, the default is 1.0. Internally, the Map Tiling service draws tiles to an offscreen bitmap (OSBM) (e.g., BufferedImage). To help speed up rendering of tiles by reducing garbage collection pauses, pools of offscreen bitmaps may be used to avoid constantly creating new ones. The OSBMPooling configuration controls how the offscreen bitmaps are created in memory. Note: If the OSBM pooling section of the configuration is removed, then pooling will not be enabled. The following are OSBM configuration paramters: Parameter Type Required Description MaxActive integer no Controls the maximum number of offscreen bitmaps (per tile dimension) that can be allocated by the pool (checked out to client threads, or idle in the pool) at one time. When non-positive, there is no limit to the number of objects per key. When this value is reached, the keyed pool is said to be exhausted. The default setting for this parameter is 8. MinIdle integer no The minimum number of idle offscreen bitmaps (per tile dimension) that should always be available. If this parameter is set to a positive number and TimeBetweenEvictionRunsMills is greater than zero, each time the idle object eviction thread runs, it will try to create enough idle instances so that there will be this number of idle instances available under each key. The default setting for this parameter is

163 How To's Parameter Type Required Description MaxIdle integer no The maximum number of offscreen bitmap that can sit idle in the pool (per tile dimension) at any time. When negative, there is no limit to the number of objects that may be idle per key. The default setting for this parameter is 8. MaxTotal integer no The global limit on the number of objects that can be in circulation (active or idle) within the combined set of pools. When non-positive, there is no limit to the total number of objects in circulation. When MaxTotal is exceeded, all keyed pools are exhausted. When MaxTotal is set to a positive value and an offscreen bitmap is requested when at the limit with no idle instances available, an attempt is made to create room by clearing the oldest fifteen percent (15%) of the elements from the keyed pools. The default setting for this parameter is -1 (no limit). ExhaustedAction string no The behavior when the pool of offscreen bitmaps is exhausted. The options are fail, grow, or block. Fail will throw an exception when an offscreen bitmap is requested when the pool is exhausted. Grow, the default, will create a new offscreen bitmap and return it, making MaxActive meaningless. Block will stop the process until a new or idle object is available. Optionally, one may configure the pool to examine and possibly evict objects as they sit idle in the pool and to ensure that a minimum number of idle objects is maintained for each key. This is performed by an idle object eviction thread, which runs asynchronously. Caution should be used when configuring this optional feature. Eviction runs require an exclusive synchronization lock on the pool. If they run too frequently or incur excessive latency when creating, destroying or validating object instances, performance issues may result. The idle object eviction thread may be configured using the MinEvictableIdleTimeMills and TimeBetweenEvictionRunsMills parameters. MinEvictableIdleTimeMills integer no The minimum amount of time that an offscreen bitmap may sit idle in the pool before it is eligible for eviction due to idle time. When non-positive, no object will be dropped from the pool due to idle time alone. This parameter has no effect unless TimeBetweenEvictionRunsMillis is greater than zero. The default setting for this parameter is 30 minutes. TimeBetweenEvictionRunsMils integer no How long the eviction thread should sleep before examining idle offscreen bitmaps. When non-positive, no eviction thread 163

164 How To's Parameter Type Required Description will be launched. The default setting for this parameter is -1 (i.e., by default, idle object eviction is disabled). Reload the Service Configuration using JMX Console Once you have modified a service configuration, you must reload the configuration in the repository using the JMX Console. The JMX console allows you to reload and administer a service, without having to restart the application container. To reload the service configuration: 1. Access the JMX Console using the following URL: 2. Under the Domain: Spatial section, select the administration link for the service. For example, Spatial:name=Administration,type=WMS Service. 3. Click the Invoke button for the reloadconfiguration operation. You will get a message on the status of the invocation. Creating a Named Tile Definition To create a named tile definition: 1. Using Management Console, create named resources for your MWS and add them to the repository. See Adding a Named Map and Named Tables on page Using a text editor or an XML editor, create a named tile definition that will display some or all of the named map that was created when you uploaded the MapInfo workspace. We have provided sample named tiles in the repository for some common maps. 3. Using a WebDAV tool of your choice, upload the named tile definition file to the repository. Note: This step must be performed on the machine that hosts the repository. Parameters for Named Tiles Named tiles are stored in the repository, and define how an individual hosted named map is used by the Map Tiling Service. For each map you want to expose through the Map Tiling Service you must have an equivalent named tile. In the named tile file, the NamedTile element contains the parameters that define the named tile, each of which contains some or all of the following list of child elements: 164

165 How To's Parameter Type Required Description DisplayName string yes The alias of the named map stored in the map repository. This alias can be different than the actual name of the named map, and will be used in the tiling service requests to call the named tile. Description string yes The metadata description of the named map. This information is presented to the user when a getdescription call is sent to the Map Tiling Service. ResourceLocation string yes The directory and name of the actual named map in the repository, from the repository base. For example, if the named map is located at default/samples/namedmaps/world, then you would define the ResourceLocation as /NamedMaps/World. Note: You must specify the starting '/'. Projection string yes The coordinate system projection to host the named map. The Map Tiling Service will transform the named map into the projection defined. The projection is defined using the EPSG format. For best results, use epsg:3857 (Spherical Mercator). MinimumLevel integer yes The minimum zoom level to host the map. Must be greater than zero. See What Is Tile Level? for information to help define the level. MaximumLevel integer yes The maximum zoom level to host the map. Must be greater than zero. See What Is Tile Level? for information to help define the level. TileWidth integer yes Width of a tile in pixels. Must be greater than or equal to 16 and must be a number that can be calculated from a 2 n equation (for example 2 4 =16, 2 5 =32, 2 8 =256). Bounds string yes The bounds of the map. Coordinates are comma separated and in the coordinate system specified by the projection option. The bounds must represent a square in order for proper tile divsioning. MimeList string no The available types of tiles generated by the tile server for this map only. ExpirationDate string no The date on which the client should delete the map tile from the cache, and request a new copy from the server. The 165

166 How To's Parameter Type Required Description ExpirationDate value must be specified as a W3C formatted date string. MapResolution integer no The resolution of the tile images in dots per inch (the number of individual dots that can be placed within the span of one linear inch). If not specified, the GlobalMapResolution is used. The minimum dpi you can define is 72. Less than 72 dpi, the service will throw an exception. MapRendering string no The rendering quality (anti-alias) of the tile images generated. You can specify either Speed or Quality. If a MapRendering preference is not specified, the global preference in the configuration will be used to determine the maps rendering quality. If neither is specified, the default rendering quality is Speed. RasterRendering string no The rendering quality (anti-alias) of the tile images generated from raster maps. You can specify either Speed or Quality. If a MapRendering preference is not specified, the global preference in the configuration will be used to determine the maps rendering quality. If neither is specified, the default rendering quality is Speed. RenderLabels boolean no Tells the service not to render LabelLayers when generating a tile. The value is case-insensitive. If a RenderLabels preference is not specified, the global preference in the configuration will be used. If neither is specified, the default is 'true'. PadFactor double no Used to prevent the clipping of labels when a label crosses a tile boundary. The PadFactor controls the amount of space is rendered around the requested tile with 0 meaning no padding, 1 meaning padding of 1 tile around the requested tile and so on. If a PadFactor preference is not specified, the global preference in the configuration will be used. If neither is specified, the default is 1.0. BackgroundOpacity double no The level of background opacity (transparency) for the tile images. The background opacity is defined on a scale from 0.0 (zero) to 1.0. Where 0.0 is completely transparent and 1.0 is completely opaque. For example a value of 0.75, would be 75 percent transparent. The following is an example of a named tile definition: <NamedTile> 166

167 How To's <DisplayName>World</DisplayName> <Description>Map Of The World</Description> <ResourceLocation>/Samples/NamedMaps/WorldMap</ResourceLocation> <Projection>epsg:3857</Projection> <MinimumLevel>1</MinimumLevel> <MaximumLevel>20</MaximumLevel> <TileWidth>256</TileWidth> <Bounds> , , , </Bounds> <MimeList> <Mime>image/png</Mime> <Mime>image/jpeg</Mime> <Mime>image/gif</Mime> </MimeList> <ExpirationDate> </ExpirationDate> <MapResolution>96</MapResolution> <MapRendering>Speed</MapRendering> <RenderLabels>false</RenderLabels> <PadFactor>1.0</PadFactor> </NamedTile> What Is Tile Level? The level, in combination with the tile width, tile height, and bounds of the named map, determines the zoom level of the tiles to be returned. The level shows how close the map image is to the Earth. Level 1 is the furthest away and is composed of one tile that the entire map will be drawn into. Level 2 is composed of 4 tiles, 2 across and 2 down. Each tile is a quarter of the entire map. Level 3 is composed of 16 tiles, 4 across and 4 down, and so on. The higher the level specified, the closer to the Earth the map image appears. For example, levels 1 to 3 usually show global or hemispheric detail, levels 4 to 15 show county/state/province level of detail and some larger cities, levels greater that 15 show street level views. What the levels actually display is dependent on the named map hosted by the Map Tile Service and the parameters in the named tile definition. For example, a level of 1 for a world map would be zoomed out to show the entire world. However, if you have a named map of a city or region where the bounds is less than the whole world, Level 1 would be zoomed in to show the regional or street level map. How Tile Height Is Calculated The tile height is calculated from the map bounds and the tile width to produce a tile that has the same aspect ratio as the bounds. The tile height is calculated using the following equation: tileheight = (boundsheight boundswidth) tilewidth 167

168 How To's There is one restriction when defining a map: the resultant tile height must be a whole number (integer). Since tile height and tile width are calculated in pixels, it is impossible for a user to display these values as fractions of a pixel. For example, a map with a bounds of (-180, -90, 180, 90) in WGS84 has an aspect ratio (width to height) of 2:1. So the tileheight calculation is half the tilewidth. If you defined the tilewidth parameter to be 256 then the tileheight would be 128. This is an acceptable tileheight value. However, if you have defined a map with the bounds of (-180, -90, 90, 0) in WGS84, that would create an aspect ratio of 3:1. Calculating the tileheight based on a tilewidth of 256 would result in a tileheight of This is not an acceptable tileheight value, and will not be displayed by the Map Tiling Service. If a map hosted by the Map Tiling Service is configured with tilewidth and bounds parameter settings that result in an invalid tileheight calculation, then the map will not appear in the list of available maps returned by a call to the getmaps method in the Map Tiling Interface. StreetPro Named Tile Definition StreetPro data is well-suited to being used for map tiling in a web application. The layers provide a wealth of reference information for a map and the information doesn't change very often. To use StreetPro in tiling, create a named tile definition that points to a StreetPro named map in the repository. If you are interested in creating a named tile based on a smaller geography than the entire world, you will need to define fewer levels. We recommend the beginning level of 7. However, the bounds of the map should stay at the world level for best results. Creating a StreetPro Named Tile Once you have uploaded your named map (and named tables, optionally), you then also have the option of creating a named tile using Management Console. You can render StreetPro data on a map with or without map tiles; however, tiling makes map rendering more efficient. To create a named tile for a StreetPro named map: 1. In Management Console, under Location Intelligence > Tools, select Named Tiles. 168

169 How To's 2. Click Add. Populate the fields with the following data: 169

170 How To's Name: (Required) Enter the name of the new named tile including the repository path and name for the named tile. You must prepend the name of the named tile with where in the repository the named tile is going to be created. For example, /StreetPro/NYStateTile. You cannot modify the name of an existing named tile. Changing the name of an existing resource would cause any services or jobs that reference the resource to fail. Description: (Optional) Add a metadata description of the named map. This information is presented to the user when a getdescription call is sent to the Map Tiling Service. NamedMap: (Required) Enter the name of the named map to be used as the source of the name tile. Either enter the name of the named map including the repository path of the resource in the repository, or use the repository browser button and select the named map from the repository. Coordinate system: (Required) Keep the default coordinate system projection, epsg:3857. MinLevel: (Required) Enter the minimum zoom level to host the map; for StreetPro enter 7 as the optimal minimum level. Must be greater than zero. The level, in combination with the tile width, tile height, and bounds of the named map, determines the zoom level of the tiles to be returned. The level shows how close the map image is to the Earth. Level 1 is the furthest away and is composed of one tile that the entire map will be drawn into. Level 2 is composed of 4 tiles, 2 across and 2 down. Each tile is a quarter of the entire map. Level 3 is composed of 16 tiles, 4 across and 4 down, and so on. The higher the level specified, the closer to the Earth the map image appears. For example, levels 1 to 3 usually show global or hemispheric detail, levels 4 to 15 show county/state/province level of detail and some larger cities, levels greater that 15 show street level views. MaxLevel: (Required) Enter the maximum zoom level to host the map; for StreetPro, enter a maximum level of 18 or 19, depending on your specific needs. Width: (Required) Enter the width of the tiles in pixels: 256. Bounds: (Required) Enter the bounds of the map: E7, E7, E7, E7. Coordinates are comma separated and in the coordinate system specified by the Coordinate system field. MimeTypes: (Optional) Enter the available image types of tiles generated by the tile server for the named map: png,jpeg,gif. This is a comma separated list of image mime types. ExpiryDate: (Optional) Enter the date on which the client should delete the tile from the cache, and request a new copy from the server: The ExpiryDate value must be specified in a W3C formatted date string as YYYY-MM-DD. Resolution: (Optional) Keep the default resolution of 96. MapRendering: (Optional) Keep the default option for Speed. RasterRendering: (Optional) Keep the default option for Speed. RenderLabels: (Optional) Select False so that labels will not be rendered on your tiles for label layers in this map. PadFactor: (Optional) Keep the default value of 1. The pad factor is used to prevent the clipping of labels when a label crosses a tile boundary. The PadFactor controls the amount of space is rendered around the requested tile with 0 meaning no padding, 1 meaning padding of 1 tile around the requested tile and so on. BackgroundOpacity: (Optional) Enter 0.5 for the level of background opacity (transparency) for the tile images. The background opacity is defined on a scale from 0.0 (zero) to 1.0. Where

171 How To's is completely transparent and 1.0 is completely opaque. For example a value of 0.5, would be 50 percent transparent. 3. Click OK. The named tile is now available for use in the Map Tiling Service. As you render tiles in calls to the tile service, they are generated on the fly (if they do not already exist in the cache) and stored in the tile cache if it is configured to do so. Requesting a Map Tile Once the named tile definition is in the repository, you are ready to formulate and submit an XML request for the map tile. You do this using the Tile method in the Spectrum Technology Platform REST interface. In the REST Interface, all the parameters are included in the request For the tile method these include service, named map, tile level, column and row based on the level, and the output image format. 1. Create the Tile request following the example: 2. Copy the request into a browser and refresh the page. The tile displays. 3. To learn about all capabilities of the Map Tiling Service, go to and choose the JavaScript sample application. Click on the Map Tiling tab. 4. Choose any of the supported methods and study the responses in the map window and/or the response windows. Generating Map Tiles The Tile Generator is a command line utility that enables a user to execute batch runs to generate map tiles. Generating Tiles from a Request File This procedure outlines how to create a tile request list and use it to generate tiles with Tile Generator. To generate tiles from a tile request list: 1. Extract the files from TileGeneratorUtility.zip to a location of your choice. 171

172 How To's 2. To generate a tile request file, in a command window, type cache_builder.bat followed by the required and optional parameters that meets your needs, as defined in the table. cache_builder.bat -url= -fileoutput=c:\spatialserver\tiling\maptilingrequests.txt -map=/namedtiles/worldtile -level="1,2-4" -mbr=" , , , " -username=admin -password=admin Parameter Required Description -fileoutput <fileoutput> yes Path and name of the file the tile requests will be saved to. -level <level> yes Level(s) for which to generate tiles (e.g., comma separated 1,2,6 or range 1-10). -map <map> yes Named tile in the repository used to create tile(s) ( e.g., /NamedTiles/WorldTile). -mbr <mbr> no Minimum Bounding Rectangle (MBR) to be used to generate tiles. -password <password> yes Password to access the repository. -url <url> yes URL to the MapTiling Service. -username <username> yes User to access the repository. 3. To generate the tiles using the output file from step 2, in the command window, type cache_builder.bat followed by the parameters as defined in the table below. cache_builder.bat -url= -fileinput=c:\spatialserver\tiling\maptilingrequests.txt -image=png -threads=1 -diroutput=c:\spatialserver\tiling\output -username=admin -password=admin Parameter Required Description -diroutput <diroutput> yes Path to the directory the generated tiles will be saved to. 172

173 How To's Parameter Required Description -fileinput <fileinput> yes Path and name of the request file to generate the tiles. -image <image> yes Image type of tiles (e.g., png). -password <password> yes Password to access the repository. -threads <threads> no Number of threads to use to generate the tiles. -url <url> yes Specifies the URL to the MapTiling Service. -username <username> yes User to access the repository. -cache <cache> no When set to false, sets the HTTP cache-control header to no-cache when doing a tile request. This tells the proxy server to go back to the originating server for the tile. The proxy server will replace what s in its cache with the new tile. Generating Tiles Without a Request File This process generates tiles directly by specifying all parameters in the command. No input file is needed. To generate tiles: 1. Extract the files from TileGeneratorUtility.zip to a location of your choice. 2. In the command window, type cache_builder.bat followed by the parameters as defined in the table below. cache_builder.bat -url= -image=png -level="1,2-4" -threads=1 -map=/namedtiles/worldtile -mbr=" , , , " -diroutput=c:\spatialserver\tiling\output -username=admin -password=admin Parameter Required Description -diroutput <diroutput> yes Path to the directory the generated tiles will be saved to. 173

174 How To's Parameter Required Description -image <image> yes Image type of tiles (e.g., png). -level <level> yes Level(s) to generate tiles for(e.g., comma separated 1,2,6 or range 1-10). -map <map> yes Named tile resource used to create tile(s) in the repository( e.g., /NamedTiles/WorldTile). -mbr <mbr> no Minimum Bounding Rectangle(MBR) to be used to generate tiles. -password <password> yes Password to access the repository. -threads <threads> no Number of threads to use to generate the tiles. -url <url> yes Specifies the URL to the MapTiling Service. -username <username> yes User to access the repository. -cache <cache> no When set to false, sets the HTTP cache-control header to no-cache when doing a tile request. This tells the proxy server to go back to the originating server for the tile. The proxy server will replace what s in its cache with the new tile. Caching Tiles A built-in pluggable tile caching mechanism is provided with the Map Tiling Service. This allows you to pre-generate tiles, and use these tiles as a cache source for your application. You can also use the tile cache for holding on-the-fly rendered tiles for more efficient map navigation. Tiles can be pre-generated using the Tile Generator utility. Install the Tile Generator Utility by extracting the files from <installdir>\spectrum\server\app\exports. Caching is used to enhance performance and minimize redundant rendering of frequently rendered map tiles. As an alternative to the service's built-in caching mechanism, you can use external caching software such as Squid or you can write your own caching mechanism. In both cases, you must have the service's built-in caching mechanism turned off. Creating a Tile Cache To set up a tile cache for pre-rendered or on-the-fly tiles: 174

175 How To's 1. Download and install an instance of the Apache HTTP Server that will act as the front end to your Spectrum Technology Platform installation. Note: The Apache web server must be installed on a machine that has network access to the one that hosts Spectrum Technology Platform. The front-end Apache server will act as a sort of filter, intercepting NamedTile requests so that the requested map tiles can be cached to disk. 2. Modify the Apache server's configuration file: apache_install_dir/conf/httpd.conf. a) Open httpd.conf in a text editor. b) In httpd.conf, find this line... Listen 80...and immediately below it, add this line... Listen 90 c) At the end of the file, add this line... Include conf/tilecaching.conf d) Save the changes you have made to httpd.conf, and close the file. 3. In the apache_install_dir/conf directory, create a new file named tilecaching.conf. a) Open tilecaching.conf in a text editor, and add the following lines: Note: Placeholder values are shown in bold italics. Replace them with the actual values for your system. LoadModule proxy_module modules/mod_proxy.so LoadModule proxy_http_module modules/mod_proxy_http.so LoadModule headers_module modules/mod_headers.so <Directory "c:/maptilecache_dirname"> AllowOverride None Order allow,deny Allow from all </Directory> NameVirtualHost *:90 NameVirtualHost *:80 ProxyRequests off ProxyPreserveHost On <Proxy *> Order allow,deny Allow from all 175

176 How To's </Proxy> <VirtualHost *:80> ServerName spatialserver <Location /rest/maptilingservice/namedtiles/> RequestHeader unset Authorization </Location> ProxyPass /rest/maptilingservice/namedtiles/ ProxyPassReverse /rest/maptilingservice/namedtiles/ ProxyPass / ProxyPassReverse / </VirtualHost> <VirtualHost *:90> ServerName spatialserver ProxyPass / ProxyPassReverse / <Location /rest/maptilingservice/namedtiles/> Header merge cache-control "public" RequestHeader set Authorization "Basic YWRtaW46YWRtaW4=" </Location> LoadModule cache_module modules/mod_cache.so LoadModule disk_cache_module modules/mod_disk_cache.so CacheRoot c:/maptilecache_dirname CacheEnable disk /rest/maptilingservice/namedtiles/ CacheIgnoreHeaders None </VirtualHost> b) Save the changes you have made to tilecaching.conf, and close the file. 4. Create the directory that will hold the cached map tiles. Give the directory a name that will make its purpose clear, such as maptilecache. Be sure to specify the name correctly in the tilecaching.conf configuration file. 5. Restart the Apache web server. Enabling Pluggable Tile Caching To enable the pluggable tile cache in the Map Tiling Service: 176

177 How To's 1. Use a standard WebDAV protocol tool to access the repository (e.g., Windows WebFolders, DAVExplorer, etc.) and copy the configuration file from the repository to a directory on your local machine. The Map Tiling Service configuration file is located in the repository's Configuration folder ( 2. Open the local MapTilingConfiguration file in any text editor. 3. In the Cache section, set enabled to true. <Cache enabled="true"> 4. Set the diskpath property to the location where your tiles are stored. Since this location not only stores your pre-generated tiles, but also stores tiles that are generated by the tiling service, this directory must be writable by the user account that launches the Spectrum Technology Platform. <Property name="diskpath" value="c:/program Files/Pitney Bowes/Spectrum/server/modules/spatial/TileCache"/> 5. Optionally modify the tilepathpattern property to define how tiles are stored in the diskpath directory structure. The file structure in the cache is define by the three properties :diskpath/tilepathpattern/tilenamepattern. You can use the key words (mapname, level, row, column, mimetype) to set the path format. <Property name="tilepathpattern" value="mapname/level/row"/> 6. Optionally modify the tilenamepattern property to define how tiles are named in the diskpath directory structure. The file structure in the cache is define by the three properties :diskpath/tilepathpattern/tilenamepattern. You can use the following three tilenamepattern values (row.mimetype, column.mimetype, row-column.mimetype) to set the name format. <Property name="tilenamepattern" value="column.mimetype"/> 7. Upload the modified configuration file back to the same location (and name) in the repository using your WebDAV tool. 8. Use the Spectrum Technology Platform JMX Console to invoke the new configuration for the service. For instruction on how to reload the configuration using the JMX Console, see Reload the Service Configuration using JMX Console on page

178 How To's The pluggable tile cache is now enabled. You can now use your pre-generated tiles at the location you specified. Creating Your Own Tile Caching Mechanism Depending on your organization's requirements, you may need to create your own custom tile caching mechanism. For example, the built-in tile caching mechanism included with the Location Intelligence Module caches tiles on the file system. If instead you want to cache your tiles in a database, you will need to create your own custom tile caching mechanism. To create your own tile caching mechanism, use the following steps: 1. Create a Java class that implements the following interface: com.mapinfo.midev.service.maptiling.cache.itilecache Note: Your implementing class must contain a default (no arguments) constructor. The ITileCache interface class is packaged in this JAR file: Spectrum_install_dir/server/modules/spatial/lib/midev-service-maptiling jar For information about each of the ITileCache methods you will need to implement, see the ITileCache Javadoc file located here: Spectrum_install_dir/server/modules/spatial/javadoc 2. Package your implementing class into a JAR file, and place a copy of the JAR file in this directory: Spectrum_install_dir/server/modules/spatial/lib 3. Register your implementing class in the java.properties file by setting its full name as the value for the maptiling.tilecache.class key. The java.properties file is located in the Spectrum_install_dir/server/modules/spatial directory. 4. Pull the named configuration file for the Map Tiling Service (MapTilingConfiguration.xml) out of the repository using your favorite WebDAV tool. The default location of the MapTilingConfiguration.xml file in the repository is: 5. Using a text editor, add any initialization settings for the cache to the MapTilingConfiguration.xml named configuration file. Each initialization setting is added to a <Property> element that is a child of the <Cache> element in the configuration file. Each <Property> element has a name attribute and a value attribute which holds the name and value of the initialization setting. 6. Re-add the named configuration file back into the repository using your favorite WebDAV tool. 178

179 How To's 7. Do one of the following to reload the Map Tiling Service configuration: Restart the web service. Use the Spectrum Technology Platform JMX Console (available at to reload the configuration without restarting the web service. The Map Tiling Service will now use your custom tile caching mechanism to cache the map tiles. Web Service Authentication Spectrum Technology Platform web services can be configured to allow access only to authenticated users. When developing a client application that will access such a web service, you must add program code that will pass the user's credentials to the web service. Using Basic Authentication Basic authentication is one of the authentication methods a client application can use to pass a user's credentials to a Spectrum Technology Platform web service. When basic authentication is used, a username and password are concatenated, with a colon separating the two values. The resulting string is then Base64 encoded and transmitted in the HTTP header of the web service request. Using Basic Authentication to Access SOAP Services To use basic authentication to access a SOAP service, your client application must add the username and password to an instance of the service interface. Just before the request is submitted to the SOAP service, the username and password set in the service interface are Base64 encoded and inserted into the HTTP Authorization request header. Java Example The following program listing (Preference.java) shows an example of a Java class that adds the username and password to the service interface: package com.pbbi.midev.feature.feature.utility; import java.net.url; import javax.xml.namespace.qname; import javax.xml.ws.bindingprovider; import com.mapinfo.midev.service.feature.ws.v1.featureservice; 179

180 How To's import com.mapinfo.midev.service.feature.ws.v1.featureserviceinterface; public class Preference { public final static String NAMESPACE = " public final static String SERVICENAME = "FeatureService"; public final static String DEFAULT_SERVICENAME = " public final static String USERNAME = "admin"; public final static String PASSWORD = "admin"; public static FeatureServiceInterface getserviceinterface() throws Exception { FeatureService service; FeatureServiceInterface serviceinterface; service = new FeatureService(new URL(DEFAULT_SERVICENAME), new QName(NAMESPACE, SERVICENAME)); serviceinterface = service.getfeatureserviceinterface(); Preference.setUserCredentials(serviceInterface, USERNAME, PASSWORD); return serviceinterface; } public static void setusercredentials(featureserviceinterface serviceinterface, String username, String pasword) { BindingProvider provider = (BindingProvider)serviceInterface; provider.getrequestcontext().put(bindingprovider.username_property, username); provider.getrequestcontext().put(bindingprovider.password_property, pasword); } } C# Example The following program listing (Preference.cs) shows an example of a C# class that adds the username and password to the service interface: using System; using System.Collections.Generic; using System.Linq; using System.Text; using FeatureSamples.FeatureService; 180

181 How To's using System.ServiceModel; namespace FeatureSamples { class Preference { public static String ENDPOINT_CONFIG_NAME = "FeatureServiceInterface"; public static String DEFAULT_SERVICE_URL = " // This is used to create an client interface to the Feature service. public static FeatureServiceInterfaceClient getserviceinterface() { // create the client to communicate to the service. // can also use the empty client constructor as below // FeatureServiceInterfaceClient client = new FeatureServiceInterfaceClient(); // In this case, the default value for the 2 parameters are set in the app.config file. // app.config is a configuration file generated when the Visual Studio imports a service WSDL. // the remote address will be default to the service URL entered for the WSDL. // FeatureServiceInterfaceClient client = new FeatureServiceInterfaceClient(ENDPOINT_CONFIG_NAME, DEFAULT_SERVICE_URL); // Create client with Basic authentication BasicHttpBinding binding = new BasicHttpBinding(); binding.sendtimeout = TimeSpan.FromSeconds(25); binding.security.mode = System.ServiceModel.BasicHttpSecurityMode.TransportCredentialOnly; binding.security.transport.clientcredentialtype = System.ServiceModel.HttpClientCredentialType.Basic; EndpointAddress address = new EndpointAddress(DEFAULT_SERVICE_URL); FeatureServiceInterfaceClient client = new FeatureServiceInterfaceClient(binding, address); // set username and password client.clientcredentials.username.username = "guest"; client.clientcredentials.username.password = ""; } } } return client; 181

182 How To's Using Basic Authentication to Access REST Services To use basic authentication to access a REST service, your client application must add the Base64-encoded username and password to the HTTP Authorization request header, using a standard library method corresponding to your client application language. Java Example The following program listing shows an example of a Java class that adds the Base64-encoded username and password to the HTTP Authorization request header: import java.io.bufferedreader; import java.io.inputstreamreader; import java.net.url; import java.net.httpurlconnection; import java.net.authenticator; import java.net.passwordauthentication; public class RestAuth { public static void main(string[] args) { Authenticator.setDefault(new Authenticator() { protected PasswordAuthentication getpasswordauthentication() { return new PasswordAuthentication("admin", "admin".tochararray()); } }); try { URL url = new URL(" HttpURLConnection connection = (HttpURLConnection)url.openConnection(); connection.setrequestmethod("get"); connection.setdoinput(true); connection.setdooutput(true); BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream())); String inputline; while((inputline = reader.readline())!= null) System.out.println(inputLine); reader.close(); } catch(exception e) { 182

183 How To's } } } e.printstacktrace(); C# Example The following program listing shows an example of a C# class that adds the Base64-encoded username and password to the HTTP Authorization request header: using System; using System.IO; using System.Net; using System.Text; namespace RestAuthSample { public class RestAuth { public static string SERVICE_URL = " public static string SERVICE_METHOD = "tables.json"; public static string RESPONSE_FILE = "C:\\tableslist.json"; public static void Main() { try { HttpWebRequest request = (HttpWebRequest)WebRequest.Create(SERVICE_URL + "/" + SERVICE_METHOD); string authinfo = "admin:admin"; // username:password authinfo = Convert.ToBase64String(Encoding.Default.GetBytes(authInfo)); request.method = "GET"; request.headers["authorization"] = "Basic " + authinfo; WebResponse response = request.getresponse(); Stream responsestream = response.getresponsestream(); StreamReader reader = new StreamReader(responseStream); if (reader.endofstream!= true) { StreamWriter writer = new StreamWriter(RESPONSE_FILE); writer.write(reader.readtoend()); 183

184 How To's } writer.close(); } } } reader.close(); responsestream.close(); response.close(); } catch(exception e) { Console.WriteLine(e.ToString()); } WMS Configuration The WMS server support within Spectrum Technology Platform allows you to expose map images of your data to any conforming WMS client. Through configuration you decide what layers are exposed and how they might be presented to a WMS user. These configuration items reuse the named tables and named layers which are best practices for using data in any facet of Spectrum Technology Platform. Step 1: Create Named Tables The first step is to create a named table for each data table to ensure that the data is accessible to the Spectrum Technology Platform server. For examples of named tables for all supported table types, see the Resources and Data section in the Spectrum Technology Platform Spectrum Spatial Guide on support.pb.com. To create a named table: 1. Choose one of the following methods: Using the Spectrum Spatial Manager (see the Resources and Data section in the Spectrum Technology Platform Spectrum Spatial Guide on support.pb.com). Using WebDAV technology, create a new file or edit an existing named table from the repository and save as a new XML file. Add the named table to the repository if edited outside the repository. This choice is for the advanced user who understands the named table schemas and wants to create named tables that are similar to others they have. 2. Verify that the named tables have been uploaded to the repository by going to 184

185 How To's 3. Verify that each named table you create is accessible to Spectrum Technology Platform by going to the Feature Service demo page and choosing DescribeTable. If the named table is built correctly, the Feature Service will return a response that describes the table. Step 2: Create Named Layer WMS uses named layers as the basis for the information to render as a WMS map image. Ultimately, you must create a WMSLayer and add it to the WMS Configuration file, but creating the named layer comes first. For examples of named layers, see the Resource and Data section in the Spectrum Technology Platform Spectrum Spatial Guide on support.pb.com. To create a named layer: 1. Using WebFolders or DAVExplorer to access named resources in the repository, open the sample named layer LayerWithTable in an editor. Save the file with a new name. Contents of the LayerWithTable named layer before editing. The bold sections are what you will edit. <?xml version="1.0" encoding="utf-8"?> <NamedLayer version ="MXP_WorkSpace_1_5" xmlns=" <ConnectionSet /> <DataSourceDefinitionSet> <NamedDataSourceDefinitionRef id="id1" resourceid="/namedtables/usa"/> </DataSourceDefinitionSet> <FeatureLayer id="id9" name="usa" alias="usa" volatile="unknown"> <Visibility visible="true"> <VisibleRange enabled="false"> <ZoomRange uom="mapinfo:length mi">0 0</ZoomRange> </VisibleRange> </Visibility> <DataSourceRef ref="id1" /> </FeatureLayer> </NamedLayer> 2. Change the resourceid to your named table. 3. Create a unique name and alias for the layer. It is important that these elements are unique. If two layers with the same alias are rendered in the same map, only one of the layers will be drawn. 4. If your named layer is a simple layer with default styles, you can skip to step

186 How To's 5. If your layer is more complex, such as it contains a theme or label layer, copy the layer section from the existing MWS and paste it into the new named layer replacing the <FeatureLayer> section. Your layer can be a FeatureLayer, LabelLayer, ObjectThemeLayer or a LayerGroup. Example of a feature layer with a style override (FeatureStyleOverrideTheme). <FeatureLayer id="id49" name="usa" alias="usa" volatile="unknown"> <Visibility visible="true"> <VisibleRange enabled="false"> <ZoomRange uom="mapinfo:length mi" mininclusive="true" maxinclusive="true"> </ZoomRange> </VisibleRange> </Visibility> <DataSourceRef ref="id1"/> <FeatureStyleModifierThemeList> <FeatureStyleOverrideTheme id="id50" name="style Override" alias="style Override id50"> <CompositeStyle> <LineStyle stroke="rgb(0,0,0)" stroke-opacity="1" width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 2</Pen> </LineStyle> <AreaStyle> <LineStyle stroke="rgb(0,0,0)" stroke-opacity="1" width="1" width-unit="mapinfo:imagesize pixel"> <Pen>mapinfo:pen 2</Pen> </LineStyle> <Interior fill-opacity="1" fill="rgb(255,244,208)"/> </AreaStyle> <PointStyle> <FontSymbol text="#" size="12" size-unit="mapinfo:length pt" stroke="rgb(0,0,0)" stroke-opacity="1" family="mapinfo 3.0 Compatible"/> </PointStyle> <MapinfoTextObjectStyle> <FontStyle size="9" size-unit="mapinfo:length pt" stroke="rgb(0,0,0)" stroke-opacity="1" family="arial" font-style="normal" effect="rgb(255,255,255)" effect-opacity="1" effect-type="none" font-weight="normal" text-decoration="none" text-case="default" shadow="false" expand="false"/> </MapinfoTextObjectStyle> </CompositeStyle> </FeatureStyleOverrideTheme> </FeatureStyleModifierThemeList> </FeatureLayer> 6. Save the named layer to the repository. 7. Repeat from Step 1 for each named layer you wish to create. 8. To verify that the named layer(s) were created correctly, go to the Mapping Service demo page and choose Render Map 1 from the drop-down list. 186

187 How To's a) Replace the named layer in the v:1 layer with your named layer. <v1:layer xsi:type="v1:namedlayer" name="/namedlayers/layerwithtable" xmlns:xsi=" b) Click Submit. If you see your named layer in the map window, you created the named layer correctly. You may need to change the map request to use the center and zoom width appropriate for your data. Step 3: Add Layers to WMS Configuration The layers to be exposed in WMS are specified in the WMS Configuration as WMSLayer elements. Each WMSLayer to be rendered references a named layer in the repository. You must add a WMSLayer entry for each layer you want to present on your WMS server. WMSLayers are a flat list of entries under the WMSLayerList element. In addition to the layers of data to be exposed, WMS supports the creation of non-renderable layers that exist for purpose of organization. In the WMS configuration file, you need to create WMSLayer entries for the actual data layers and the layers that are just for organization. In the case of the actual layers, you will provide detailed information about how to expose that layer by following the steps below. In the case of pure organizational layers, the WMSLayer entry only requires a Title representing the user friendly name. To add layers to WMS Configuration. 1. Using WebFolders or DAVExplorer open the WMSConfiguration in an editor. 2. Under the <WMSLayerList> add a WMSLayer entry for each layer. Provide the information following Example: WMSLayer Definition on page 187. For an explanation of the parameters, see Parameters: WMSLayer on page Optionally, if you wish to create a hierarchy for your layers, first create a WMSLayer for the top level layer, but omit the name element. This layer will not render in a WMS GetMap request. The actually hierarchy is created in the WMSConfiguration under the WMSLayerTree section in the next step. Example: WMSLayer Definition Example of a WMSLayer: <WMSLayer> <Name>World</Name> <Title>World</Title> <Abstract>The entire world base map</abstract> <KeywordList> <Keyword>World</Keyword> 187

188 How To's </KeywordList> <Queryable>true</Queryable> <SRSList> <SRS>EPSG:4326</SRS> </SRSList> <NamedResourceList> <ResourcePath>/NamedLayers/LayerWithTable</ResourcePath> </NamedResourceList> <NamedStyleList> <NamedStyle> <Name>PointStylePin</Name> <Title>PointStylePin</Title> <ResourcePath>/NamedStyles/PointStylePin</ResourcePath> </NamedStyle> <NamedStyleList> <LatLonBoundingBox>-180, -90, 180, 90</LatLonBoundingBox> <DefaultPixelSearchRadius>5</DefaultPixelSearchRadius> </WMSLayer> Parameters: WMSLayer Parameter Required Description Name Yes, if layer is to be rendered The name of your Layer. This is the machine readable name of your named layer. If the layer is only listed for organizational purposes, no name is needed. It will get the name of the layer from the Title parameter. Title Yes Human-readable name for your layer. Abstract No Descriptive introduction to your layer. Edit the Abstract to describe what type of features or content the layer provides. Queryable No Boolean that indicates whether the server supports the GetFeatureInfo operation on that Layer. Default is true. Only renderable layers can be queryable. KeywordList No Contains <Keyword> elements to aid in catalog searches. SRSList No List of the Spatial Reference Systems used by the layer. Every renderable layer needs at least one coordinate system either explicitly listed or inherited from a parent. 188

189 How To's Parameter Required Description NamedResourceList Yes The absolute path of the named layer within the repository root. All ResourcePaths must start with a slash (/) character. NamedStyleList No List of available styles for this layer. Any number of styles may be defined for a Layer. Each style must have a Name, Title, and ResourcePath element. The ResourcePath is the absolute path of the NamedStyle within the repository root. All ResourcePaths must start with a slash (/) character. LatLonBoundingBox No Describes the bounding box for the Layer. DistanceBuffer No Deprecated. The distance buffer within which a GetFeatureInfo operation will search all features for information. The default value is 300 meters. DefaultPixelRadiusSearch No Use instead of DistanceBuffer. The distance in pixels within which a GetFeatureInfo operation will search all features in the layer. This can also be set at the Service level and/or in a request using the parameter PIXELSEARCHRADIUS. If specified in both the layer and service levels, the layer level value will override the service level value. If specified in the request, it overrides both the layer and service level values. If not specified at either the service or layer level or in the request, the default value is 3 pixels. Step 4: Create Layer Tree in WMS Configuration Now that you have created all the WMSLayers that represent your WMS offering, you now need to describe how those layers will be organized hierarchically. In the WMSLayerTree section, you will create this hierarchy as nested XML elements where the title of each element must match the title of a WMSLayer element. To create a layer tree in the WMS Configuration. 1. Add a WMSLayerTree entry for each WMSLayer you created in Step 3: Add Layers to WMS Configuration on page 187. Insert a WMSLayerTree element underneath an existing WMSLayerTree element. This would be the root element or a sub element. It cannot be added parallel to the root element. 2. Save the WMS Configuration file and reload it so your changes take effect. To reload the edited WMS Configuration, use the Spectrum Technology Platform JMX Console (available at Choose WMS Service under Domain:Spatial and click Invoke. 189

190 How To's Example: WMSLayer Definition Example of a list of WMSLayerTree layers. The bold entries are non-rendering organizational layers. <WMSLayerTree> <Title>Pitney Bowes Map Server</Title> <WMSLayerTree> <Title>World Map</Title> </WMSLayerTree> <WMSLayerTree> <Title>World Capitals</Title> </WMSLayerTree> <WMSLayerTree> <Title>Mexico</Title> <WMSLayerTree> <Title>Mexico Range Theme</Title> </WMSLayerTree> <WMSLayerTree> <Title>Mexico Label Layer</Title> </WMSLayerTree> </WMSLayerTree> </WMSLayerTree> Step 5: Test the WMS Configuration Once the named layers are created and the information added to the WMS Configuration, check to make sure that your WMS layers are exposed through the WMS service properly and that they follow your intended layout. To test the capabilities: 1. Enter into a web browser: 2. Check the XML returned. Example: WMS GetCapabilities Response Example of a response from a WMS GetCapabilities request. <WMS_Capabilities version="1.3.0" xsi:schemalocation=" <Service> <Name>WMS</Name> <Title>Spatial Server WMS Service</Title> <Abstract>The Spatial Server WMS Service!</Abstract> <KeywordList> <Keyword>mapinfo</Keyword> 190

191 How To's <Keyword>geographic</Keyword> <Keyword>wms</Keyword> </KeywordList> <OnlineResource ns2:type="simple" ns2:href=" <ContactInformation> <ContactPersonPrimary/> <ContactAddress/> </ContactInformation> <Fees>NONE</Fees> <AccessConstraints>NONE</AccessConstraints> </Service> <Capability> <Request> <GetCapabilities> <Format>application/vnd.ogc.wms_xml</Format> <Format>text/xml</Format> <DCPType> <HTTP> <Get> <OnlineResource ns2:type="simple" ns2:href=" </Get> </HTTP> </DCPType> </GetCapabilities> <GetMap> <Format>image/gif</Format> <Format>image/jpeg</Format> <Format>image/jpg</Format> <Format>image/png</Format> <Format>image/tiff</Format> <DCPType> <HTTP> <Get> <OnlineResource ns2:type="simple" ns2:href=" </Get> </HTTP> </DCPType> </GetMap> <GetFeatureInfo> <Format>text/xml</Format> <DCPType> <HTTP> <Get> <OnlineResource ns2:type="simple" ns2:href=" </Get> </HTTP> </DCPType> </GetFeatureInfo> </Request> 191

192 How To's <Exception> <Format>INIMAGE</Format> <Format>BLANK</Format> <Format>XML</Format> </Exception> <Layer queryable="false" opaque="false" nosubsets="false" fixedwidth="0" fixedheight="0"> <Title>Pitney Bowes Map Server</Title> <CRS>CRS:84</CRS> <EX_GeographicBoundingBox> <westboundlongitude>-180.0</westboundlongitude> <eastboundlongitude>180.0</eastboundlongitude> <southboundlatitude>-90.0</southboundlatitude> <northboundlatitude>90.0</northboundlatitude> </EX_GeographicBoundingBox> <BoundingBox CRS="CRS:84" minx="-180.0" miny="-90.0" maxx="180.0" maxy="90.0"/> <Style> <Name>PointStyle</Name> <Title>PointStyle</Title> <Abstract/> </Style> <Style> <Name>LineStyle</Name> <Title>LineStyle</Title> <Abstract/> </Style> <Layer queryable="true" opaque="false" nosubsets="false" fixedwidth="0" fixedheight="0"> <Name>World</Name> <Title>World Map</Title> <CRS>CRS:84</CRS> <EX_GeographicBoundingBox> <westboundlongitude>-180.0</westboundlongitude> <eastboundlongitude>180.0</eastboundlongitude> <southboundlatitude>-90.0</southboundlatitude> <northboundlatitude>90.0</northboundlatitude> </EX_GeographicBoundingBox> <BoundingBox CRS="CRS:84" minx="-180.0" miny="-90.0" maxx="180.0" maxy="90.0"/> <Style> <Name>AreaStyle</Name> <Title>AreaStyle</Title> <Abstract>Default area style.</abstract> </Style> <Style> <Name>AreaStyleBlue</Name> <Title>AreaStyleBlue</Title> <Abstract>Blue area style.</abstract> </Style> <Style> <Name>AreaStyleGreen</Name> <Title>AreaStyleGreen</Title> 192

193 How To's <Abstract>Green area style.</abstract> </Style> <Style> <Name>AreaStyleRed</Name> <Title>AreaStyleRed</Title> <Abstract>Red area style.</abstract> </Style> <Style> <Name>CompositeStyle</Name> <Title>CompositeStyle</Title> <Abstract>Composite style.</abstract> </Style> <Style> <Name>LineStyleDash</Name> <Title>LineStyleDash</Title> <Abstract>Dashed line style.</abstract> </Style> <Style> <Name>LineStyleSolid</Name> <Title>LineStyleSolid</Title> <Abstract>Solid line style.</abstract> </Style> <Style> <Name>PointStylePin</Name> <Title>PointStylePin</Title> <Abstract>Pin point style.</abstract> </Style> <Style> <Name>PointStyleStar</Name> <Title>PointStyleStar</Title> <Abstract>Star point style.</abstract> </Style> </Layer> <Layer queryable="true" opaque="false" nosubsets="false" fixedwidth="0" fixedheight="0"> <Name>WorldCap</Name> <Title>World Capitals</Title> <CRS>CRS:84</CRS> <EX_GeographicBoundingBox> <westboundlongitude> </westboundlongitude> <eastboundlongitude>229.58</eastboundlongitude> <southboundlatitude>-51.7</southboundlatitude> <northboundlatitude>64.24</northboundlatitude> </EX_GeographicBoundingBox> <BoundingBox CRS="CRS:84" minx=" " miny="-51.7" maxx="229.58" maxy="64.24"/> </Layer> <Layer queryable="true" opaque="false" nosubsets="false" fixedwidth="0" fixedheight="0"> <Name>UKREGNS</Name> <Title>UK Regions</Title> <EX_GeographicBoundingBox> <westboundlongitude> </westboundlongitude> 193

194 How To's <eastboundlongitude> </eastboundlongitude> <southboundlatitude> </southboundlatitude> <northboundlatitude> </northboundlatitude> </EX_GeographicBoundingBox> <BoundingBox CRS="CRS:84" minx=" " miny=" " maxx=" " maxy=" "/> </Layer> <Layer queryable="false" opaque="false" nosubsets="false" fixedwidth="0" fixedheight="0"> <Title>Mexico</Title> <CRS>EPSG:3857</CRS> <EX_GeographicBoundingBox> <westboundlongitude>-180.0</westboundlongitude> <eastboundlongitude>180.0</eastboundlongitude> <southboundlatitude>-90.0</southboundlatitude> <northboundlatitude>90.0</northboundlatitude> </EX_GeographicBoundingBox> <BoundingBox CRS="CRS:84" minx="-180.0" miny="-90.0" maxx="180.0" maxy="90.0"/> <Layer queryable="true" opaque="false" nosubsets="false" fixedwidth="0" fixedheight="0"> <Name>MexicoRangeTheme</Name> <Title>Mexico Range Theme</Title> <EX_GeographicBoundingBox> <westboundlongitude> </westboundlongitude> <eastboundlongitude> </eastboundlongitude> <southboundlatitude> </southboundlatitude> <northboundlatitude> </northboundlatitude> </EX_GeographicBoundingBox> <BoundingBox CRS="CRS:84" minx=" " miny=" " maxx=" " maxy=" "/> <Style> <Name>Green</Name> <Title>Green</Title> <Abstract/> </Style> <Style> <Name>Blue</Name> <Title>Blue</Title> <Abstract/> </Style> </Layer> <Layer queryable="true" opaque="false" nosubsets="false" fixedwidth="0" fixedheight="0"> <Name>MexicoLabels</Name> <Title>Mexico Label Layer</Title> <EX_GeographicBoundingBox> <westboundlongitude> </westboundlongitude> <eastboundlongitude> </eastboundlongitude> <southboundlatitude> </southboundlatitude> <northboundlatitude> </northboundlatitude> 194

195 How To's </EX_GeographicBoundingBox> <BoundingBox CRS="CRS:84" minx=" " miny=" " maxx=" " maxy=" "/> </Layer> </Layer> </Layer> </Capability> </WMS_Capabilities> Custom Symbols In MapInfo Professional you can create maps that contain your own custom symbols. If you want to use these maps in Spectrum Technology Platform, you must first save them as MapInfo Professional workspace (MWS) files and then upload them to the Spectrum Technology Platform repository. To have the custom map symbols displayed correctly in Spectrum Technology Platform, you must also follow the additional steps described here. Displaying Custom Symbols To display custom symbols in Spectrum Technology Platform: 1. Add the image files for the custom symbols to a JAR file. 2. Place the JAR file in this directory: install_dir/server/modules/spatial/lib. 3. If necessary, make any required changes to the custom symbol references in the MapInfo Professional workspace (MWS) file. This step is required only in cases where the custom symbol files are not located in the top-level internal directory within the JAR file. In the MWS file, each reference to a custom symbol file can be found in the uri attribute of a Bitmap element. When you save a map as an MWS file in MapInfo Professional, the custom symbol references in the MWS file are set to the name of the custom symbol file only. If the custom symbol files are located in the top-level internal directory within the JAR file, then these references will already be correct. However, if the symbol files are located lower down in the JAR file's internal directory structure, then the uri attributes must be changed to reflect the location of the symbol files within the JAR file. In the uri attribute, each directory level within the JAR file must be separated by a forward slash ( / ), except for the top level. 195

196 How To's For example, if a custom symbol file named my_custom_symbol.png is located in the top-level internal directory within a JAR file, then the default reference to it in the MWS file will still be correct: <Bitmap id="id000017" name="my_custom_symbol" uri="my_custom_symbol.png" height="native" width="native" unit="mapinfo:imagesize pixel"> However, if the custom symbol file is located under an internal directory named images within the JAR file, then its reference in the MWS file should be changed to the following: <Bitmap id="id000017" name="my_custom_symbol" uri="images/my_custom_symbol.png" height="native" width="native" unit="mapinfo:imagesize pixel"> Note: In both cases, note the absence of a forward slash at the start of the uri path. For more information about the Bitmap element, see Bitmap on page Create named resources from the MWS using the Spectrum Technology Platform Management Console. See Adding a Named Map and Named Tables on page Restart Spectrum Technology Platform. 196

197 9 - Migrating from Envinsa or MapXtreme Java This section is for developers who have an application in Envinsa or MapXtreme Java and want to migrate it to Spectrum Spatial. The approach we have taken is a walkthrough of a coverage locator web application that is written in ASP.NET and uses Envinsa web sevices. The walkthrough highlights many of the decisions you will need to make as you evaluate your application for migration. For a higher level comparison of Spectrum Spaital to Envinsa and MapXterme Java, see the white paper "Migrating to a New Generation of MapInfo." The application to be discussed here is a web-based coverage locator solution for determining if wireless service is available from a wireless telecommunications operator and at what quality. The solution is an ASP.NET application using an Envinsa-based web services platform for mapping, geocoding and spatial analysis (Envinsa.NET API Presentation, Directory, Location Utility Services). The client tier is comprised of ASP.NET Web forms and uses Web 2.0 ASP.NET AJAX Extensions. In this section Architecture Considerations 198 Migration Tasks 199

198 Migrating from Envinsa or MapXtreme Java Architecture Considerations This section covers migration decisions about the coverage locator solution architecture. Client Application The client portion of the coverage locator solution is an ASP.NET Web forms/ajax client. Decision: Do we keep the client application as is, using ASP.NET Web Forms, or do we take the opportunity to upgrade to a Web 2.0 Map tile-based application using Open Layers with Spectrum Spatial RIA controls? With the upgrade to Open Layers and RIA controls you will get a fast map display, navigation and a highly responsive user experience. It integrates with Pitney Bowes StreetPro-based base maps or other base maps such as those from Google and Bing maps. It also takes advantage of Spectrum Spatial s Map Tiling Service and Map Tiling generator. For more information on RIA controls, see Working with RIA Controls on page 16. For more information on map tiling, see Map Tiling on page 160. API: SOAP or REST for Geospatial Functionality The coverage locator uses geocoding, point-in-polygon querying and map rendering from the Envinsa.NET API. Decision: Do the Spectrum Spatial SOAP and REST APIs provide the same geospatial capabilities? Spectrum Spatial has built off the foundational interfaces of MapXtreme Java and Envinsa. In Spectrum Spatial, users have the ability to develop applications against one of three APIs: WS-I compliant SOAP interface; REST interface; and Series of OGC (Open Geospatial Consortium) interfaces including WMS, WFS and CSW. Spectrum has the Universal Addressing and Enterprise Geocoding modules for address validation and geocoding. These modules are a superset of Envinsa s Location Utility Service capabilities. Spectrum Spatial's SOAP API provides robust Mapping and Feature services. The REST API provides a smaller set of operations for mapping and feature searching, plus a map tiling service. The SOAP API is easiest to implement in a ASP.NET Web forms architecture while the REST API is easiest to implement in the Javascript-based Open Layers with Spectrum Spatial RIA Controls client. For more information on Spectrum Spatial's SOAP and REST API, see Working With REST Services on page

199 Migrating from Envinsa or MapXtreme Java Data, Data Access and Management The coverage locator solution uses a base map for geographic reference and custom data for the coverages. In Envinsa the data format is MDF, which must be converted to Spectrum Spatial named resources. Decision: How do we access coverage layer data sources for point-in-polygon coverage quality query in Spectrum Spatial? How can we access our base map with coverage layers for map rendering at a specified location and zoom? Data access in Spectrum Spatial is similar to that in Envinsa, via a data provider model, but a generation ahead in terms of performance. For example, Spectrum Spatial can push spatial processing to a database with spatial capability to retrieve only records that satisfy the query. Data Management in Spectrum Spatial has built upon the Envinsa Content Manager concept to create the Spectrum Spatial Repository. The repository contains named resources that point to actual data. By attaching a name to a data resource, it can be referenced from many locations. To change the look or behavior of applications or data, only the resource needs to be changed, not each application or data file. The management tool is called the Management Console. It has capabilities to create named resources and add them to the repository, as well as manage data connections and user access. Automation The processes for address validation, geocoding and point-in-polygon querying in the Envinsa solution required hand-written code specific to the implementation of the coverage locator. Decision: Can we improve on the workflow and performance of the application's business processes for address validation, geocoding and point-in-polygon querying? The Spectrum Spatial Enterprise Designer is a drag-and-drop workflow design tool for automating business processes. It can tie address validation, geocoding and point-in-polygon stages together without writing any code and with the ability to publish the process as a web service, a gain in performance over Envinsa and MapXtreme Java. This new capability is new to the MapInfo suite and enables a product paradigm shift for users and analysts that wish to formulate customized uses of Location Intelligence throughout an organization. Migration Tasks Decision Result After evaluating the architecture options for migrating the coverage locator, the decision is to leave the application as is experienced by the users and change as little as possible. The solution will continue to use ASP.NET Web Forms/Ajax client and we will update the Geosptial functionality and data access and management to use Spectrum Spatial. 199

200 Migrating from Envinsa or MapXtreme Java This section covers how to configure the application, services and data acess, and update the code to use the Spectrum Spatial SOAP API for geoprocessing. Configuration Configuration tasks include: User Account Management This section describes the task for creating users. Adding a User This procedure describes how to create a Spectrum Technology Platform user account and assign a role to the account. 1. Open the Management Console. 2. Expand Security then click Users. 3. Go to System > Security. 4. Click Add. The New User window appears. 5. Click the Add button. 6. Leave the Enable user box checked if you want this user account to be available for use. 7. Leave the Enabled switch set to On if you want this user account to be available for use. 8. Enter the user name in the User name field. Note: User names can only contain ASCII characters. 9. Enter the user's password in the Password field. 10. Reenter the user's password in the Confirm password field. 11. Enter the user's address in the address field. The address is used by some modules to send notifications to users. 12. Enter a description of the user in the Description field. 13. Enter the user's password in the Password field. 14. Reenter the user's password in the Confirm password field. 15. Select the roles you want to give to this user. 16. Click OK. 17. Click Save. 200

201 Migrating from Envinsa or MapXtreme Java Transaction Logging Transaction Logging is managed via the Management Console. For more information see Transaction History. Set Default Options for Services in Repository Configuration Files Set-up Default options for FeatureService, MappingService and GeocodingService services in Spectrum Spatial Repository Configuration files and Management Console 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. Development The development work to undertake when migrating our coverage locator application from Envinsa is to update the code in the following areas: change URLs to the Spectrum Spatial mapping; feature and geocoding services; provide user authentication; configure file references to the named map and data sources; and update the code to use the SOAP/WSDL Spectrum Spatial API in place of the Envinsa.NET API. Convert Envinsa Named Map to MWS Use the Envinsa Map Manager to save the named map as a. gst format file which can than be opened by MapInfo Professional ( MapX geoset Utility) or the MapXtreme Workspace Manager and saved as a MSW workspace file. 201

202 Migrating from Envinsa or MapXtreme Java 1. In the Envinsa Map Manager, save the named map as a.gst and open it in MapInfo Professional or MapXtreme Workspace Manager. 2. Save the.gst as an.mws workspace file. Be sure that Spectrum Spatial can access the.mws file for uploading to the repository. Adding a Named Map and Named Tables Important: The capabilities for managing named resources are being moved to the Spectrum Spatial Manager and to a MapInfo Professional plug-in called Map Uploader. The Spectrum Spatial Manager allows you to view, rename, move, and delete resources safely, as well as create and modify named connections and named tables. We recommend you use it for these tasks. Adding named maps, as well as adding and modifying named tiles, can be done using Management Console, while adding named maps, tables, and layers can be done using the Map Uploader. However, future enhancements will only be added to the plug-in or the Spectrum Spatial Manager. You can download the Map Uploader installer and view its documentation on the Spectrum Spatial section of the Welcome Page, under the Utilities tab. Documentation for the Map Uploader is also located at support.pb.com. To preserve connections between resources, use the Spectrum Spatial Manager to rename, move, and delete named resources. To add named maps and named tables to the repository: 1. Open Management Console. 2. Expand Modules > Location Intelligence > Tools then click Named Maps. 3. Click Add. The Add Named Map dialog box appears. 202

203 Migrating from Envinsa or MapXtreme Java 4. Select the MWS file in the MWS source field using the browser button. This MWS file will be used to define the named map. 5. In the Named Map name field enter the name for the named map to be created. You can either use the repository browser button and select the directory in the repository and enter the named map name, or enter the repository path and named map name information in the field. For example, if you are entering the information in the field and creating the nymap named map in the Maps folder in the repository, the name you would enter in the Named map name field would be /Maps/nymap. 6. Select one of the following methods to generate the table information for the named map: The Use inline tables option generates a named map with table definitions inline. This means that no named tables are used, rather the named map will contain all relevant table information. Choose this option if you will not be querying data but are merely planning to create tiles from StreetPro data. The Create named tables option generates new named tables in the repository in the specified folder that you define in the Named tables path field. You must choose this option if you are planning to query StreetPro data that you are uploading. 203

204 Migrating from Envinsa or MapXtreme Java If the named table already exists in that folder, it will use the existing one, unless you have selected the Overwrite named tables option. In this case, all named tables will be overwritten with new named table definitions. Note: The Use existing named table option updates the named map by populating the tables in the map using already existing named tables in the repository. The list of named tables are populated in the list and you must verify that each of the named tables is valid in the named map. This option is useful if you have only modified styles and not tables in the MWS in MapInfo Professional, for example. 7. For the Use inline tables and Create named tables options, leave the Local data path blank. 8. For the Use inline tables and Create named tables options, specify the best server path from the server's perspective. The Server data path is used to define the new path from the machine on which you are using Management Console to upload the MWS file (local path), to the new table files located on the hosting machine (server path). For example, if the server is on a machine you remote to, use the mapped drive that is on the server if applicable, not the mapped drive on your own machine. Also a mapped drive address is more efficient than a UNC address, such as \\server-name\directory\filename. This will replace all data paths in the MWS file (up to the name of the table) with the new path specified. This includes both relative or full paths. 9. Click OK. The new named map appears in the tree in the Named Maps dialog. 10. To verify that you successfully uploaded all named tables for the Use inline tables option, open the named map using WebDAV to inspect that the named tables appear inline: 204

205 Migrating from Envinsa or MapXtreme Java 11. To verify that you successfully created all named tables for the Create named tables option, click Modify. You can now see the named tables: 12. To verify that you can render a map using the new named map, select the Render Named Map request on the Mapping Service Demo Page at 205

206 Migrating from Envinsa or MapXtreme Java modify the named map in the request to match the one you created (as well as the X, Y, and Zoom as needed), then submit. A map image appears on the right side of the page. Note: For the Create named tables option, the tab files referenced in the MWS must exist in the server path or you get an error on loading; for the Use inline tables option, you will not get the error. In the latter case, the named map you create will error at render time. Updating Envinsa References to Spectrum Spatial To update the Envinsa references to Spectrum Spatial: 206

207 Migrating from Envinsa or MapXtreme Java 1. In the coverage locator configuration file, update the references for the Envinsa services, named map and catalog paths, following the table below: Envinsa Spectrum Spatial Envinsa Service: services/presentation Spectrum Spatial Service: Envinsa Service: Spectrum Spatial Service: Envinsa Service: services/locationutility Spectrum Spatial Service: Envinsa Named Map: <MapPreferences basemapname="mapdisplay/highcovloc" Spectrum Spatial Named Map: <MapPreferences basemapname=" ="/CovLoc/highCovLoc" Envinsa Content Manager Catalog: <Layer name="3g" path="ntelos;ntelos//coverage.3g1x" alias="3g" selected="false"> Spectrum Spatial Named Table: <Layer name="3g" path="/covloc/3g1x" alias="3g" selected="false"> 2. Save the configuration file. Update Code to SOAP API Update the solution code to use the SOAP/WSDL Spectrum Spatial API for the FeatureService, MappingService and GeocodingService requests instead of the Envinsa.NET API. 1. Replace the Envinsa.NET API Directory Service WithinBoundary request with the Spectrum Spatial SOAP/WSDL API FeatureService SearchBySQL request. <SearchBySQLRequest:> <SQL>select Quality from "/CovLoc/3GIX" where MI_Point( , , 'epsg:4326') within obj</sql> 2. Replace the Envinsa.NET API Presentation Service PortrayMapRequest using LayerExtension property to exclude all other coverage layers from map except the selected one. Replace with the Spectrum Spatial SOAP/WSDL API MappingService DescribeNamedMap and RenderMap requests to get a list of layers in the named map to reconstruct it excluding all other coverage layers from map except the selected one. Example from Mapping Service SOAP Demo page: Render Map with FeatureLayer CustomRangeTheme: <S:Body> <v1:rendermaprequest imagemimetype="image/png" 207

208 Migrating from Envinsa or MapXtreme Java returnimage="false"> <v1:mapview xsi:type="v1:zoomandcentermapview"> <v1:width>800.0</v1:width> <v1:height>600.0</v1:height> <v1:zoomlevel uom="mile">3000.0</v1:zoomlevel> <v1:mapcenter srsname="epsg:4269"> <ns3:pos> <ns3:x>-101</ns3:x> <ns3:y>42</ns3:y> </ns3:pos> </v1:mapcenter> </v1:mapview> <v1:map> <v1:layer xsi:type="v1:featurelayer"> <ns2:table xsi:type="ns2:namedtable" name="/samples/namedtables/usa" /> <v1:themelist> <ns5:theme xsi:type="ns5:customrangetheme" expression="pop_2000"> <ns5:rangebinlist> <ns5:rangebin> <ns5:upperbound xsi:type="ns7:doublevalue"> <ns7:value> </ns7:value> </ns5:upperbound> <ns5:lowerbound xsi:type="ns7:doublevalue"> <ns7:value>0</ns7:value> </ns5:lowerbound> <ns6:style xsi:type="ns6:namedstyle" name="/samples/namedstyles/areastylegreen" /> </ns5:rangebin> <ns5:rangebin> <ns5:upperbound xsi:type="ns7:doublevalue"> <ns7:value> </ns7:value> </ns5:upperbound> <ns5:lowerbound xsi:type="ns7:doublevalue"> <ns7:value>0</ns7:value> </ns5:lowerbound> <ns6:style xsi:type="ns6:namedstyle" name="/samples/namedstyles/areastylered" /> </ns5:rangebin> </ns5:rangebinlist> <ns5:allothers xsi:type="ns6:namedstyle" name="/samples/namedstyles/areastyleblue" /> </ns5:theme> </v1:themelist> </v1:layer> </v1:map> </v1:rendermaprequest> </S:Body> 208

209 Migrating from Envinsa or MapXtreme Java 3. Replace the Envinsa.NET API LocationUtility Service GeocodeRequest with the Spectrum SOAP/WSDL API GeocodeUSAddress service request. <GeocodeUSAddressRequest xmlns="http;//localhost:8080/services/geocodeusaddress"> <context> <account.id>admin</account.id> <account.password>admin</account.password> </context> <optional/> <rows> <row> <AddressLine>400 Main St</AddressLine> <City>Hamilton</City> <StateProvince>KS</StateProvince> <PostalCode>56789</PostalCode> </row> </rows> </GeocodeUSAddressRequest> 209

210 10 - Sample Applications In this section we're going to bring together the concepts discussed in the previous sections to create both REST and SOAP client applications. In this section When to Use REST and SOAP 211 REST Samples 211 SOAP Samples 214

211 Sample Applications When to Use REST and SOAP Spectrum supports web service requests using REST and SOAP. They both offer similar capabilities, such as rendering, listing and describing maps and features. While our SOAP API offers more capabilities, the REST API is the more commonly used framework due to its use of JavaScript. An important difference between the two protocols is that REST uses a named resource in a request. SOAP will accept either a named resource or parameters that are written out in the request. A named map has the information about the map already defined and stored in the repository. At render time you cannot change the layer order or hide a layer, for example. If that is an important capability for you, choose SOAP and do not use named maps. But there are other options. One way to use REST and have some ability to control layer rendering is to have multiple named maps where each one defines one layer. If you want to use SOAP services in a JavaScript application, consider creating your own URL. This proxy will parse the request containing the named map and formulate it into a SOAP request containing the individual layers. Proxies are an important component in the RIA controls that ship with Spectrum Technology Platform. For more information see RIA controls section in this guide. 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() { 211

212 Sample Applications //Create an XMLHttpRequest object or try ActiveX var req; if (typeof XMLHttpRequest!= "undefined") { req = new XMLHttpRequest(); } else { try { req = new ActiveXObject("Msxml2.XMLHTTP"); } catch (e) { req = new ActiveXObject("Microsoft.XHTTP"); } } // populate the request, username and password var reqstring = document.getelementbyid('request').value; var username = document.getelementbyid('user').value; var password = document.getelementbyid('password').value; //Execute the REST request against a server secured with Basic Authentication req.open("get", reqstring, false, username, password); req.send(); //Display the response resp = req.response; alert(resp); } </script> <form action="javascript: submitform()"> User: <input type="text" name="user" id="user" value="admin"/> Password: <input type="password" name="password" id="password" value="admin"/><br /> Request: <input type="text" name="request" id="request" value=" /> <input type="submit" value="submit" /> </form> </body> </html> 212

213 Sample Applications 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 = " java.net.url url = new java.net.url(serverurl); java.net.httpurlconnection conn = (java.net.httpurlconnection)url.openconnection(); 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.encodebase64(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.bytearrayoutputstream(); 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()); 213

214 Sample Applications } } 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. Launch the Spectrum Spatial Manager and log in as an administrator. 3. From the Create drop-down located in the toolbar, select Table Note: This button is disabled if you do not have sufficient permissions. The Create Named Table page appears. 214

215 Sample Applications 4. In the Name field, type a name for the named table. Spectrum Spatial Manager will warn you if another named table exists with that name, in which case you will have to enter another name. Names are case sensitive and cannot contain the following characters: / \ : [ ] * { } ". 5. Select the File System data source. 6. Use the file tree to locate the named connection and the TAB file or shapefile. Click the table so that it appears in the Table field below the file tree. Note: The file tree does not appear if you have no named connections. Click Create Named Connection to create one. 7. Click Create. The details page for the named table appears. 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 Management Console. 4. Expand Modules > Location Intelligence > Tools then click Named Maps. 5. Click Add. The Add Named Map dialog box will appear. 6. Select the MWS file in the MWS source field using the browser button. This MWS file will be used to define the named map. 7. In the Named Map name field enter the name. Use the repository browser button and select the directory in the repository and enter the named map name, or enter the repository path and named map name information in the field. 8. Select Create named tables. This option will generate new named tables in the repository in the specified folder defined in the Named tables path field. The data source name from the MWS file is used for the named tables. 9. Set the Local data path and Server data path. Local data path is local to where you are running Management Console. Server data path is the path where Spectrum Technology Platform is running. The local data path will be replaced with the server data path. 10. To create new named tables, set the Named tables path and leave the Overwrite named tables checkbox empty. The Named tables path is the location in the repository where the named tables will be created. If the location doesn't exist, it will be created when you click OK. 11. To overwrite named tables that exist at the location specified in the Named tables path, select the Overwrite named tables checkbox. 215

216 Sample Applications If you do not check the Overwrite named tables checkbox when there are existing named tables, no new named tables are created. The existing ones will be used for the named map. 12. Click OK. 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 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 14. For the URLs of the Feature and Mapping Service WSDL documents, see WSDL URLs on page 13. 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). longitude the longitude (i.e. X ordinate) of the point to search from. latitude the latitude (i.e. Y ordinate) of the point to search from. a FeatureCollection of the 5 subway stations nearest the 216

217 Sample Applications 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); // 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.USERNAME_PROPERTY, ADMIN_USERNAME); ((BindingProvider)servicePort).getRequestContext().put(BindingProvider.PASSWORD_PROPERTY, ADMIN_PASSWORD); // query the Feature Service and return the resulting FeatureCollection try { 217

218 Sample Applications 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. Here is the code: /** * Returns the image of the map overlayed with Features in the specified FeatureCollection. fc the FeatureCollection to render on top of the map. centerlongitude the longitude of the center of the map centerlatitude the latitude of the center of the map zoom the zoom (distance across the map) assumed to be kilometers. 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

219 Sample Applications 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); { // 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(); 219

220 Sample Applications // 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); // 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.USERNAME_PROPERTY, ADMIN_USERNAME); ((BindingProvider)servicePort).getRequestContext().put(BindingProvider.PASSWORD_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(); } 220

221 Sample Applications Final Result And finally, here is the resulting map showing the five nearest subway stations: 221