Java Client Developer Guide - Pitney Bowesreference1.mapinfo.com/software/envinsa/english/4_0/java_developer... · JAVA CLIENT DEVELOPER GUIDE. ... registered trademarks of Sun Microsystems,

JAVA CLIENT DEVELOPER GUIDE

Information in this document is subject to change without notice and does not represent a commitment on the part of the vendor or its representatives. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, without the written permission of MapInfo Corporation, One Global View, Troy, New York 12180-8399.© 2006 MapInfo Corporation. All rights reserved. MapInfo, the MapInfo logo, MapXtreme, MapMarker, miAware, Envinsa, and StreetPro are trademarks of MapInfo Corporation and/or its affiliates.Copyright © 2006 The Legion Of The Bouncy CastleCopyright © 2000-2006 IPDR Organization All Rights ReservedCopyright © 2006, International Business Machines Corporation and others. All Rights Reserved. Copyright © 2006 Open GIS Consortium, Inc., All Rights Reserved.Copyright © 2006 World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University). All Rights Reserved. This product includes software developed by the Apache Software Foundation (http://www.apache.org/).Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.MapInfo Corporate Headquarters:Voice: (518) 285-6000Fax: (518) 285-6070Sales Info Hotline: (800) 327-8627Government Sales Hotline: (800) 619-2333Technical Support Hotline: (518) 285-7283Technical Support Fax: (518) 285-6080Contact information for all MapInfo offices is located at: http://www.mapinfo.com/contactus.Adobe Acrobat® is a registered trademark of Adobe Systems Incorporated in the United States.Products named herein may be trademarks of their respective manufacturers and are hereby recognized. Trademarked names are used editorially, to the benefit of the trademark owner, with no intent to infringe on the trademark.January 2006

http://www.mapinfo.com/contactus

Table of Contents

Chapter 1: Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6About the Envinsa Software Developer Kit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Software Developer Kit Inventory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Software Developer Kit Package Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

About this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Organization of this Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Chapter 2: Getting Started with Envinsa Development. . . . . . . . . . . . . . . . . . . . . . . . . . 10Planning for Application Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Customer-Hosted or MapInfo-Hosted Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Using the Envinsa API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11WSDL-Generated Stub Classes or Envinsa Client API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Web-Based and Standalone Client Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Access to the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Additional Application Design Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Compiling and Running the Services Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13How to Get a Development Project Up and Running . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Development Workflow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Chapter 3: Client Java API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Overview of the SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Developing Applications with WSDL Stub Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Developing with the Web Services Client API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

How to Work with the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24How to Use the Client API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

What is a Service Message? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25How to Construct a Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26How to Submit a Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26How to Work with a Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28How to Handle Errors – SOAP Fault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29How to Handle Errors – XLS ErrorList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29How to Obtain Results from a Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31How to Work with Geometries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31How to Use MapInfo Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34How to Work with Coordinate Reference Systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35How to Intercept and Debug SOAP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Security Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Client Developer Guide Table of Contents

Security Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Adding Security Measures to Your Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Digital Signatures (XML-DSIG). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Encryption (XML-ENC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Setting the Client Application Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Setting Required Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

HTTP and SOAP Protocol Security Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Implementing HTTP Basic Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Asynchronous Communication with Web Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Asynchronous Classes and API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Use Cases and Sample Code for Asynchronous Communication . . . . . . . . . . . . . . . . . . . . . . . 48

Chapter 4: Using Envinsa Web Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Envinsa Web Controls Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Mapping Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Default Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Integrating the Mapping Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Using the Mapping Control API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Geocoding Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Default Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Integrating the Geocoding Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Using the Geocoding Control API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Mobile Device Location Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Default Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Integrating the Mobile Device Location Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Using the Mobile Device Location Control API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Route Locations Control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Configuration and Default Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Integrating the Route Locations Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Using the Route Locations Control API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Route Preferences Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Default Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Integrating the Route Preferences Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Using the Route Preferences Control API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Route Instructions Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Default Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Integrating the Route Instructions Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Using the Route Instructions Control API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Search Preferences Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Default Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Integrating the Search Preferences Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Using the Search Preferences Control API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Search Result Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Default Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Integrating the Search Result Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Envinsa Location Platform 4.0

© 2006 MapInfo Corporation. All rights reserved. 4 Envinsa40_JavaClientDev_Guide.pdf

Client Developer Guide Table of Contents

Using the Search Result Control API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Integrating Web Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Control Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Web Controls and Data Beans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Configuring Web Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91The Envinsa Web Services Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96The Configuration API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Localizing Web Controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Creating a Sample Geocode Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Chapter 5: Enhancing Envinsa Web Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Extending an Existing Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Adding a New Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Adding a new Element to an Existing Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Adding a new Attribute to an Existing Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Modifying the Configuration to Support your Extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Sample Configuration Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Chapter 6: miTrip Application Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Installation and Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Software Requirements and Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Envinsa Requirements for miTrip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Installing miTrip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Configuring miTrip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Importing Existing miTrip Code to WebSphere Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Using the miTrip Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Step-by-Step Instructions for Using miTrip. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123miTrip Application Limitations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

miTrip Architectural Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Web Controls in miTrip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Step-By-Step Application Implementation of miTrip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Set up your IDE Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128Create the Application JSP Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128Create the JSF Backing Beans for the JSP Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Define the Navigation Rules in faces-config.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Building and Deploying An Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Appendix A: Country Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Appendix B: Supported Coordinate Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

Supported Coordinate Reference Systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Widely Used EPSG Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Further Supported EPSG and MAPINFO Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145



1
Introduction
Welcome to the MapInfo® Envinsa™ Location Platform Client Developer Guide. This guide provides instructions for installing and using the Envinsa Software Development Kit (SDK) for the Java™ platform. It is written specifically for developers designing and creating applications based on MapInfo Web Services.

Based on core Web Services standards like XML, SOAP, UDDI, and WSDL, the Envinsa SDK combines technology, tools, and core runtime infrastructure that can be deployed to create applications using Envinsa Services. The Envinsa SDK includes the client API, a sample application (miTrip), core libraries, API documentation, Java, and XML service examples. Also included are Envinsa Web Control plug-ins (JSF components) and samples that can be easily integrated into your IDE. .

In this section:

About the Envinsa Software Developer Kit . . . . . . . . . . . . . . 7About this Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Client Developer Guide Chapter 1: Introduction

About the Envinsa Software Developer Kit

The Envinsa Location Platform Software Development Kit (SDK) lets developers rapidly create location-enabled applications and integrate location information into critical enterprise applications and systems. The Envinsa SDK provides functionality to create and deliver new, custom, location-enabled applications. For example, Envinsa-enabled applications could be used to:

• Analyze and compare information, such as geographic sales distribution over time.• Integrate with customer-facing systems and workflows, such as allowing call center

representatives to easily locate a caller and quickly find the nearest product or service.

These are just a few examples of the functionality that can be designed with the SDK. Refer to the Product Guide for more examples of key business applications that you can design using the Envinsa SDK Envinsa Services.

There are separate Envinsa SDKs for the Java platform and the Microsoft .NET Framework.

Software Developer Kit InventoryThe Software Developer Kit includes the following:

• Client API• Runtime Libraries• JavaDocs API References (for J2EE/J2SE platforms)• NDoc API References (for .NET Framework)• Runable Java sample code (for J2EE/J2SE platforms)• Runable C# and VB.NET sample code (for .NET Framework)• Sample Application with source code (miTrip)• Web Controls (JSF components) for integration into WebSphere Developer Studio (for J2EE/

J2SE platforms)• Web Controls for integration into WebSphere Developer Studio• Class Diagrams (located in docs/classdiagrams)

Software Developer Kit Package RequirementsThe Developer Kit installation requirements and procedure are described in the SDK Install Guide, which is available with the Developer Kit. This section highlights a few requirements that are specific to the SDK.

Before you install the Developer Kit Package, do the following:

• Install a supported IDE. The recommended IDEs are WebSphere Studio 5.1.2 or Rational 6 IDE.

• Deploy your Web application server to test and run your Web application. If you installed Envinsa Web Services and chose the Typical install option, then Tomcat 5.5.9 was automatically deployed. If you are using a different supported Web application server, you must deploy this independently.




About this Guide

This document describes how to work with the Envinsa SDK. It is written for the application developer who will use the Envinsa SDK to design and deploy location-enabled applications. This book describes: how to get started with Envinsa application development, application design considerations, Envinsa-provided productivity tools, how to use the API, security considerations, and the miTrip sample application that is provided with Envinsa.

This book does not describe details of individual Envinsa Services or Tools. Refer to the Related Documents on page 9 for a description of the related materials in the Envinsa documentation set.

Organization of this DocumentWhat will this book cover?

• Chapter 1: Introduction (this chapter) provides a brief introduction to the Envinsa SDK and Client Developer Guide.

• Chapter 2: Getting Started with Envinsa Development describes the decisions and choices you have when developing and deploying your application. This includes planning steps, using productivity tools (Web controls), compiling and running service samples, and getting your project up and running.

• Chapter 3: Client Java API includes an overview of the SDK and describes specific topics on using the API (including requests, responses, and error handling). Security concepts are also discussed.

• Chapter 4: Using Envinsa Web Controls describes how to use and configure the controls, perform common tasks, and explains the architecture and concepts that will guide you in developing Envinsa applications.

• Chapter 5: Enhancing Envinsa Web Controls describes how to customize Envinsa productivity tools (Web Controls). This chapter expands on the concepts discussed in Chapter 4 and describes how to create your own Web Controls, enhance the existing Web Controls, and support your enhancements using custom configuration and data.

• Chapter 6: miTrip Application Tutorial describes installing and using the miTrip sample application. This chapter also describes how the miTrip application is developed and implemented using the Envinsa Web Controls, and provides a detailed description of how specific features are implemented in the miTrip sample applications. You can use this information as a model for designing and deploying your own applications.

• Appendix A: Country Codes provides a list of all the country codes that are associated with the Envinsa 4.0 Location Platform. This information is used by several Envinsa Services and for batch geocoding.

• Appendix B: Supported Coordinate Systems provides a table of the supported coordinate systems and European Petroleum Survey Group (EPSG) and MAPINFO codes.




Related DocumentsEnvinsa Developers can also use the following books, which describe Envinsa Service capabilities and provide information on how to work with each service.

• Coordinate Geometry Service Reference• Coordinate System Transform Service Reference• Directory Service Reference• Find Location Service Reference• Gateway Service Reference• Location Utility Service Reference• Position Refine Service Reference• Presentation Service Reference• Profile Management Service Reference• Route Service Reference• Web Feature Service Reference• Web Map Service Reference

The following books may also be useful for the Envinsa Developer:

Product Guide – The Product Guide provides a product-level overview of the Envinsa Location Platform. It also contains information describing the Platform and Services and includes a glossary of terms and acronyms used by the documentation set. The Product Guide provides information that is relevant to all Envinsa users, and includes a full list of books delivered with the Envinsa documentation set.

Install Guide – The Install Guide describes the procedure for installing the Envinsa packages: Platform Services, Developer Kit, Administrator Kit, and Documentation.

Release Notes – The Release Notes are available online at www.envinsa.com. They include a list of what is new in this release, updates since the last release, known issues, and workarounds. It is stronly recommended that you review the Release Notes for the latest information about the Envinsa Location Platform Web Services and SDK.



http://www.envinsa.com

2
Getting Started with Envinsa Development
Once you have installed the Envinsa Software Developer Kit, you are ready to develop and deploy your applications.

There are a number of ways you can develop applications using the Envinsa Location Platform. Several approaches are described in this chapter.

In this section:

Planning for Application Development . . . . . . . . . . . . . . . . 11Compiling and Running the Services Samples . . . . . . . . . . 13How to Get a Development Project Up and Running . . . . . 15

Client Developer Guide Chapter 2: Getting Started with Envinsa Development

Planning for Application Development

There are several approaches you can take toward developing and deploying Envinsa applications. Each of these approaches have advantages and disadvantages and some approaches may suit your requirements better than others.

Envinsa development and deployment approaches include:

• Customer-Hosted or MapInfo-Hosted Deployment on page 11(user account, security, performance issues, and data requirement)

• Using the Envinsa API on page 11(primary way that most developers will develop applications)

• WSDL-Generated Stub Classes or Envinsa Client API on page 12(provides low-level programming interface)

• Web-Based and Standalone Client Development on page 12(Web-based development is major focus of this book)

• Access to the Application on page 13(user access, login requirements, and account management should be considered)

• Additional Application Design Considerations on page 13(applications designed mobile devices may have special requirements)

• Using Envinsa Web Controls on page 51(these Web Controls are valuable tools for Rapid Application Development)

Customer-Hosted or MapInfo-Hosted DeploymentIn a customer-hosted scenario, you (or the your organization) will deploy and hosts Envinsa Services in-house. In a MapInfo-hosted scenario, customers acquire location services from MapInfo for a fee, which is usually based on the number of transactions.

Your Envinsa Administrator and MapInfo representative considered data requirements, types of users, and security and performance requirements when deciding whether to deploy Envinsa as a customer-hosted or MapInfo-hosted solution. For data-related issues, consult with your Envinsa Data Administrator and read the Content Manager Guide. For user, accounting, performance or security-related issue, consult with your Envinsa Administrator and read the Administration Guide.

Using the Envinsa APIThe Envinsa Client Application Programming Interface (API) is the primary way that you will develop location-enabled applications. The API rewraps the stub classes to provide a more usable interface for developers. The API shields you from the details of the underlying XML syntax and SOAP protocol. For a description of developing with the Envinsa API, refer to How to Use the Client API on page 25.

The JavaDocs API References (also part of the SDK),provide complete documentation for the API. The SDK also includes runable sample code and a sample application with source code.

Web services are, by definition, platform-independent. Envinsa 4.0 also provides Web productivity tools (Web Controls) with built-in features that will help you design your custom applications more quickly. For more information, refer to Using Envinsa Web Controls on page 51.




WSDL-Generated Stub Classes or Envinsa Client APIWeb Service Definition Language (WSDL)-generated stub classes are modeled after the XML schemas for each service. The stub classes provide a low-level programming interface for the request/response messages (XML serialization and XML deserialization) between services and client applications. Third party tools can generate stub classes from WSDLs to interface with Web Services.

Note: If you plan to develop Envinsa applications using the WSDL-generated stub classes and are using the WebSphere 5.1 application server, you must use JVM 1.4.2. WebSphere 5.1 does not support WSDL-generated stubs with JVM 1.5.0.

For a further discussion of developing with WSDL stub classes, refer to Developing Applications with WSDL Stub Classes on page 18.

Web-Based and Standalone Client DevelopmentEnvinsa applications can be developed as Web-based or standalone applications.

Web-based and standalone applications are typically three-tiered, with Envinsa Services running in the middle tier between the data storage and DBMS (first tier) and the client/application (third tier).

Your decision to use Web-based versus standalone deployment may depend on how users will access the application. For example, will some processing be done within the client directly or will it be a "zero footprint" deployment?

This Client Developer Guide focuses on Web-based deployments.

Web-based applications can be built with JavaServer Pages (JSP) or optionally with JavaServer Faces (JSF) technology.

JSP enables Web developers to quickly and easily embed Java code into HTML or XML pages to create dynamic Web pages. For more information on JSP, refer to http://java.sun.com. Or more specifically, refer to http://java.sun.com/products/jsp/faq.html.

JavaServer Faces technology is a framework for building user interfaces for Web applications. JavaServer Faces technology includes:



http://java.sun.com

http://java.sun.com/products/jsp/faq.html


• A set of APIs for: representing UI components and managing their state, handling events and input validation, defining page navigation, and supporting internationalization and accessibility.

• A JavaServer Pages (JSP) custom tag library for expressing a JavaServer Faces interface within a JSP page.

JavaServer Faces technology simplifies building user interfaces for JavaServer applications. Developers can quickly build Web applications by: assembling reusable UI components in a page; connecting these components to an application data source; and wiring client-generated events to server-side event handlers. For more information on JSF, refer to http://java.sun.com/j2ee/javaserverfaces/. Or more specifically, refer to http://java.sun.com/j2ee/javaserverfaces/reference/faqs/index.html.

Access to the ApplicationYou need to consider the types of users who will access the application and how the users will access the application. For example, the application might provide public access for anyone with no login required, or it might require a login. You may also need to consider how user accounts are created and managed and whether user-specific profiling is needed. The application may use its own authentication scheme, such as a single-login. This is recommended.

Additional Application Design ConsiderationsSome additional considerations when developing an application are described here.

• Consider special requirements of PDA and phone-based applications. The limited screen space on a PDA or phone device may dictate how much information and what size and format of map you can effectively display. If you do display a map, the MapDisplay/Low format would be more appropriate for PDA or phone devices. Also, phone devices may have limited or no support for JavaScript.

• Determine the type of client using the application, for example, PC/PDA/WAP-phone Browsers, Java Phones (J2ME/MIDP), using Applets or a Java Standalone application. This will impact the design and framework to use.

• Consider the user interface flow, functionality, and appearance on all devices to be supported. This can vary greatly between the most and least powerful devices.

• Analyze expected load, importance of scalability, and determine a suitable architecture and framework.

• Start with the design and implementation of the most simple device or browser, for example, XHTML.

Compiling and Running the Services Samples

The Client SDK contains many small code samples in Java and XML for each Web Service.

In order to compile and run the Java code samples, you must use the Apache Ant v1.6.2 for automating the software build processes. For more information on the Apache Ant software build tool, refer to: http://ant.apache.org/. There is an Ant build.xml file in the directory <SDK_HOME>/samples/java. That same directory contains subdirectories with sample java code for each service.



http://ant.apache.org/

http://java.sun.com/j2ee/javaserverfaces/


http://java.sun.com/j2ee/javaserverfaces/reference/faqs/index.html

http://java.sun.com/j2ee/javaserverfaces/reference/faqs/index.html


You can execute the “compile” target to compile the sample codes, and execute the “run” target to launch all samples, or launch samples for individual services using the corresponding target (refer to build.xml). You must use a valid URL pointing to the Envinsa Web Services. By default, the service end-point used by all the samples are: http://silvia.mapinfo.com:9090/... You must have Internet access to silvia.mapinfo.com.

The following table shows all the targets supported within the build.xml file.

Example

The following commands compile and run the sample code for the Coordinate Geometry (Cogo) service:

%cd samples%cd java%ant compile%ant Cogo

The miTrip sample application is delivered as a deployable .war file and the source code is also included in the SDK. For more information on using miTrip, refer to miTrip Application Tutorial on page 119.

Other sample applications may be available for download from the Mapinfo Web site.

Ant Targets

Ant Target Description

compile Compiles all of the sample java code.

run Run all samples sequentially.

info Display the source directory and the ver-sion of the JVM.

Cogo Run the Cogo samples

Content Manager Run the ContentManager samples

CoordSys Run the CoordSys samples

Directory Run the Directory samples

FindLocation Run the FindLocation samples

Gateway Run the Gateway samples

Location Utility Run the Geocode and reverese geocode samples

PositionRefine Run the PositionRefine samples

Presentation Run the Presentation samples.

RouteClient Run the Route samples

WFS Run the WebFeature samples.




How to Get a Development Project Up and Running

This section describes the basics of application development with the Envinsa Location Platform.

The Envinsa 4.0 SDK runs on the Java™ 2 Platform, Enterprise Edition (J2EE™) or Java™ 2 Platform, Standard Edition (J2SE™),

You can use the advantages of an IDE to build and deploy your application. IBM WebSphere® Studio is one of the recommended integrated development environments. An IDE enables you to visually construct, test and deploy Web applications. WebSphere is built on Eclipse technology, includes design-time support for Web page and drag and drop capabilities, and supports the JavaServer Faces (JSF) framework. Refer to http://www-306.ibm.com/software/awdtools/studiositedev/ for information on the WebSphere IDE.

IBM WebSphere Application Server is also one of the supported application servers, but this will require more installation and configuration choices. You will have to use the Custom install path of the Envinsa Platform Services Package installation. For more information on installing and configuring the WebSphere application server, refer to the Envinsa Location Platform Install Guide and consult with your MapInfo Representative.

Note: If you plan to develop Envinsa applications using the WSDL-generated stub classes and are using the WebSphere 5.1 application server, you must use JVM 1.4.2. WebSphere 5.1 does not support WSDL-generated stubs with JVM 1.5.0.

You can also use Borland JBuilder, Sun Java Studio, for your IDE. Refer tohttp://www.apl.jhu.edu/~hall/java/IDEs.html#Java-IDEs for information on Java Integrated Development Environments.

You can use the Eclipse IDE, but this does not provide design-time support. Refer tohttp://www.eclipse.org).for more information.

For desktop standalone applications, the JFC/Swing graphical interface toolkit can be used. Refer to http://java.sun.com/products/jfc/index.jsp for more information. To download Java Foundation Classes, refer to http://java.sun.com/products/jfc/download.html.

Development WorkflowEnvinsa 4.0 includes Web Controls on the Java platform that support developers using the Envinsa API. The Web Controls are based on JSF and integrate directly with WebSphere Studio. For a more thorough description of these controls and examples of how to use them, refer to Using Envinsa Web Controls on page 51. These Web Controls are also used in the Envinsa sample applications. For more detailed of the miTrip sample application, refer to miTrip Application Tutorial on page 119.

To develop an application using Web Controls, follow this workflow.

1. From your IDE, create a new Java project.2. If you are using the recommended WebSphere IDE, the Web controls will be in your palette.

You can drag and drop them into application layout.3. You may want to modify some of the Envinsa-provided controls to better suit your application.

To modify Envinsa-provided Web Controls, refer to Enhancing Envinsa Web Controls on page 110



http://www-306.ibm.com/software/awdtools/studiositedev/

http://www.eclipse.org

http://java.sun.com/products/jfc/index.jsp

http://java.sun.com/products/jfc/download.html


4. Drag and drop Websphere controls and Envinsa-provided controls into your application workspace.

5. Add the business logic for your application. For example, for a FindNearest type of application, you might need to provide a drop-down list of bank categories. After the user selected a bank, you might call the Directory Service to find the nearest branch, then show the result in a table (using the Table Control) and a map (using the Map Control).



3
Client Java API
This section provides an overview of the Envinsa Location Platform SDK for Java application development.

In this section:

Overview of the SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18How to Work with the API . . . . . . . . . . . . . . . . . . . . . . . . . . . 24How to Use the Client API . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Security Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37HTTP and SOAP Protocol Security Issues. . . . . . . . . . . . . . 45Asynchronous Communication with Web Services . . . . . . 46

Client Developer Guide Chapter 3: Client Java API

Overview of the SDK

Envinsa Web Services are a suite of location-enabled services that fully conform to the SOAP, WSDL, UDDI specifications. This means that client applications are able to communicate with the Web Services over the Internet or intranet using the standard SOAP messaging protocol based on the eXtensible Markup Language (XML). The client Software Development Kit (SDK) enables applications to work with the services remotely. This is accomplished through a simple and easy-to-use Application Programming Interface (API), hiding all of the underlying details such as the XML syntax and semantics of SOAP and the Web Services. Included also with the SDK, are XML and code samples together with a real-life Web-based application to guide and assist you in building applications successfully.

The Web Services employ a request and response model based on the SOAP protocol using HTTP as the transport. Service requests and responses are SOAP messages governed by corresponding Web Service Definition Language (WSDL) definition and XML schema design of the services. Each service message carries a SOAP Envelope and a Body (header is not used). The Body contains an OpenLS XLS document with a common header and content of one or more requests or responses, which vary from service to service. The following diagram presents a pictorial view of the Web Service message structure:

While the Envinsa Services are designed to communicate via the SOAP request/response protocol, the services are also deployed with a built-in adapters (filters) that support the HTTP Get/Post protocol, as required by the OpenLS and OGC specifications. Note that HTTP Post cannot transmit most encrypted messages. So if you use HTTP Post, the only security you can implement is user name and password encryption.

For more information on the security issues related to the SOAP and HTTP protocols refer to HTTP and SOAP Protocol Security Issues on page 45.

Developing Applications with WSDL Stub ClassesApplications can either handle service request and response messages with their own logic or make use of the client stub classes (artifacts) generated from the WSDL of the service.

Since Envinsa 4.0 is compliant with the Web Services Interoperablity (WSI) standard, you can develop applications using the client stub classes generated from the WSDL of a Web Service. To do this, you will need additional tools (for example, Apache Axis’s wsdl2java) bundled with a commercial SOAP processor. These tools produce Java mappings according to the types, attributes, and hierarchical structure of the XML schemas that define the WSDL. The main purpose of the stubs classes is to




provide a programming interface for composing and publishing request messages (XML serialization) and parsing response messages (XML deserialization). The stub classes are modeled after the XML schemas.

Note: If you plan to develop Envinsa applications using the WSDL-generated stub classes and are using the WebSphere 5.1 application server, you must use JVM 1.4.2. WebSphere 5.1 does not support WSDL-generated stubs with JVM 1.5.

Development with stub classes may not be advisable, because stub classes reflect the object representation of the schema, not the application model for a specific business domain. There may also be some security considerations when developing with WSDL. For these reasons, there are advantages to developing your applications using the Envinsa Services client API.

Apache Axis 1.2.11. Generate the stubs using Axis WSDL2Java tools. An Ant script is used to generate the stubs

and create the client jar file. Customize the properties to reflect your environment. Run the ant script.

2. Create a new application project using a java IDE. Include the generated client jar into the project (include Axis 1.2.1 jars as well).

3. Use the package defined in the package mapping section in the Ant script to reference the stubs.

<?xml version="1.0"?><project name="Envinsa v4.0 - Client" basedir=".">

 <property name="axis.lib" value="D:/xml-axis-1_2_1/lib"/> <property name="src.out" value="d:/temp/src"/> <property name="SERVICE" value="cogo"/> <property name="ONLINEWSDL" value="http://localhost:8080/Cogo/services/Cogo?wsdl"/> <path id="client.classpath">

<fileset dir="${axis.lib}"> <include name="*.jar"/> </fileset>

<fileset dir="${src.out}"><include name="*.jar"/>

</fileset></path>

<target name="makeclient">

<mkdir dir="${src.out}"/><delete includeEmptyDirs="true" quiet="true">

<fileset dir="${src.out}" includes="**/*"/></delete>






<taskdef resource="axis-tasks.properties" classpathref="client.classpath"/>

<axis-wsdl2java url="${ONLINEWSDL}" output="${src.out}" serverSide="false" all="false" verbose="false" timeout="-1" testcase="false" wrapArrays="true">

<mapping namespace="http://www.opengis.net/xls"

package="com.mapinfo.miaware.xls"/><mapping namespace="http://www.opengis.net/gml"

package="com.mapinfo.miaware.gml"/><mapping namespace="http://www.w3.org/1999/xlink"

package="com.mapinfo.miaware.xlink"/><mapping namespace="http://www.w3.org/2000/svg"

package="com.mapinfo.miaware.svg"/><mapping namespace="http://www.mapinfo.com/xls"

package="com.mapinfo.miaware.mixls"/><mapping namespace="http://www.mapinfo.com/mxp"

package="com.mapinfo.miaware.mixls"/><mapping namespace="http://www.mapinfo.com/xls/wsdl"

package="com.mapinfo.miaware.ws.${SERVICE}"/><mapping namespace="http://www.mapinfo.com/locationutility"

package="com.mapinfo.miaware.ws.locationutility"/><mapping namespace="http://www.mapinfo.com/route"

package="com.mapinfo.miaware.ws.route"/><mapping namespace="http://www.opengis.net/ogc"

package="com.mapinfo.miaware.ogc"/><mapping namespace="http://www.opengis.net/wfs"

package="com.mapinfo.miaware.ws.webfeature.wfs"/><mapping namespace="http://www.mapinfo.com/wfs"

package="com.mapinfo.miaware.ws.webfeature"/></axis-wsdl2java>

<javac destdir="${src.out}"><classpath refid="client.classpath"/><src path="${src.out}"/><include name="**"/>

</javac><jar jarfile="${src.out}/${SERVICE}client.jar" basedir="${src.out}">

<include name="**/*.class"/></jar><echo message="Client stubs is created - ${src.out}/${SERVICE}client.jar"/

></target>

</project>

IBM WebSphere Application Server 5.1To work with WSDL directly using WebSphere Application Server 5.1, follow these steps:

1. Generate the stubs using WebSphere WSDL2Java tools. An Ant script is used to generate the stubs and create the client jar file. Customize the properties to reflect your environment. Run the ant script.




2. Create a new application project using a Java IDE. Include the generated client jar in the project (include WebSphere jars as well).

3. Use the package defined in the package mapping section in the Ant script to reference the stubs.

<?xml version="1.0"?><project name="Envinsa v4.0 - Client" basedir=".">

 <property name="websphere.lib" value="C:/WebSphere51/client_jars/lib"/> <property name="src.out" value="d:/temp/src"/> <property name="SERVICE" value="cogo"/> <property name="ONLINEWSDL" value="http://localhost:8080/Cogo/services/Cogo?wsdl"/> <path id="client.classpath">

<fileset dir="${websphere.lib}"> <include name="*.jar"/> </fileset>

<fileset dir="${src.out}"><include name="*.jar"/>

</fileset></path>

<target name="makeclient">

<mkdir dir="${src.out}"/><delete includeEmptyDirs="true" quiet="true">

<fileset dir="${src.out}" includes="**/*"/></delete><taskdef name="WSDL2JavaTask"

classname="com.ibm.websphere.ant.tasks.WSDL2Java" classpathref="client.classpath"> </taskdef>

<WSDL2JavaTask url="${ONLINEWSDL}" output="${src.out}" role="client" container="none" genjava="overwrite" testcase="false" verbose="false"> <mapping namespace="http://www.opengis.net/xls" package="com.mapinfo.miaware.xls"/>

<mapping namespace="http://www.opengis.net/gml" package="com.mapinfo.miaware.gml"/>

<mapping namespace="http://www.w3.org/1999/xlink" package="com.mapinfo.miaware.xlink"/>

<mapping namespace="http://www.w3.org/2000/svg" package="com.mapinfo.miaware.svg"/>

<mapping namespace="http://www.mapinfo.com/xls" package="com.mapinfo.miaware.mixls"/>




<mapping namespace="http://www.mapinfo.com/mxp" package="com.mapinfo.miaware.mixls"/>

<mapping namespace="http://www.mapinfo.com/xls/wsdl" package="com.mapinfo.miaware.ws.${SERVICE}"/>

<mapping namespace="http://www.mapinfo.com/locationutility" package="com.mapinfo.miaware.ws.locationutility"/>

<mapping namespace="http://www.mapinfo.com/route" package="com.mapinfo.miaware.ws.route"/>

<mapping namespace="http://www.opengis.net/ogc" package="com.mapinfo.miaware.ogc"/>

<mapping namespace="http://www.opengis.net/wfs" package="com.mapinfo.miaware.ws.webfeature.wfs"/>

<mapping namespace="http://www.mapinfo.com/wfs" package="com.mapinfo.miaware.ws.webfeature"/> </WSDL2JavaTask> <javac destdir="${src.out}">

<classpath refid="client.classpath"/><src path="${src.out}"/><include name="**"/>

</javac><jar jarfile="${src.out}/${SERVICE}client.jar" basedir="${src.out}">

<include name="**/*.class"/></jar><echo message="Client stubs is created - ${src.out}/${SERVICE}client.jar"/

></target>

</project>

IBM WebSphere Developer Studio 5.1To work with WSDL directly using WebSphere Developer Studio 5.1, follow these steps.

1. Launch WebSphere Developer Studio 5.12. Create a new Web Service client project. Select File > New > other Web Service > Web

Service Client.3. Optionally, turn off the WSDL validation. This will ignore any errors on WSDL validation.4. Follow the wizard to set the Web Service runtime.Select WebSphere V5/WebSphere v5.1 server

5. Enter the WSDL URL of the service endpoint.For example, http://tnt-envinsa:9095/Cogo/services/Cogo?wsdl

6. Set namespace to Java package mappings.Check "Define custom mapping for the namespace to package" check box, input the mapping pairs (Reference the recommended list of mappings in the Ant script for WebSphere application server).

7. Click Finish to generate the stubs.8. Use the package defined in the package mapping screen to reference the stubs.

Developing with the Web Services Client APIThe Envinsa Services client API is a thin layer that rewraps the stub classes to provide a more intuitive interface to developers. Another advantage of using the API rather than WSDL-generated stub classes, is that API-developed applications can be shielded from future incompatible changes. With WSDL development, code is integrated directly with the generated stubs.




The following diagram shows the relationships between the API, the stubs classes, and the underlying Apache Axis SOAP processor that supports the Web Services.

The Service Message ClassService messages are represented by a class called ServiceMessage, which carries information (client ID, password). There are also classes, such as Address, that are shared among services to facilitate exchange of information. A ServiceMessage object can contain one or more service request or response objects, such as GeocodeRequest or GeocodeResponse, which encapsulate information specific to a service. Stub objects are created by the toXLS() method of ServiceMessage to enable Apache Axis to perform XML serialization and submit the request message to the designated service. In return, the response message is deserialized into stubs objects by Axis. These stubs objects are used to construct the corresponding Web Service response object so information can be retrieved through the API.

The Service URLEach of the services have a distinct end-point URL in the form of http://<host>:<port>/<service-name>/services/<service-name>. For example, http://silvia.mapinfo.com:9090/Directory/services/Directory for the Directory Service running at port 9090 on a server named silvia.mapinfo.com. These service URLs are required by the SDK to work with the Web Services. The Web Services administrator of a customer deployment is responsible for publishing these URLs to their developers, either as a simple list, or in a private or public UDDI repository, with a known address.

There is a demo registry server. To locate this, start the miTrip demo application on:http://oberon.mapinfo.com:8080/mitrip40, select UDDI Service Locator. This produces the UDDI Service Locator dialog (for demonstration purpose only). Then select Lookup in UDDI to see the endpoints of the services currently in use.



http://oberon.mapinfo.com:8080/mitrip40


Applications can use the JAX-R API to discover and obtain information about the services including their end-points. Refer to subsequent sections of this guide for steps and examples.

Developers can use the Dynamic Proxy or DII to invoke a service. The SDK objects can be used to produce the necessary input parameters for the service call. Refer to the JAX-RPC documentation for detailed steps.

Service WSDL FilesDevelopers can access the WSDL file of a specific service by adding the suffix ?wsdl to the end-point of the service location. For example, assuming the end-point of the LocationUtility Web Service ishttp://silvia.mapinfo.com:9090/LocationUtility/services/LocationUtility, you can use this URL to access the WSDL file: http://silvia.mapinfo.com:9090/LocationUtility/services/LocationUtility?wsdl.

How to Work with the API

The Web Services are request and response message-based. You should prepare a request message for a certain service and send it to the endpoint of the service. If the endpoint accepts the request, a response message is sent back.

Each request and response message is an XLSType object, conforming to OpenLS/XLS standards. The XLSType object includes a Header and one or more Bodies. The Header holds the information that applies to all of the Bodies in this object, such as the username and password for authentication. The Body includes the actual service request and response.

Each Body can have only one service request for the request message, or one service response for the response message. Only the request-related information in the XLSType object should be considered when it is used in the request message, and only the response-related information in the XLSType object should be concerned when it is used in the response message.

The Envinsa SDK acts as a helper. It provides developers with a simple way to create the XLSType object for the service request and navigate the XLSType object for the service response.

When working with the API, you will use the ServiceMessage object. Once the ServiceMessage object is created, you can call the toXLS() method of the ServiceMessage object to convert it into an XLSType object that is used as the request and response message.

The following are the five main steps to use the API.

1. Get the Service Proxy. Use the URL of the service endpoint to create a service locator. From the locator, you can get the service proxy.

2. Create the ServiceMessage for request. Use the default constructor to create an instance of the ServiceMessage. Fill in the necessary information, and add one or more service requests to the ServiceMessage.

3. Invoke the service. Use the toXLS() method of the ServiceMessage to convert the message into the XLSType stubs object, and invoke the operation from the service proxy by passing the XLSType object as the parameter.



http://java.sun.com/xml/jaxrpc/index.html

http://silvia.mapinfo.com:9090/LocationUtility/services/LocationUtility?wsdl


4. Create the ServiceMessage for response. Use the response XLSType object to construct the ServiceMessage for the response.

5. Process the response. Check the ErrorList in the ServiceMessage to see whether an Error has occurred. Retrieve the information from each of the response objects in the ServiceMessage and cast them to the specific service response. Each response may have ErrorList in it to indicate an error.

Normally a services request/response will be handled in a synchronous manner. However, there are some situations in which asynchronous communication is preferable. For example, if the request requires a great deal of processing and might potentially take a long time to return a result. For details, refer to Asynchronous Communication with Web Services on page 46.

How to Use the Client API

Use the samples in this guide and provided with the SDK to assist you in working with the client API. Reference the JavaDocs provided in the Envinsa SDK for any specific definitions and information about the API. You may want to refer to the appropriate Service Reference guide for details about each of the services. The OpenLS/XLS schemas are available in the <SDK_HOME>/xsd directory, for advanced developers, as a reference.

Refer to the following samples:

• What is a Service Message?• How to Construct a Request• How to Submit a Request• How to Work with a Response• How to Handle Errors – SOAP Fault• How to Handle Errors – XLS ErrorList• How to Obtain Results from a Response• How to Work with Geometries• How to Use MapInfo Extensions• How to Work with Coordinate Reference Systems• How to Intercept and Debug SOAP Messages

What is a Service Message?In OpenLS/XLS, each XLSType object represents a service request or service response. In the API, there is a ServiceMessage that is equivalent to the XLSType object in OpenLS/XLS, but has a more simplified API. When you need an XLSType object, you can create a ServiceMessage, fill in the specific service requests, then call the toXLS() method of the ServiceMessage to create the XLSType object.

The ServiceMessage is a place holder for the service requests and responses. More than one request or response of any one service may be added into the ServiceMessage.




How to Construct a RequestTo construct a request message, use the default constructor to create a ServiceMessage object. Fill in the information that is required for the request, such as the client name and password, if authentication is required

ServiceMessage serviceMessage = new ServiceMessage();serviceMessage.setClientName("demo");serviceMessage.setClientPassword("demo");

Create the service-specific request and fill in the request content based on the requirements of the application (street geocoding versus gazetteer). Add the service request into the ServiceMessage object.

Address addressStreet = new Address("US");addressStreet.setCountrySubdivision("NY");addressStreet.setMunicipality("New York");

StreetAddress streetAddress = new StreetAddress("43 West 83rd. Street");addressStreet.setStreetAddress(streetAddress);

GeocodeRequest geocodeRequestStreetAddress = null;GeocodeRequestStreetAddress = new GeocodeRequest("Geocode", "4.0", "id", addressStreet);

serviceMessage.addRequest(geocodeRequestStreetAddress);

Use the toXLS() method of the ServiceMessage object to create the XLSType stub object.

XLSType xlsRequest = serviceMessage.toXLS() ;

How to Submit a RequestGet the end-point of the required service. This is the URL, and can be established by querying a UDDI service or asking the administrator of the Web Service. The miTrip sample application contains an example of how to query the server (the com.mapinfo.miaware.mitrip.WebServiceLocator class). The following table shows the URLs of the core Web Service endpoints.

Service URL Endpoints

Service Name URL

Cogo http://silvia.mapinfo.com:9090/Cogo/services/Cogo

Coordsys http://silvia.mapinfo.com:9090/CoordSys/services/CoordSys

Directory http://silvia.mapinfo.com:9090/Directory/services/Directory

Find Location http://silvia.mapinfo.com:9090/FindLocation/services/FindLocation

Gateway http://silvia.mapinfo.com:9090/Gateway/services/Gateway

Location Utility http://silvia.mapinfo.com:9090/LocationUtility/services/LocationUtility

Position Refine http://silvia.mapinfo.com:9090/PositionRefine/services/PositionRefine

Presentation http://silvia.mapinfo.com:9090/Presentation/services/Presentation

Route http://silvia.mapinfo.com:9090/Route/services/Route




The Web Map Service is an OGC standard service and is not supported by the Envinsa Client API. For more information, refer to the Web Map Service Reference. The Presentation Service also supports WMS layers. Refer to the Presentation Service Reference for more information.

The following table shows the service name, class name of the locator of each service, the class name of the service proxy, and the operation for each service.

The service proxy is a stub class. This class is the Java representation of the Web service operations described in the WSDL port type element. It is a Java interface defining the methods used by the Java client to interact with the Web service (generated by a WSDL to Java mapping tool such as Apache Axis's WSDL2Java or IBM WSDK's WSDL2Client). Using the Envinsa API, the simplest way to get the service proxy is to use the Locator class.

The Locator class works as a factory of the service proxy for each Web Service, and is part of the stubs (each service has a Locator class). The name of the Locator class for each service can be found in Table 4. The Operation is the method of the service proxy that you can use to invoke the service from the client. The name of the operation is service-specific. The Operation column in Table 4 shows the operation name of each service proxy.

Use the end-point of the service to create the Locator for the service. From the Locator instance, you can create the service proxy, and call the operation.

String url = “http://mapinfo.com/ LocationUtility/services/LocationUtility”;//Create a locator of the LocationUtility service.LocationUtilityServiceLocator geocodeLocator = new LocationUtilityServiceLocator();//Create a service proxy for the LocationUtility service.

Web Feature http://silvia.mapinfo.com:9090/WebFeature/services/WebFeature

Service Locator Classes

Service Name Locator Class NameService Proxy Class Name Operation

Cogo CogoServiceLocator Cogo perform

Coordsys CoordsysServiceLocator Coordsys transform

Directory DirectoryServiceLocator Directory perform

Find Location FindLocationServiceLocator FindLocation perform

Gateway GatewayServiceLocator Gateway perform

Location Utility LocationUtilityServiceLocator LocationUtility perform

Position Refine PositionRefineServiceLocator PositionRefine getPOIAddress

Presentation PresentationServiceLocator Presentation perform

Route RouteServiceLocator Route getRoute

Web Feature WebFeatureServiceLocator WebFeature perform

Service URL Endpoints

Service Name URL




LocationUtility location = geocodeLocator.getLocationUtility(new URL(url));

Use the proxy to invoke the operation.

//Call the operation of the proxy to invoke the service.XLSType xlsResponse = location.perform(xlsRequest);

In the previous example, the Locator class of LocationUtililty service is LocationUtilityServiceLocator. From the instance of the Locator (geocodeLocator in sample code above), the service proxy can be returned. The name of the service proxy class is LocationUtility. The operation perform() is called on the service proxy to invoke the service.

Advanced developers can use the Dynamic Proxy or DII to invoke the end-point of the services, because the XLSType object for the request and response can be created through the ServiceMessage object. You can use the created XLSType object to invoke the services any way you like.

How to Work with a ResponseTo construct a response message, use the response XLSType object to create the ServiceMessage object. From this ServiceMessage object, you can check whether an error has been encountered when processing the request. The following example shows how you can check whether an error has occurred, and when the specific request was processed.

serviceMessage = new ServiceMessage(xlsResponse);Response[] responses = serviceMessage.getResponses();

for (int k=0; k<responses.length; k++) { if (responses[k].hasError()) {

//Handle the error here } else { //Cast to original type. See table-5 for details. GeocodeResponse response = (GeocodeResponse) responses[k]; … }

}

If a request is processed successfully, you can retrieve the response information from the ServiceMessage object.

Each response must be caste to the original type to retrieve the correct response information. The following table shows the class name of the response and the corresponding request being used.

Request and Response Classes

Service Name Request Name Response Name

Cogo CogoRequest CogoResponse

Coordsys CoordsysRequest CoordsysResponse

Directory DirectoryRequestDirectoryGetCapabilitiesRequest

DirectoryResponseDirectoryGetCapabilitiesResponse

Find Location FindLocationRequest FindLocationResponse




How to Handle Errors – SOAP FaultWhen calling a Web Service at the SOAP processor level, an error may occur. In that case, a SOAP fault may be generated and returned as a RemoteException (such as Invalid document due to syntax errors). Developers must handle this exception in their applications.

try { … //Invoke the service XLSType xlsResponse = location.perform(xlsRequest); …}catch(RemoteException e){ //Handle the SOAP fault System.out.println("Service failed:"+e.getMessage());}

How to Handle Errors – XLS ErrorListIf errors are encountered when the request message is being processed by a service, the error is contained within an ErrorList and returned in the response message. You can retrieve the corresponding error code, error message, and severity level of the error. The following table shows all of the Error Codes and their descriptions.

Gateway GatewayRequestHandleRequest

GatewayResponseHandleResponse

Location Utility GeocodeRequestReverseGeocodeRequest

GeocodeResponseReverseGeocodeResponse

Position Refine PositionRefineRequest PositionRefineResponse

Presentation GetPortrayMapCapabilitiesRequestPortrayMapRequest

GetPortrayMapCapabilitiesResponsePortrayMapResponse

Route DetermineRouteRequestDetermineRouteMatrixRequest

DetermineRouteResponseDetermineRouteMatrixResponse

Web Feature GetCapabilitiesRequestDescribeFeatureTypeRequestGetFeatureRequest

GetCapabilitiesResponseDescribeFeatureTypeResponseGetFeatureResponse

Error Code Descriptions

Error Code Description

RequestVersionMis-match

Version of Request Schema not supported.

ResponseVersionMis-match

Version of Response Schema not supported.

Request and Response Classes

Service Name Request Name Response Name




The following table shows all the severity levels and their descriptions.

There are two places where the ErrorList may exist. One is at the ServiceMessage level (Message Level) and the other is at the response level (Response Content Level). An error in the response level indicates an error related to the processing of the request. The error in the ServiceMessage level indicates a general error, such as mismatched version. You must check both levels before processing the information from the response message.

Message Level

if (serviceMessage.hasError()) {

ValueNotRecognized Element content or attribute value not recognized. Although the document is well formed and valid, the element/attribute contains a value that could not be recognized and therefore could not be used by the service processing the message.

NotSupported Element or attribute not supported. Although the document is well formed and valid, an element or attribute is present that is consistent with the rules and constraints con-tained in the OpenLS specification, but is not supported by the service processing the message.

Inconsistent Element content or attribute value inconsistent with other elements or attributes. Although the document is well formed and valid, according to the rules and constraints contained in the OpenLS specification the content of an element or attribute is incon-sistent with the content of other elements or their attributes.

OtherXml Other error in an element content or attribute value. Although the document is well formed and valid, the element content or attribute value contains values that do not conform to the rules and constraints contained in the OpenLS specification and is not covered by other error codes. The Error message attribute should be used to indicate the nature of the problem.

DeliveryFailure Message Delivery Failure. A message has been received that either probably or defi-nitely could not be sent to its next destination. Note: if severity is set to Warning then there is a small probability that the message

was delivered.

SecurityFailure Message Security Checks Failed. Validation of signatures or checks on the authentic-ity or authority of the sender of the message have failed.

Unknown Unknown Error. Indicates that an error has occurred that is not covered explicitly by any of the other errors. The Error message attribute should be used to indicate the nature of the problem.

Table 7:Severity Levels

Severity Level Description

Warning This indicates that an error occurred, but other parts of the request were processed as expected.

Error This indicates that there is an unrecoverable error in the request and no part of the request will be processed.

Error Code Descriptions

Error Code Description




System.out.println("Highest severity: " + serviceMessage.getHighestSeverity()); Error[] errors = serviceMessage.getErrors(); for (int i=0; i<errors.length; i++) { System.out.println(errors[i].getSeverity()); System.out.println(errors[i].getMessage()); }}else { …}

Response Content Level

if (responses[k].hasError()) { System.out.println("Highest severity: " + responses[k].getHighestSeverity()); Error[] errors = responses[k].getErrors(); for (int i=0; i<errors.length; i++) { System.out.println(errors[i].getSeverity()); System.out.println(errors[i].getMessage()); }}else { …}

How to Obtain Results from a ResponseWhen a request is successful, an XLSType object is returned. You can construct a ServiceMessage from this XLSType object. If the service responses are returned, a response array can be retrieved from the ServiceMessage. Each response has to be cast to its original type before retrieving any service-specific information. Request and Response Classes on page 28 shows the class name to which the response should be cast.

if(responses[i] instanceof GeocodeResponse ){GeocodeResponse response = (GeocodeResponse) responses[i];GeocodeResponseList geocodeResponseList[] = response.getGeocodeResponseList(); ...}

For specific service responses, not all features returned may be available. The availability depends on service request. It is good practice to check items retrieved from the response for null values before using them.

How to Work with GeometriesA coordinate is represented as a DirectPosition (two dimensions are used). Some geometries require that a distance or an angle be specified. The units of the measure used by the Web Services are defined in the com.mapinfo.miaware.clientsdk.uom.DistanceUnit class for linear units and the com.mapinfo.miaware.clientsdk.uom.AngleUnit class for angular units. The coordinate reference system for a geometry is referenced using the srsName. Both the DirectPosition and Geometries have the srsName attribute. However, it is recommended that the srsName is always used at the geometry




level. One exception is for the CircleByCenterPoint, where the srsName can only be used at the DirectPosition of the center point. For more information on geometries, refer to the GMLFactory class and the com.mapinfo.geometry package.




The following examples show how to create each of the geometries:

//Instantiate a geometry factoryGMLFactory gmlFactory = GeometryUtils.getXLSGMLFactory();

//Create a point by using the geometry factoryPoint pointA = gmlFactory.newPoint(gmlFactory.newDirectPosition(-74.00566, 40.70983));

//Create a point by using GeometryUtils classPoint pointB = GeometryUtils.newPoint(-74.00566, 40.70983, "EPSG:4326");

//Create a CircleByCenterPointCircleByCenterPoint circle = gmlFactory.newCircleByCenterPoint();DirectPosition pos = gmlFactory.newDirectPosition(-74.00566, 40.70983);pos.setSrsName("EPSG:4326");circle.setCenter(pos);circle.setRadius(new Length(DistanceUnit.M.getValue(), 100));

//Create a CircularArcCircularArc circularArc = gmlFactory.newCircularArc();circularArc.setCenter(gmlFactory.newDirectPosition(-74.00566, 40.70983));circularArc.setOuterRadius(new Length(DistanceUnit.M.getValue(), 200));circularArc.setInnerRadius(new Length(DistanceUnit.M.getValue(), 100));circularArc.setStartAngle(new Angle(AngleUnit.DecimalDegrees.getValue(), 30));circularArc.setEndAngle(new Angle(AngleUnit.DecimalDegrees.getValue(), 120));circularArc.setSRS("EPSG:4326");

//Create an EllipseEllipse ellipse = gmlFactory.newEllipse();ellipse.setCenter(gmlFactory.newDirectPosition(-74.00566, 40.70983));ellipse.setMajorAxis(new Length(DistanceUnit.M.getValue(), 100));ellipse.setMinorAxis(new Length(DistanceUnit.M.getValue(), 60));ellipse.setRotation(new Angle(AngleUnit.DecimalDegrees.getValue(), 30));ellipse.setSRS("EPSG:4326");

//Create a LinearRingLinearRing linearRing = gmlFactory.newLinearRing();linearRing.addCoord(gmlFactory.newDirectPosition(-74.00566, 40.70983));linearRing.addCoord(gmlFactory.newDirectPosition(-74.00666, 40.70983));linearRing.addCoord(gmlFactory.newDirectPosition(-74.00766, 40.70983));linearRing.addCoord(gmlFactory.newDirectPosition(-74.00566, 40.70983));

//Create a PolygonPolygon polygon = gmlFactory.newPolygon();polygon.setExterior(linearRing);polygon.setSRS("EPSG:4326");

Your application may need to pass geometry objects between different Envinsa Services. This may also mean that the application must convert an object from one geometry type to another. The geometry factory included with the SDK provides an easy way of creating all the geometry types used by the SDK and enables you to convert and pass geometries among Envinsa Services. Refer to the Geometry Support Table for a list and description of geometries used within the Envinsa SDK.

For example, the WebFeature Service or Directory Service returns an EnvelopeType object. You must convert this to an Envelope object to display on a map using the Presentation Service. In other cases, you may need to convert between a Point object and Envelope object.




The GeometryUtils.getXLSGMLFactory() method of the GeometryUtils class allows you to use the XLS implementation to create geometries. By using this factory, you can create all the geometry types used by the Envinsa SDK.

For example, to create an Envelope bounding box:

Envelope bBox = GeometryUtils.getXLSGMLFactory().newEnvelope(featureCollectionEnvelope)

The following table lists all the geometries used in the geometric calculations, and transforming geometry coordinates from one coordinate system to another. For more information on geometry types, refer to the Coordinate Geometry Service Reference and the Coordinate System Transform Service Reference.

The GeometryUtils class also has two static methods that supply a convenient way to create Point and Envelope.

How to Use MapInfo ExtensionsMapInfo extended functionality has been bundled into the classes where the name of the classes have an Ex suffix. For example, the XLS standard address class is Address, and the corresponding MapInfo extended class is AddressEx. This extension is inherited from the Address class and has extended functions contained within. Whenever the extended functions are required, instantiate a corresponding extension class instead of the standard class and provide the necessary information for that extension.

AddressEx addressStreetEx = new AddressEx("US");addressStreetEx.setCountrySubdivision("NY");addressStreetEx.setMunicipality("New York");

StreetAddress streetAddress = new StreetAddress("43 West 83rd. Street");addressStreetEx.setStreetAddress(streetAddress);

GeocodeRequest geocodeRequestStreetAddress = null;GeocodeRequestStreetAddress = new GeocodeRequest("Geocode", "4.0", "id", addressStreetEx);

Geometry Support

Geometry Name Description

CircleByCenterPoint XLS Circle

CircularArc GML CircularArc

Ellipse XLS Ellipse

Envelope GML Envelope

LinearRing GML LinearRing

LineString GML LineString

MultiPolygon GML MultiPolygon

Point GML Point

Polygon GML Polygon




The ServiceMessage also has an extension ServiceMessageEx. Only when the ServiceMessageEx is used for a request should the ServiceMessageEx be used for the response.

When MapInfo extensions are used in a service request, corresponding MapInfo extensions may be returned in the response. For this to happen, you must cast the standard object into the extended object. Only then can the extension information be retrieved. It is good practice to check if extensions are used when processing a response. The following examples check for an extended address object in a geocode response:

GeocodedAddress[] geocodedAddress = geocodeResponseList[i].getGeocodedAddress();...if (geocodedAddress[m].getAddress()!=null) {

//Retrieve the attribute carried by the standard addressString postcode = geocodedAddress[m].getAddress().getPostalCode();//Checking for extensionsif (geocodedAddress[m].getAddress() instanceof AddressEx) {

AddressEx addressEx = (AddressEx)geocodedAddress[m].getAddress();//Retrieve the attribute carried by the extended addressString placeName = addressEx.getPlaceName();...

}...

}...

For more information on the MapInfo extended functionality, refer to the appropriate Service Reference.

How to Work with Coordinate Reference SystemsAn Envinsa application may need to process either data (geometries) or service requests and responses from different coordinate systems. For example, data from different sources may need to be combined or processed. Or the application may require that data (geometries, maps) must be presented in a particular coordinate system (even if the source data was in a different coordinate system). Envinsa applications can transform the data into a consistent coordinate system for presentation.

The Coordinate System Transform Service can transform geometries from one coordinate system to another. Refer to the Envinsa Coordinate System Transform Reference for descriptions and examples of using this Envinsa Service.

All Envinsa Services that process geometries will ensure that all data is in a consistent coordinate reference system and perform transformations internally, if necessary. Geometries returned in responses are, by default, in the same coordinate system as the source data.

The Envinsa application must use the setSRS method to set the coordinate reference system for each geometry. The srsName (Spatial Reference System Name) format must be either the European Petroleum Survey Group (EPSG) code or the MAPINFO code. The srsName text must contain a coordinate reference system namespace and code, separated by a colon. For example, a geometry in WGS 84 (srsName="EPSG:4326") could look like this:

Point point = null;...point.setSRS(“EPSG:4326”);




For a list and description of the most commonly used EPSG codes, refer to Appendix B: Supported Coordinate Systems.

For a complete list and more information on EPSG codes, visit the following Web site:http://www.epsg.org/.

An application may use the ServiceMessageEx class and setResponseSRSName method to control in what projection the data is to be returned. To find out in which projection a particular geometry is in use the getSRS method.

How to Intercept and Debug SOAP MessagesFor debugging, you may want to see the SOAP message exchanged between the client and the Web Services. Envinsa supplies a TCPMonitor utility that allows you to capture the messages exchanged between the client and the Web Services. The Envinsa SDK supplies a script to launch the utility:

<envinsa_java_sdk>\tools\debug\TCPMonitor.bat (on Windows systems)<envinsa_java_sdk>/tools/debug/TCPMonitor.sh (on Unix/Linux systems)

For more information about the TCPMonitor, refer to the Apache Axis manual at http://ws.apache.org/axis/java/user-guide.html.

The default Listen Port used by the script is 8088. The default service host is localhost. The default service port is 9090. You can change them to reflect their environment.

To use the TCPMonitor utility, you need to change the host and port in the service endpoint in the locator to the host on which the TCPMonitor is running, the port to which the TCPMonitor is listening. You also must ensure that the host and port of the TCPMonitor points to the target service correctly. You can change these parameters by clicking Stop, filling in the new values and clicking Start again.

To use the TCP Monitor utility program, follow the following steps:

1. After starting TCPMonitor, select the Admin tab.2. In the Listen Port # field, specify a valid TCP/IP port number that can be used on the TCP

Monitor's machine.3. In the Target Hostname field, enter the name of the machine that is running Envinsa. This

machine can be anywhere on the Internet.4. In the Target Port # field, enter the TCP/IP port number of the Web server (or servlet-container)

that is hosting Envinsa.5. Click the ADD button.6. A new tab panel will be displayed. This new panel has the name of the TCP/IP port number

that was entered in step 2.7. On the newly added tab panel, check the XML FORMAT checkbox.8. Click SWITCH LAYOUT to make the Envinsa client direct its requests to the TCP Monitor

program, which will act as a "pass-through" to Envinsa, such that the XML text of both the request and response will be displayed.

When using the TCP monitor in conjunction with a client application that uses the Envinsa API, users will need to switch the URL of the target Envinsa Service they are using with that of a different URL that targets the TCP monitor for the machine and port.



http://ws.apache.org/axis/java/user-guide.html

http://ws.apache.org/axis/java/user-guide.html

http://www.epsg.org/



For example, if the client application uses the following URL to access MapInfo-hosted Envinsa Services:

http://silvia.mapinfo.com:9090/LocationUtility/services/LocationUtility

you must switch the machine and port to access the TCP monitor as follows (assuming that the Listen port is number 7777):

http://localhost:7777/LocationUtility/services/LocationUtility

Security Support

The Web Services security is built on foundational technologies such as SOAP, WSDL, XML Digital Signatures, and XML Encryption. It ensures the authentication, privacy, integrity, confidentiality, and security of the Web Services.

There are several levels of security available through the Envinsa SDK:

Basic Authentication – A username and password must be included in the request. The requester must have a user account registered to the Web Services to which they are sending requests.

Signing – A digital signature may be included in the request. Only those requests containing a valid, registered certificate are processed.

Encryption – Requests may be encrypted so they can not be read if intercepted.

Note: For a complete description of security issues, and information on how to manage security through the Enterprise Manager, refer to the Administration Guide.

Security ConceptsIn a secure system you need to ensure that a request or response is:

• Private and confidential – This is done by encrypting the message.• From a trusted source – This is done by authenticating the message using digital signatures. • Intact and has not been tampered with – Using certificates and digital signatures can also

insure the integrity of the message.

EncryptionEncryption is the process of making the content of a message unreadable. The message is decrypted at the receiving end to make it readable again. There are two types of encryption; symmetric and asymmetric.

Symmetric encryption uses the same key, called a session key, to send and receive messages. The drawback with using symmetric encryption is that anyone who discovers the session key can decrypt the message.




Asymmetric encryption uses a public key and a private key. A public key is an encryption tool that, combined with a private key that is derived from the public key, can be used to encrypt messages. These keys are created as a matching pair. A public key is used to encrypt a message; a private key is used to decrypt it. The drawback to this method is that it is slower than symmetric encryption.

The technology that the Web Services rely on for encryption uses a hybrid encryption system, which combines both symmetric and asymmetric techniques. In a hybrid system both participants, at the beginning of every transaction, use a session key to encrypt the message and a private key to encrypt the session key. The session key is a symmetric encryption tool that gets used to encrypt the remainder of the transaction. A new session key is used for each new transaction. This system relies on a public key that is openly distributed – it can be sent via e-mail or posted to a network server. In order to ensure the authenticity of the public key, it includes a digital certificate.

Authentication Using Certificates and SignaturesAuthentication means proving identity. An application needs to ensure that a user is who they say they are. This is done through the use of certificates and signatures.

A digital certificate is a way of proving that you are who you say you are when performing transactions on the Web. A digital certificate contains a user name, serial number, expiration date, a copy of the certificate holder’s public key (used for encrypting messages), and the signature of the certificate issuer so that the recipient can verify that the certificate is real.

A digital signature is used to authenticate the identity of the sender of a message, and to ensure that a message arrived intact. It is used with both encrypted and non-encrypted messages.

Adding Security Measures to Your ApplicationYou can add these security measures to your application:

• Digital Signatures (XML-DSIG)• Encryption (XML-ENC)

When adding any of the following security measures to your application, the following sequence must be followed:

1. The client application creates an instance of the service object. For example, for the Cogo service the instance will look like:CogoServiceLocator locator = new CogoServiceLocator();Cogo service = locator.getCogo();

2. The client application creates an instance of the Security object.3. The client application sets the required parameters for signing or encryption.4. The client application calls the enableSecurity method and passes the service locator into that

method:security.enableSecurity(locator);

5. The client sends a request using the proper method (for example, the perform method):XLSType xlsResponse = service.perform(message.toXLS());




The following is the UML sequence diagram for the Web Services security using the API:

AuthenticationThe request must have a valid username and password for the Web Services that the request is sent to. The following example shows how to add a username and password to the request:

ServiceMessage message = new ServiceMessage();message.setClientName("demo");message.setClientPassword("demo"); . . . XLSType xlsResponse = service.perform(message.toXLS());

When an invalid username or password is sent to the service, and the service is configured to authenticate the request, the service sends back a SOAPFault response with the fault code 10007.msg.peer.site.denied and the fault string Request Access Denied.

Digital Signatures (XML-DSIG)Please refer to the following sections for further information on implementing digital signatures:

• Setting the Client Application Environment• Setting Required Libraries




Sign RequestBefore you can send a signed request to a Web Service, the service must be configured to accept this kind of request. By default, a service does not accept signed requests. To sign a request you will need to perform the following steps:

1. Create an instance of the Security class.2. Set keystore information. This information is necessary to find the keystore file and obtain

access to it. The API offers a helper method in the Security class to set these parameters in one method (line 5 in the following example).

3. Set signature parameters. The parameters should be set as: the client alias name in the keystore, password to client's private key, and the XML-DSIG implementation. The API offers a helper method in the Security class to set these parameters in one method (line 6 in the following example).

4. Apply security on the instance of the Web Service class (line 9 in the following example).1. ServiceMessage message = new ServiceMessage ();2. message.setClientName("demo");3. message.setClientPassword("demo"); . . . 4. Security security= new Security(); 5. security.setKeystoreParameters("C:/keystore.jks", "secret");6. security.setSignatureParameters("client", "password",

Security.TRANSLATOR_APACHE);7. CogoServiceLocator locator = new CogoServiceLocator();8. Cogo service = locator.getCogo();9. security.enableSecurity(locator);10. XLSType xlsResponse = service.perform(message.toXLS());

Verify ResponseBefore a Web Service can sign a response, it must be configured to do so. By default, the services do not sign responses. To verify a response, you will need to perform the following steps:

1. Create an instance of the Security class.2. Set keystore information – This information is necessary to find the keystore file and obtain

access. The API offers a helper method in the Security class to set these parameters in one method (line 5 in following example).

3. Set signature parameters – The parameters should be set as: the client alias name in the keystore, password to the client's private key, and XML-DSIG implementation. The API offers a helper method in the Security class to set these parameters in one method (line 6 in following example).

4. Set verification parameters – The parameters should be set as: the user alias in the keystore, and XML-DSIG implementation (line 7 in the following example).

5. Apply security on the instance of the Web Service class (line 9 in the following example).1. ServiceMessage message = new ServiceMessage ();2. message.setClientName("demo");3. message.setClientPassword("demo"); . . . 4. Security security= new Security(); 5. security.setKeystoreParameters("C:/keystore.jks", "secret");6. security.setSignatureParameters("client", "password",

Security.TRANSLATOR_APACHE);7. security.setVerificationParameters("demo",

Security.TRANSLATOR_APACHE);




8. CogoServiceLocator locator = new CogoServiceLocator();9. Cogo service = locator.getCogo();10. security.enableSecurity(locator);11. XLSType xlsResponse = service.perform(message.toXLS());

If verification of the client's signature fails on the Web Service server side, the client application receives the following message:

Failed to decrypt request message - 30008.secyrity.error.verify.failed

If verification of the service's signature fails on the client side, the client application receives the following message:

javax.xml.rpc.JAXRPCException: Failed to process secured response:30008.secyrity.error.verify.failed

Encryption (XML-ENC)Please refer to the following sections for further information on implementing encryption:

• Setting the Client Application Environment• Setting Required Libraries

Encrypt RequestBefore you can send an encrypted request to a Web Service, the service must be configured to accept this kind of request. By default, a service does not accept encrypted requests. To encrypt a request you need to perform the following steps:

1. Create an instance of Security class.2. Set keystore information – This information is necessary to find the keystore file and obtain

access. The API offers a helper method in the Security class to set these parameters in one method (line 5 in the following example).

3. Set encryption parameters – The parameters should be set as: user alias in the keystore, xpath to the element to be encrypted and XML-ENC implementation. The API offers a helper method in the Security class to set these parameters in one method (line 6 in the following example). Also, the API contains two predefined xpaths: XPATH_XLS and XPATH_XLS_HEADER. The first one points to the XLS root element. When this xpath is used, the entire XLS element is encrypted. The second one points to the Header element, where the username and password are located.

4. Apply security on the instance of the Web Service class (line 9 in the following example).1. ServiceMessage message = new ServiceMessage ();2. message.setClientName("demo");3. message.setClientPassword("demo"); . . . 4. Security security= new Security(); 5. security.setKeystoreParameters("C:/keystore.jks", "secret");6. security.setEncryptionParameters("demo", Security.XPATH_XLS_HEADER,Security.TRANSLATOR_XSS4J);

7. CogoServiceLocator locator = new CogoServiceLocator();8. Cogo service = locator.getCogo();9. security.enableSecurity(locator);10. XLSType xlsResponse = service.perform(message.toXLS());




Decrypt ResponseBefore you can receive an encrypted response from a Web service, the service should be configured to accept this kind of response. By default, a service does not encrypt responses. To receive an encrypted response, you need to perform the following steps:

1. Create an instance of Security class.2. Set keystore information – This information is necessary to find the keystore file and obtain

access. The API offers a helper method in the Security class to set these parameters in one method (line 5 in the following example).

3. Set decryption parameters – The parameters should be set as: the client alias in the keystore, password to the client private key, and XML-ENC implementation. The API offers a helper method in the Security class to set these parameters in one method (line 6 in the following example).

Note: The request will be signed as well.

4. Apply security on the instance of the Web service class (line 9 in the following example).1. ServiceMessage message = new ServiceMessage ();2. message.setClientName("demo");3. message.setClientPassword("demo"); . . . 4. Security security= new Security(); 5. security.setKeystoreParameters("C:/keystore.jks", "secret");6. security.setDecryptionParameters("client","password",Security.TRANSLATOR_XSS4J);7. CogoServiceLocator locator = new CogoServiceLocator();8. Cogo service = locator.getCogo();9. security.enableSecurity(locator);10. XLSType xlsResponse = service.perform(message.toXLS());

If the decryption process fails, the client application receives an error message, containing the following:

"javax.xml.rpc.JAXRPCException: Failed to process secured response:" + specific message based on implementation.

Setting the Client Application EnvironmentIn order to set up the secure client application environment, the following steps must be performed on the client side:

1. Generate a key pair for a client application. The following example generates a key pair using a keytool utility (bundled with the SDK) with the following parameters: • Keystore File – keystore.jks. The keystore file that will be created in the directory where

you run the command.• Alias – client.• Password to keystore – secret.• Keystore Type – KS.• Password to private key – password.• Key Algorithm – RSA.• Dname – CN=client,OU=Applications,O=Company,L=Toronto,S=Ontario,C=CA.




keytool.exe -genkey -keystore keystore.jks -alias client -storepass secret -storetype JKS -keypass password -keyalg RSA -dname "CN=client,OU=Applications,O=Company,L=Toronto,S=Ontario,C=CA"

2. Register the client application certificate with the Web Service. You need to export the client certificate into a separate file and send it to the Web Services administrator. The following example shows how to export the certificate from keystore (generated in step 1.) to file using the keytool utility with the following parameters:• Keystore File – keystore.jks.• Alias – client.• File – client.cer. The file name where the certificate will exported.• Password to keystore – secret.• Keystore Type – JKS.

keytool.exe -export -keystore keystore.jks -alias client -file client.cer -storepass secret -storetype JKS

3. Obtain a user certificate. When you get a user certificate you need to import it into the keystore file. The following example shows how to import the user certificate to the keystore (generated by the Web Service administrator) using the keytool utility with the following parameters:• Keystore File – keystore.jks.• Alias – Envinsa user alias.• File – demo.cer. The file name where the user's certificate is stored.• Password to keystore – secret.• Keystore Type – JKS.

keytool.exe -import -noprompt -keystore keystore.jks -alias demo -file demo.cer -storepass secret -storetype JKS

Setting Required LibrariesTake the following library settings into consideration when adding security to your application:

• The security jar file (securityimpl.jar) – This jar file is required if you want to use security with the Web Services.

• JCE libraries – JCE has been integrated into the Java 2 SDK, Standard Edition, v1.4 and v1.5. Therefore, you do not need a separate download if you are running v1.4 and later.

• JCE provider – Due to a limitation with the RSA algorithm in the JCE package, the JCE provider is required. The SDK is bundled with the Bouncy Castle JCE provider. For JDK 1.4 you need the bcprov-jdk14-118.jar library. For JDK 1.5, Bouncy Castle bcprov-jdk15-129.jar is also supported.

The Envinsa SDK supports the following XML-DSIG and XML-ENC implementations.

Apache XML Security

Apache XML Security is the default implementation for the Web Services. This implementation supports only XML-DSIG, which means it can be used only for signing a request and verifying of the response. This implementation is represented by the com.mapinfo.miaware.clientsdk.security.Security.TRANSLATOR_APACHE constant.




The following example shows how to set Apache XML security in the SDK:

security.setTranslatorImplClass(Security.TRANSLATOR_APACHE);

or

security.setSignatureParameters("clientsdk", "password", Security.TRANSLATOR_APACHE);

IBM XML Security Suite

IBM XML Security Suite (XSS4J) supports both XML-ENC and XML-DSIG. (XSS4J requires the xss4j.jar, and are.jar files). This implementation is represent by the com.mapinfo.miaware.clientsdk.security.Security.TRANSLATOR_XSS4J constant.

security.setTranslatorImplClass(Security.TRANSLATOR_XSS4J);

or

security.setSignatureParameters("clientsdk", "password",Security.TRANSLATOR_XSS4J);

or

security.setEncryptionParameters("demo", Security.XPATH_XLS_HEADER,Security.TRANSLATOR_XSS4J);

VeriSign Trust Services Integration Kitt

The VeriSign Trust Services Integration Kit (TSIK) supports both XML-ENC and XML-DSIG. (TSIK requires the tsik.jar file). This implementation is represent by the com.mapinfo.miaware.clientsdk.security.Security.TRANSLATOR_VERISIGN constant.

security.setTranslatorImplClass(Security.TRANSLATOR_VERISIGN);

or

security.setSignatureParameters("clientsdk", "password",Security.TRANSLATOR_VERISIGN);

or

security.setEncryptionParameters("demo", Security.XPATH_XLS_HEADER,Security.TRANSLATOR_VERISIGN);

Note: There is a known issue when using the security implementation of TSIK in combination with Axis. As a result, a response may not be encrypted. This situation is transparent to the client application but there is no known workaround. This issue depends on the Web Service’s environment. The security implementation on top of TSIK fails to properly handle the security elements in the SOAPMessage. Because of this, a service can not check the signature and will not encrypt the response. Instead, it returns the response in clear text. This behavior can be verified using the TCP monitor. Refer to How to Handle Errors – SOAP Fault on page 29.




HTTP and SOAP Protocol Security Issues

All Envinsa Services can communicate via the SOAP request/response protocol. SOAP requests can use various methods of encryption. If the SOAP request/response is encrypted, the service must be encrypted in the same way.

To support the HTTP Get/Post protocol (to conform with OpenLS and OGC specifications), some Envinsa Services are deployed with built-in adapters (filters). These adapters are transparent to you the developer and do not require any attention or configuration. If you communicate with Envinsa Services via HTTP Get/Post, the only security mechanism you can use is HTTP Basic Authentication. HTTP Basic Authentication restricts access to Web services based on user name and password. Since HTTP Post cannot transmit encrypted messages, encrypted security mechanisms are not possible with the HTTP protocol.

Implementing HTTP Basic AuthenticationEnvinsa OpenLS compliant Services are:

• Directory• Gateway• Location Utility• Presentation• Route

EnvinsaOGC compliant Services are:

• WFS• WMS

For both OpenLS compliant and OGC compliant Services, the username and password are passed with the HTTP request to perform Basic Authentication. This validates the user name and password, and restricts Web service access to authorized users.

To enable HTTP Basic Authentication for both Envinsa OpenLS and OGC compliant Services, those services must be configured with encryption disabled. Encryption for Envinsa Services is disabled (Off) by default. If the Envinsa administrator uses Enterprise Manager to enable encryption for an Envinsa OpenLS or OGC compliant Service, then HTTP cannot be used to communicate with that service. In that scenario, only SOAP requests can be used.

Note: For a description of the HTTP Basic Authorization scheme, refer to http://www.faqs.org/rfcs/rfc2617.html.

The user account must be created before Basic Authentication is activated. Use Enterprise Manager to create, modify, and manage user accounts. A user account can be propagated from the console peer to one or many remote Web peers. Refer to the Administration Guide for instructions on using the Enterprise Manager.

The following MapInfo Services are neither OpenLS nor OGC compliant. These services accept SOAP messages only.

• Coordinate Geometry• Coordinate System Transform



http://www.faqs.org/rfcs/rfc2617.html

http://www.faqs.org/rfcs/rfc2617.html


• Find Location• Position Refinement• Profile Management

Asynchronous Communication with Web Services

The typical synchronous request/response communication with Web services is described in How to Work with the API on page 24. However, there are some situations in which asynchronous communication is preferred. For example, if the request requires a great deal of processing and might take a long time to return a result. For example, a complex FindLocation request. Asynchronous communication lets you:

• Submit a request to the Web service and get immediate confirmation that the process has started on the server side. The user can then perform other actions while the request is processing. This is especially useful if the process will potentially take a long time to complete.

• Check status of the server-side process.• Terminate running process if you no longer want the result.• Attache listeners (callbacks) so the Web service will initiate communication with the client

when processing is finished.• Get result when the process is finished.

WebLogic Users

If you are using WebLogic 8.1 and asynchronous communication, you must use the SUN JVM (which is provided by WebLogic). If WebLogic is configured with the jrockit JVM, communication with Web Services will fail with a NullPointerException wrapped into AxisFault. To resolve this problem:

1. Shut down the server.2. Locate startup script that launches Weblogic server and set "JAVA_HOME" property to point

SUN JVM <BEA_DIR>/jdk14x_xx instead of <BEA_DIR>/jrockit81_14x_xx. 3. Restart the server.




Asynchronous Classes and APIThe Asynchronous classes are shown in the following illustration:

The API is described as follows.

public class AsyncService { //Constructor public AsyncService(Service locator, String endpointURL)

// Methods public AsyncCallStatus asyncCall(AsyncCallListener listener, XLSType request, int timeOut, int pullinterval) throws Exception {...}

public AsyncCallStatus asyncCall(URL listener, XLSType request, int timeOut) throws Exception {...}

public AsyncCallStatus asyncCall(XLSType request, int timeOut, int timeInCache) throws Exception {...}

public String getEndPointURL()...} public String getName() {...}}

public class AsyncCallStatus { // Methods public boolean isFailed() throws Exception {...} public boolean isFinished() throws Exception {...} public void terminate() throws Exception {...} public EMException getError() throws Exception {...} public ServiceMessage getResponseMessage() throws Exception {...} public String getStatus() throws Exception {...} public int getTimeOut() {...} public int getTimeInCache() {...} public long getStartTime(){...} public long getEndTime(){...} public String getProcessID(){...}}

public interface AsyncCallListener




{ // Methods public void asyncCallback(XLSType request, AsyncCallStatus process);}

Use Cases and Sample Code for Asynchronous CommunicationThere are three basic ways to make an asynchronous call in Envinsa Java API. These are described in the following scenarios and code samples.

Sample 1In this scenario, you have full control over when to check the call status and when to retrieve the response. When making the asynchronous call, you would supply a request object to return a AsynchronousCallStatus object, check the status of the call, and retrieve the response ServiceMssage by calling methods of the AsynchronousCallStatus object.

The following sample code illustrates this scenario:

//Create a request messageServiceMessage requestMsg = getRequestMessage(user, passwd);

//Get the service endpointCoordSysServiceLocator locator = new CoordSysServiceLocator();AsyncService asyncCoordSys = new AsyncService(locator, serviceUrl);

//Make an asynchronous callAsyncCallStatus callStatus = asyncCoordSys.asyncCall(requestMsg.toXLS(),

TIMEOUT, TIMEINCACHE);

//Wait until process finishedint attempts = 10; //number of attemptswhile (callStatus.isFinished()==false && attempts>0) {

System.out.println("Checking status " + (11 - attempts));//Do something also, here simply sleeping...Thread.sleep(TIMEPULL);attempts--;

}

//Process response messageString remoteProcessStatus = callStatus.getStatus();if (remoteProcessStatus.equals(AsyncCallStatus.STATUS_FINISHED)) {

ServiceMessage responseMsg = new ServiceMessage(callStatus.getXLSResponse());System.out.println("Use case 1: It's returned. "

+ publishResponse((CoordSysResponse)responseMsg.getResponses()[0]));}else {

if (callStatus.isFailed()) {System.out.println("Error: " + callStatus.getError().getFaultMessage());

}}




Sample 2In this scenario, you implement a callback interface. Unlike in Sample 1, all pulling work is done by the API. When making the asynchronous call, you supply a request object and an object that implements the AsynchronousCallListener interface. You do not need to monitor the status of the call. Instead, when the response is ready, the callback method in AsynchronousCallListener interface is automatically triggered.

The following sample code illustrates this scenario:

//Create a request messageServiceMessage requestMsg = getRequestMessage(user, user);

//Get the service endpointCoordSysServiceLocator locator = new CoordSysServiceLocator();AsyncService asyncCoordSys = new AsyncService(locator, serviceUrl);

//Make an asynchronous callAsyncCallStatus callStatus = asyncCoordSys.asyncCall(this, requestMsg.toXLS(), TIMEOUT, TIMEPULL);

//Process response message//The response will be processed in the asyncCallback() method.System.out.println("Use case 2: It's returned. ");...//The callback interface implementationpublic void asyncCallback(XLSType response, AsyncCallStatus process){ try { //Processing the response if (response!=null) { ServiceMessage responseMsg = new ServiceMessage(response); System.out.println("Use case 2: callback performed - " + publishResponse((CoordSysResponse)responseMsg.getResponses()[0])); } //Handling errors else { if (process.isFailed()) { System.out.println("Error: " + process.getError().getFaultMessage()); } } } catch (Exception ex) { ex.printStackTrace(); }}

Sample 3In this scenario, you supply a service endpoint. When making the asynchronous call, you supply a request object and a URL of an active service endpoint (this does not have to be a Web service, but it must be able to understand the response of Envinsa Web Services). The call will return immediately. As soon as the response is ready, it will be pushed to the URL automatically.

The following sample code illustrates this scenario.




//Create a request messageServiceMessage requestMsg = getRequestMessage(user, user);

//Get the service endpointCoordSysServiceLocator locator = new CoordSysServiceLocator();

AsyncService asyncCoordSys = new AsyncService(locator, serviceUrl);

//Make an asynchronous callAsyncCallStatus remoteProcess = asyncCoordSys.asyncCall(new URL(lisenerUrl),

requestMsg.toXLS(), TIMEOUT);

//Process response message//The response will be processed in the listener endpoint.System.out.println("Use case 3: It's returned. ");



4
Using Envinsa Web Controls
Envinsa productivity tools (Web Controls) are a collection of visual components that use the Envinsa Client API to communicate with Envinsa Services. Envinsa Web Controls allow you to take advantage of built-in functionality for Rapid Application Development (RAD). These Web Controls provide the generic user interface components that are common to most applications.

The Web Controls also provide a learning aid for the Envinsa SDK, demonstrating how it can be used to build visual Web applications.

In this section:

Envinsa Web Controls Overview. . . . . . . . . . . . . . . . . . . . . . 52Mapping Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Geocoding Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Mobile Device Location Control . . . . . . . . . . . . . . . . . . . . . . 65Route Locations Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Route Preferences Control . . . . . . . . . . . . . . . . . . . . . . . . . . 74Route Instructions Control . . . . . . . . . . . . . . . . . . . . . . . . . . 77Search Preferences Control . . . . . . . . . . . . . . . . . . . . . . . . . 80Search Result Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Integrating Web Controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Configuring Web Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Creating a Sample Geocode Application . . . . . . . . . . . . . . . 98

Client Developer Guide Chapter 4: Using Envinsa Web Controls

Envinsa Web Controls Overview

Envinsa 4.0 includes Web Controls to aid developers using the Envinsa API. These Web Controls are based on JSF, and integrate directly into your IDE. You can use these Web Controls to build new applications or enhance existing applications. The advantages of using Envinsa Web Controls are:

• They provide built-in functionality to help you easily and quickly add location-based functionality to business applications.

• Functionality can be added without coding changes.• Source code is provided allowing the Web Controls to be modified and extended to suit your

application business needs.

The Envinsa Web Controls are built using the Java Server Faces framework (JSF) and can be integrated into your IDE, such as IBM WebSphere® Studio. In order to run an application developed using Web Controls you must deploy them on an application server such as Tomcat or WebSphere Application Server. The controls support Rapid Application Development (RAD), so you can use RAD options in your testing environment. You can use the Web Controls in two ways:

• Add controls to the application by editing the JSP page.• Add controls to the application by dragging and dropping from the IDE palette, if available.

If WebSphere Studio is used, the drag and drop option can be added to the Web perspective palette by creating and deploying a custom plug-in. Refer to the SDK Install Guide, distributed with the Developer Kit, for details on integrating Web Controls with your IDE. After installation, start the IDE. You will see the MapInfo palette category with the Envinsa Web Controls and be able to drag and drop the Web Controls from the palette into your JSP pages.

Envinsa Web Controls use a common configuration file in XML format. The configuration is loaded and cached in the application state. Some of this information can be defined in the configuration file and, if required, can be overridden at the time of execution. Developers can edit the configuration file using any text editor. For detailed information on configuring the behavior of Web Controls, refer to Configuring Web Controls on page 91.

The Web Controls follow the Model View Controller (MVC) design pattern. For more details on how to extend the Web Controls refer to Enhancing Envinsa Web Controls on page 110.




The following Web Controls are bundled with the Envinsa Client SDK:

Additional Advanced Web Controls may be available for download from the MapInfo Web site. Those additional controls are not used in the miTrip sample application, but can be used in the additional Envinsa sample applications that are available from the MapInfo Web site. You can use these controls to more rapidly develop your own applications.

The Envinsa Web Controls provided with the SDK are described in the following sections:

• Mapping Control on page 55• Geocoding Control on page 60• Mobile Device Location Control on page 65• Route Locations Control on page 69• Route Preferences Control on page 74

Available Web Controls

Web Control Description and Functionality

Mapping Control Provides the basic map viewing capability. This is central to any Envinsa-based application.This control also provides capabilities for managing and navigating a map. This includes: zoom in, zoom out, zoom to scale (specified map width) re-center, and pan in given direction.

Geocoding Control Geocodes based on street address, street intersection address, or Places/Point of Interest. After the geocoding operation, a selection list of candidates is displayed and the user can select one of them.

Mobile Device Location Control

Locates the position of a mobile device.Takes a mobile device ID, locates it using Gateway Service and shows the reverse geocoded address of the location. For example, miTrip presents a drop-down list of phone numbers, allows the user to select a number, then calls the Gateway Service to determine the location.

RouteLocations Control Extends the Geocoding Control and provides the information that can be used to set up start, end, or via points in the RoutePreferences control.

RoutePreferences Con-trol

Provides the criteria for generating a route request. For example, in the miTrip sam-ple application, this control allows you to specify the criteria used for route prefer-ences (such as fastest or shortest routes). The RoutePreferences Control receives the endpoints input from the RouteLocations Control and triggers the route request action. Note: This also could be set externally by another location/geocoding control at

the application level and used as a location/address collector/receiver.

RouteInstructions Con-trol

Displays the route instructions as specified and requested by the RoutePreferences Control.For example, driving directions are shown as text, route summary, and turn-by-turn instructions (optionally with turn icons). The user can select the entire route with the “Route Map” button or can select just one segment of the route.

SearchPreferences Control

Performs a search around a location with specified preferences such as POI cate-gory, radius, maximum number of candidates. Select the Search button to perform a Find Nearest request, based on specified criteria. The list of nearest POI can be sent to the SearchResult and the Mapping Control for display.

SearchResult Control Following a Find Nearest request, this control displays a list of information for each Point of Interest returned by the Find Nearest search.




• Route Instructions Control on page 77• Search Preferences Control on page 80• Search Result Control on page 85

The following diagram illustrates the basic architecture of the Envinsa Web Controls.

The miTrip sample application shipped with Envinsa provides a good model for understanding how the Web Controls can be integrated into an application. In miTrip, the RouteLocations Control is responsible for providing the start and end points. The RoutePreferences Control will send a route request, and will receive the route response. The response will be sent to the RouteInstructions Control to generate the route summary information (total time, total distance) and the directions to be displayed. The application gets these points from the Route Preferences Control and passes them to the Mapping Control to show them on the map. This flow is illustrated as follows:

The miTrip sample application is described in miTrip Application Tutorial in Chapter 6 on page 119. Other sample applications may be available for download from the MapInfo Web site at www.mapinfo.com.



http://www.mapinfo.com


Mapping Control

The Mapping Control provides the basic map viewing capability, is central to almost any Envinsa-based application, and is typically used in combination with other controls such as the Geocoding or RouteLocations Controls. The Mapping Control draws the map following a request to the Presentation Service. This control also provides capabilities for managing and navigating a map. This includes: zoom in, zoom out, zoom to scale (specified map width) re-center, and pan in any given direction using the mouse.

Some typical use cases are:

• Draw a geocoded location on a map.• Draw a route map.• Draw a map with Points of Interest (POI).• Redraw map following a pan or zoom.

Default ConfigurationDefault map values include:

• Basemap – Name of the displayed map.• Default zoom value – Used when a single overlay (point or POI) is added to the map.• Zoom factor – Defines how the zoom distance changes when zoom in/out operations are

performed.• Distance unit – A two letter abbreviation. For example, MI for mile or KM for kilometer.• Output attributes – Width, height, format, background color, transparency, content (URL or

binary).• Map boundaries or center context – The lower left x,y and upper right x,y coordinates

representing a bounding box, which is the extent of the map view.

The following section of a sample configuration file highlights these map attributes.

<PortrayMapRequest basemapName="MapDisplay/Low" zoomFactor="3" defaultZoom="1"distanceUnit="MI">

<Output width="400" height="300" format="image/png" bgcolor="000000"transparent="true" content="Data"/><Bounds llX="-74.22412255718116" llY="40.58208485212916"urX="-73.67474447891242" urY="40.94391807729767"/>

</PortrayMapRequest>

The basemapName, zoomFactor, and width and height properties are exposed at design time and can overwrite the configuration. The property zoomFactor is used in Zoom-in and Zoom-out Controls; distanceUnit and defaultZoom are also used by the MapWidth Control (refer to Mapping JSF Controls on page 56 for more information).

Note: Overwriting properties at design time will become hard-coded. You will not be able to alter these properties at execution time.

For a complete description and, sample envinsa-config.xml file, refer to Configuring Web Controls on page 91.




Integrating the Mapping ControlTo integrate the Mapping Control in your application, you need to know about the provided JSF controls, JSP tags, Mapping control files, Mapping API (Java Beans), and Mapping control interactions.

In addition to Web control files (miwebcontrols.jar, envinsaws-config.xml, etc.), the following files are required to run the Mapping Control:

• CursorIcons/*.*• images/*.*• js/*.*• skins/*• theme/mapping.css

Mapping JSF ControlsThe Mapping Control contains the following JSF controls:

• mapping – The mapping JSF control represents the map image and defines attributes for how the map will appear.

• maptoolbar – The maptoolbar JSF control represents the container for the map tools.• maptool – The maptool JSF control represents a tool on the toolbar, such as pan, zoom in,

zoom out.

• mapwidth – The mapwidth JSF control represents the distance of the map. The distance is recalculated each time a map state changes (for example, as a result of Zoom in operation). It also provides the input to change the map distance (map scale) directly.

Mapping Control JSP TagsTo start using the mapping control, first make sure that you include the declaration of the tag library in your JSP page:

<%@taglib uri="http://www.mapinfo.com/webcontrols" prefix="mi"%>

The mapping control tags are defined in the miwebcontrols.tld file, which is located under the META-INF directory in the miwebcontrols.jar file. The following tags are defined for controls: Mapping, Maptoolbar, Maptool, and Mapwidth.

If you want to use the mapping css styles, then you must include the mapping.css file to your JSP page. For example:

<LINK rel="stylesheet" type="text/css" href="theme/mapping.css" title="Style">

Mapping Tag

This tag defines the map and is the container of the maptoolbar tag. The Mapping tag contains the following attributes:

• id – The ID of the mapping control.




• imageHeight – Defines the height of the map in pixels.• imageWidth – Defines the width of the map in pixels.• imageFormat – The map image format. For example "image/jpg".• basemapName – The name of the displayed map. For example "MapDisplay/high".• zoomFactor – The zoom factor value that is used to zoom in/out the map.• defaultZoom – The map distance if a single overlay (as point or POI) is added to the map.• units – The distance units the map is using.• mapClass – The style name that is used for the map control. This style class name is defined

in the mapping.css file.• mapCanvasClass – The style name that is used for the map canvas. This style class name is

defined in the mapping.css file.• rendered – Flag indicating whether this component (and its children) should be rendered. The

expression must evaluate to a Boolean. The default value is true. If this attribute is not specified, the component will be rendered.

• value – The value attribute allows you to associate the mapping bean with the control. For details refer to Using the Mapping Control API on page 58. You can define the mapping bean as managed in the faces-config.xml:<managed-bean>

<managed-bean-name>map</managed-bean-name><managed-bean-class>

com.mapinfo.envinsa.clientutil.beans.MappingBean</managed-bean-class><managed-bean-scope>session</managed-bean-scope>

</managed-bean>

Then you can bind the control with the defined bean:<mi:mapping id="map" value="#{map}" ...>

Maptoolbar Tag

This tag defines the toolbar that is used in the mapping control. The maptoolbar is the child of the mapping tag and the parent of maptool and mapwidth tags. It contains the following attributes:

• id – The ID of the map toolbar.• toolbarClass – The style that is used in the toolbar. This style class name should is defined in

the mapping.css file.• defaultTool – The name of the tool that is used by default (pan). The default tool name has to

match one of the map tool names that are used in the Mapping Control.• skin – This is the skin of the toolbar. The skin defines tool images and styles that define

toolbar look and feel. The skins are defined in the /WebContent/skins directory. The folder name matches the skin name.

• rendered – Flag indicating whether this component (and its children) should be rendered. The expression must evaluate to a Boolean. The default value is true. If this attribute is not specified, the component will be rendered.

Maptool Tag

The mapptool tag defines tools in the toolbar like zoom in, zoom out or pan. Maptools are the children of the maptoolbar tag. It has the following attributes:

• id – The ID of the map tool.




• name – The name of the maptool. The supported map tools are Pan, Zoom-in, and Zoom-out.• rendered – Flag indicating whether this component (and its children) should be rendered. The


Mapwidth Tag

The mapwidth tag shows the current map distance in the defined units. It also allows you to change this distance directly. The Mapwidth tag is the child of the maptoolbar tag. It has the following attributes:

• id – The ID of the map width.• rendered – Flag indicating whether this component (and its children) should be rendered. The


Sample Mapping Control in JSP PageFollowing is a simple example that shows how to code a mapping control in the JSP page:

<mi:mapping id="map" units="mi" basemapName="MapDisplay/high"><mi:maptoolbar id="toolbar" defaultTool="pan" skin="standard">

<mi:maptool id="pan" name="pan" /><mi:maptool id="zoomin" name="zoomin" /><mi:maptool id="zoomout" name="zoomout" /><mi:mapwidth id="zoom" />

</mi:maptoolbar></mi:mapping>

Using the Mapping Control APIThis section describes the Mapping Control API. You need this API if there is a need to interact with the Mapping Control programmatically, for example adding a point or route geometry to the map. The Mapping Control uses the Java Beans represented in the following illustration:




Where:

• MapBean – The MapBean interface represents the map properties such as map image URL, width, and height.

• MapBeanImpl – This is the implementation of the MapBean interface that is Envinsa specific.• MapController – The MapContoller interface defines the operations on the map. The

MapController can work with the different implementations of the MapBean.• MappingBean – This is the implementation of the MapController that is Envinsa specific.• MappingFactory – This class creates the instance of MapController. For now, it is the only

instance of MappingBean.• OverlayLayers – This class allows you to display overlays on the map. This class is

referenced by the MapBean.• UIMapping - This is a JSF UIComponent class, and it represents a user interface for the

Mapping control.

Note: Refer to the Web Controls Javadoc for a detailed description of the methods and classes for the Mapping Control beans.

You can get a map controller reference using the UIMapping class or access the map controller bean through the FacesContext if you bind it using the value attribute (refer to Mapping Control JSP Tags on page 56).

FacesContext context = FacesContext.getCurrentInstance(); MapController map = (MapController) context.getApplication().createValueBinding("#{map}").getValue(context);

The following examples show how to work with the mapping API (assuming that "mapping" is the UIMapping instance).

To display geocoded location on the map:

// create point overlay, where the "point" is the Point object.Overlay overlay = new GeometryOverlay(point));

// clear the existing overlays and add a new onemapping.getMapController().getMapBean().getOverlayLayers().clear();mapping.getMapController().getMapBean().getOverlayLayers().add(overlay);

// zoom to overlay using default zoom valuemapping.getMapController().zoomToOverlay(overlay);

The zoomToOverlay makes the added overlay visible on the map (and it redraws the map).

To display route on the map:

// create route geometry overlay, where the "linestring" is the LineString object (route geometry)RouteGeometryOverlay overlay = new RouteGeometryOverlay(linestring);

// clear the existing overlays and add a new onemapping.getMapController().getMapBean().getOverlayLayers().clear();mapping.getMapController().getMapBean().getOverlayLayers().add(overlay);

// zoom to all overlays that we addedmapping.getMapController().zoomToAllOverlays();

To change the basemap of the map:

// specify a new basemap name




mapping.getMapController().changeBasemap("MapDisplay/low");

The changeBasemap method automatically redraws the map. Make sure that you do not hardcode the basemap name in the mapping tag, otherwise an application will not be able to change the basemap at runtime if required.

Geocoding Control

The Geocoding Control is used to identify a location using an address, a street intersection, or a place (such as a landmark or airport). The Geocoding Control requests are sent to the Envinsa Location Utility Service which returns the list of candidates.

A simple use case is getting a list of candidate addresses. For example:

1. The user enters an address.2. The Location Utility Service returns a list of addresses if the requested address is valid.3. The user selects the desired address from the candidate list.4. The returned address can be displayed using the Mapping Control.

The following is a sample illustration of this control:

Default ConfigurationConfiguration values include:

• Values related to the user application, such as: list of countries supported, default country, and the list of landmark types for POI.

• Close match property – If CloseMatchOnly is set to true, only those geocoded results that are close match candidates are returned. The address candidates are ranked according to how closely the input address matches the located address. For information on match criteria refer to the Location Utility Service Reference.

The following section of the sample configuration file highlights these geocoding attributes and shows the default settings.

Location Utility sample configuration:

<LocationUtility version="4.0" url="http://localhost:8080/LocationUtility/services/LocationUtility" userName="demo" userPassword="demo">

<GeocodeRequest closeMatchesOnly="false"/></LocationUtility>




Default country code is set in envinsaws-config.xml as: <Locale countryCode="US" requestLanguage="en-US" />

The supported country list will be set by the countries bean:



<managed-bean><managed-bean-name>countries</managed-bean-name><managed-bean-class>java.util.ArrayList</managed-bean-class><managed-bean-scope>session</managed-bean-scope>

<list-entries><value-class>java.lang.String</value-class><value>USA</value><value>CAN</value>

....

</list-entries></managed-bean>

The supported landmarks/places of interest categories will be set by the landmarks bean:



<managed-bean><managed-bean-name>landmarks</managed-bean-name><managed-bean-class>java.util.TreeMap</managed-bean-class><managed-bean-scope>session</managed-bean-scope>

<map-entries><value-class>java.lang.String</value-class><map-entry>

<key></key> <value>All</value>

</map-entry><map-entry>

<key>10010900</key> <value>Shopping Malls/Shopping Centers</value>


<key>10030100</key> <value>Hotels/Motels</value>


<key>10110100</key> <value>Tourist Attraction</value>


<key>10110200</key> <value>Tourist Attraction - Building</value>

</map-entry>

....

</map-entries>




</managed-bean>

For a complete description and sample envinsaws-config.xml file, refer to Configuring Web Controls on page 91.

Integrating the Geocoding ControlTo integrate the Geocoding Control in your application, you need to know about the provided JSF controls, JSP tags, Geocoding control files, Geocoding API (Java Beans), and Geocoding control interactions.

Geocoding Control JSP TagTo start using the Geocoding Control, first make sure that you include the declaration of the tag library in your JSP page:


The Geocoding Control tag is defined in the miwebcontrols.tld file and is located under the META-INF directory in the miwebcontrols.jar file. The following tag is defined for the control:

Geocoding Tag

The Geocoding tag has the following attributes:

• id – The identifier of the control tag• title – The title of this tag.• rendered – Flag indicating whether this component (and its children) should be rendered. The

expression must evaluate to a Boolean. The default value is true (component will be rendered). If this attribute is not specified, the component will be rendered.

• action – The action attribute allows you to associate a value binding expression to an action method. This will associate the action attribute with the action method. For example: <mi:geocoding id="geocoding1" title="Geocoding"action="#{pc_TestControls.doGeocodingAction}"></mi:geocoding>

Where TestControls is the JSP page name, pc_TestControls is the name of managed bean defined in the faces-config.xml, and doGeocodingAction is the name of the method from the JSP page bean. At the end of any model update initiated by the control the referenced method will be invoked. The user will be responsible for the business logic implemented by the method. For example, get the geocoded address and display it on the map.

• value – The value attribute allows you to associate the control value to a persistent (session) geocoding AddressMatchBean bean. If this attribute is not defined the control will still set/get the data in a non persistent similar object using the component get/set methods. You can define the geocoding bean as a managed bean in the faces-config.xml:<managed-bean><managed-bean-name>geocoding</managed-bean-name><managed-bean-class>com.mapinfo.envinsa.clientutil.beans.AddressMatchBean</managed-bean-class><managed-bean-scope>session</managed-bean-scope></managed-bean>

Then you can bind the control with the defined bean. For example:<mi: geocoding id="geocoding1" value="#{geocoding}" ...>




• countries – This attribute will be used only if for some reason the user doesn't want to use the default bean name "countries" for the countries bean but another name for example "mycountries". In this case the user should change the name of the "countries" bean to "mycountries" – refer to default values and configuration paragraph above. If used, the attribute will be defined as follows:<mi:geocoding id="geocoding1" title="Geocoding"countries="#{mycountries}" ></mi:geocoding>

• landmarks – This attribute will be used only if for some reason the user doesn't want to use the default bean name "landmarks" but another name, for example "mylandmarks". In this case the user should change the name of the "landmarks" bean to "mylandmarks" – refer to default values and configuration paragraph above. If used, the attribute will be defined as follows:<mi:geocoding id="geocoding1" title="Geocoding"landmarks ="#{mylandmarks }" ></mi:geocoding>




Using the Geocoding Control APIThis section describes the Geocoding Control API. This API is used to interact with the Geocoding control model. For example, get the geocoded address or list of address candidates. The Geocoding Control uses the Java Beans represented in the following illustration:

Where:

• AddressBean – The AddressBean class contains address data, such as street, municipality, and country. It can be used as both an input and result address.

• AddressPointBean – This class extends the AddressBean with a Point. It keeps the geocoded address information.

• AddressMatchBean – This class contains the geocoded address and list of address candidates that are returned by the Location Utility Service.

• UIGeocoding – This is the JSF UIComponent that represents the Geocoding control.• AddressLocationHandler – This class contains methods to geocode an address.

Note: Refer to the Web Controls Javadoc for a detailed description of the methods and classes for the Geocoding Control beans.




You can get the geocoding results including the geocoded address with UIGeocoding class:

UIGeocoding uiGeocoding = getUIGeocoding();// address matchesAddressMatchBean addressMatch = uiGeocoding.getAddressMatch();// geocoded addressif(addressMatch.isAddressValidated()) {

AddressPointBean address = addressMatch.getAddressPoint();}

Where getUIGeocoding() method returns the UIGeocoding object.

The Geocoding control uses the AddressLocationHandler to geocode the input address:

AddressLocationHandler.geocode(AddressBean addressBean, AddressMatchBean addressMatchBean);

Where addressBean is an AddressBean object that contains the requested address to be geocoded and addressMatchBean is an AddressMatchBean object that contains the geocoded address response. The response contains the address candidate list returned.

If one candidate is returned, the address AddressPointBean object is set and the addressMatchBean response is set to valid (true).

If more than one candidate is returned in the list, you need to select one of the candidates. If one candidate is selected, the address object is set and the addressMatchBean response is set to valid (true).

If no candidate is returned (cancel button selected) the addressMatchBean response will remain invalid (false) and the current address will not be updated.

Mobile Device Location Control

The Mobile Device Location Control locates the position of a mobile device (such as a mobile phone) using the Envinsa Gateway Service and shows the reverse-geocoded address of the location. The device is identified by the mobile ID and passed to the Gateway Service as a request parameter.

For example, a dispatcher for an express delivery service may need to know the current position and address of one of their drivers to determine how well that driver is keeping on schedule. For example:

1. Choose the mobile device ID (typically a mobile phone number), or select it from a returned ID list.

2. The selected mobile ID is transmitted to the Gateway Service and the position is returned.3. The position is transmitted to the Location Utility Service. Using reverse geocoding, the

position is then returned as an address.4. The returned address can be displayed using the Mapping Control.





Default ConfigurationThe following section of a sample configuration file highlights the Mobile Device Location Control attributes:

<Gateway version="4.0" url="http://localhost:8080/Gateway/services/Gateway" userName="demo" userPassword="demo">

<GatewayRequest vendor="Ericsson" priority="NORMAL" distanceUnit="M" horizontalAccuracy="3000.0"/>

</Gateway>

The supported mobile ID list will be set by the mobileids bean:

<managed-bean>

<managed-bean-name>mobileids</managed-bean-name><managed-bean-class>java.util.ArrayList</managed-bean-class><managed-bean-scope>session</managed-bean-scope>

<list-entries><value-class>java.lang.String</value-class><value>4166881563</value><value>5185501000</value><value>2024440001</value>....



Integrating the Mobile Device Location ControlTo integrate the Mobile Device Location Control in your application, you need to know about the provided JSF controls, JSP tags, Mobile Device Location Control files, Mobile Device Location API (Java Beans), and Mobile Device Location Control interactions.

Mobile Device Location Control JSP TagTo start using the Mobile Device Location Control, first make sure that you include the declaration of the tag library in your JSP page:


The Mobile Device Location Control tag is defined in the miwebcontrols.tld file and is located under META-INF directory in the miwebcontrols.jar file. The following tag is defined for the control:




MobileLocation Tag

The Mobile Location tag has the following attributes:



• action – The action attribute allows you to associate a value binding expression to an action method. This will associate the action attribute with the action method as follows: <mi:mobileLocation id="mobileLocation1" title="MobileLocation"action="#{pc_TestControls.doMobileLocationAction}"></mi:mobileLocation>

where TestControls is the JSP page name, pc_TestControls is the name of the JSP page bean, and doMobileLocationAction is the name of the method from the JSP page bean. At the end of any model update initiated by the control the referenced method will be invoked. The user will be responsible for the business logic implemented by the method.

• value – The value attribute allows you to associate the control value to a persistent (session) mobileLocation MobilePositionBean bean. If this attribute is not defined the control will still set/get the data in a non persistent similar object using the component get/set methods.You can define the "mobile position" bean as a managed bean in the faces-config.xml:<managed-bean><managed-bean-name>mobileLocation</managed-bean-name><managed-bean-class>com.mapinfo.envinsa.clientutil.beans.MobilePositionBean</managed-bean-class><managed-bean-scope>session</managed-bean-scope></managed-bean>

Then you can bind the control with the defined bean as follows:<mi:mobileLocation id="mobileLocation1" value="#{mobileLocation}" ...>

• mobileids – This attribute will be used only if for some reason the user doesn't want to use the default bean name "mobileids" for the mobileids bean but another name, for example "mymobileids". In this case the user should change the name of the "mobileids" bean to "mymobileids" – refer to default values and configuration paragraph above. If used, the attribute will be defined as follows: <mi:mobileLocation id="mobileLocation1" title="MobileLocation"mobileids="#{mymobileids}"></mi:mobileLocation>




Using the Mobile Device Location Control APIThis section describes the Mobile Device Location Control API. The Mobile Device Location Control uses the Java Beans represented in the following illustration:

Where:

• MobilePositionBean – This class contains the mobile id, which is the mobile device number, mobile position preferences, and result position and address location.

• AddressPointBean – This class is the address with a Point. The class keeps the reverse geocoded address information.

• AddressMatchBean – This class contains the reverse geocoded address and the list of address candidates that are returned by the Location Utility service.

• UIMobileLocation – This is the JSF UIComponent that represents the MobileLocation control.

Note: Refer to the Web Control Javadoc for the detailed description of the methods and classes for the Mobile Device Location Control beans.

You can get the address that match the device mobile position with UIMobileLocation class:

UIMobileLocation uiMobileLocation = getUIMobileLocation();// mobile position beanMobilePositionBean mobilePosition = uiMobileLocation.getMobilePosition();// address match contains reverse geocoded address and candidatesAddressMatchBean addressMatch = mobilePosition.getAddressMatch();// get the result addressif(mobileLocation.isAddressValidated()) {

AddressPointBean address = mobileLocation.getAddressPoint();}

Where getUIMobileLocation() method returns UIMobileLocation object.

The Mobile Location control is using the AddressLocationHandler to get the device mobile position.




AddressLocationHandler.getMobileAddress(MobilePositionBean mobilePositionRequest, AddressMatchBean addressMatchBean);

where mobilePositionRequest is a MobilePositionBean object that defines the requested mobile ID (general phone number) to be located, and addressMatchBean is an AddressMatchBean object that contains the response of the reverse geocoded address. The response contains the address candidate list.

If one candidate is returned, the address AddressPointBean object is set and the addressMatchBean response is set to valid (true).

If more than one candidate is returned in the list, you should select one of the candidates. If one candidate is selected, the address object is set and the addressMatchBean response is set to valid (true).

If no candidate is returned (cancel button selected), the addressMatchBean response will remain invalid (false) and the current address will not be updated.

Route Locations Control

The Route Locations Control is used to prepare the start, end, stop, and via points for generating a route. It identifies a location using an address, street intersection, or place (such as a landmark or airport) and passes it to the Mapping Control and Route Preferences Control.

For example, you could get directions between the current location and an end location. This is a typical use case for the miTrip demo application. For example:

1. When the control initializes, the default values are loaded from the configuration.2. You enter the start and end addresses. These could be street addresses, street intersections,

a landmark, or an airport.3. Optionally, you could specify stopover (via) points on the trip.4. The address will be geocoded using the Location Utility Service and a list of addresses and

locations will be returned if the requested address can be located.5. After the route is requested, the turn-by-turn directions are returned and passed on to the

RouteInstructions Control. Refer to Route Instructions Control. The selected location will be displayed and passed to the RoutePreferences Control.





Configuration and Default ValuesDefault values include:

• Values related to the user application, such as: country and Point of Interest codes.• Values related to geocode preferences, such as close match only.

The following section of a sample configuration file highlights these attributes.

<LocationUtility version="4.0" url="http://localhost:8080/LocationUtility/services/LocationUtility" userName="demo" userPassword="demo">


The default country code is set in the envinsaws-config.xml file as:

<Locale countryCode="US" requestLanguage="en-US" />

The supported country list will be set by the countries bean:

<managed-bean>

<managed-bean-name>countries</managed-bean-name><managed-bean-class>java.util.ArrayList</managed-bean-class><managed-bean-scope>session</managed-bean-scope><list-entries>

<value-class>java.lang.String</value-class><value>USA</value><value>CAN</value>....


The supported landmarks/places of interest categories will be set by the landmarks bean:

<managed-bean>

<managed-bean-name>landmarks</managed-bean-name><managed-bean-class>java.util.TreeMap</managed-bean-class><managed-bean-scope>session</managed-bean-scope><map-entries>

<value-class>java.lang.String</value-class><map-entry>









<key>10110200</key>




<value>Tourist Attraction - Building</value></map-entry>....

</map-entries></managed-bean>

For a complete description and sample envinsa-config.xml file, refer to Configuring Web Controls on page 91.

Integrating the Route Locations ControlTo integrate the Route Locations Control in your application, you need to know about the provided JSF controls, JSP tags, Route Locations Control files, Route Location API (Java Beans), and Route Locations Control interactions.

Route Locations Control JSP TagThe API helps you to get the geocoded address location that can be used as start, and/or via point. To start using the Route Locations Control, first make sure that you include the declaration of the tag library in your JSP page:


The Route Locations Control tag is defined in the miwebcontrols.tld file and is located under the META-INF directory in the miwebcontrols.jar file. The following tag is defined for the control:

RouteLocation Tag

The Route Location tag has the following attributes:

• id – The identifier of the control tag.• title – The title of this tag.• rendered – Flag indicating whether this component (and its children) should be rendered. The


• action – The action attribute allows you to associate a value binding expression to an action method. This will associate the action attribute with the action method as follows: <mi:routeLocations id="routeLocations1" title="RouteLocations "action="#{pc_TestControls.doRouteLocationsAction}"></mi:routeLocations>

where TestControls is the JSP page name, pc_TestControls is the name of the JSP page bean, and doRouteLocationsAction is the name of the method from the JSP page bean. At the end of any model update initiated by the control the referenced method will be invoked. The user will be responsible for the business logic implemented by the method.

• value – The value attribute allows you to associate the control value to a persistent (session) routeLocation RouteLocationBean bean. If this attribute is not defined the control will still set/get the data in a non persistent similar object using the component get/set methods. You can define the RouteLocationBean bean as a managed bean in the faces-config.xml:<managed-bean><managed-bean-name>routeLocation</managed-bean-name><managed-bean-class>com.mapinfo.envinsa.clientutil.beans.RouteLocationBean</managed-bean-class>




<managed-bean-scope>session</managed-bean-scope></managed-bean>

Then you can bind the control with the defined bean as follows:<mi:routeLocations id="routeLocations1" value="#{routeLocation}" ...>

• countries – This attribute will be used only if for some reason the user doesn't want to use the default bean name "countries" for the countries bean but another name, for example "mycountries". In this case the user should change the name of the "countries" bean to "mycountries" – refer to default values and configuration paragraph above. If used, the attribute will be defined as follows: <mi:routeLocations id="routeLocations1" title="RouteLocations"countries="#{mycountries}" ></mi:routeLocations>

• landmarks – This attribute will be used only if for some reason the user doesn't want to use the default bean name "landmarks" but another name, for example "mylandmarks". In this case the user should change the name of the "landmarks" bean to "mylandmarks" – refer to default values and configuration paragraph above. If used, the attribute will be defined as follows:<mi:routeLocations id="routeLocations1" title="routeLocations"landmarks ="#{mylandmarks }" ></mi:routeLocations>

Using the Route Locations Control APIThis section describes the Route Locations Control API. The Route Locations Control uses the Java Beans represented in the following illustration:




Where:

• RouteLocationBean – This class contains the address location information for the current selected route point (start, end, or via).

• UIRouteLocations – This is the JSF UIComponent that represents the RouteLocations control.

• AddressMatchBean – This class contains the geocoded route location and the list of address candidates that are returned by the Location Utility Service.

• AddressPointBean – This class contains the geocoded route location.• AddressLocationHandler – This class is used to geocode the input route address.

Note: Refer to the Web Controls Javadoc for the detailed description of the methods and classes of the beans for the Route Locations Control.

The following example demonstrates how to get the route start point:

RouteLocationBean routeLocation = getUIRouteLocations().getRouteLocation();if(routeLocation.isAddressValidated()) {

if(routeLocation.isStart()) {Point startPoint = routeLocation.getAddressPoint().getPoint();

}}

Where getUIRouteLocations() method returns UIRouteLocations object.

The Route Locations Control is similar to the Geocoding Control. The difference is in the response. The Route Locations Control uses a RouteLocationBean which is an extension of the AddressMatchBean. This bean contains a RouteAddressSelectionBean object that is set with the latest route location/address type selected for geocoding (start/end/via(stop) points) when one of Start/End/Stop buttons is pressed. The RouteLocations control is using the AddressLocationHandler to get the geocoded address:

AddressLocationHandler.geocode(AddressBean addressBean, AddressMatchBean addressMatch);

where the addressBean is an AddressBean object that contains the requested address to be geocoded and the addressMatch is a AddressMatchBean object that contains the geocoded location address response. The response contains the returned address candidate list.

If one candidate is returned, the address AddressPointBean object is set and the addressMatch response is set to valid (true). The candidate list will be cleared.

If more than one candidate is returned in the list, you should select one of the candidates. If one candidate is selected, the address object is set and the addressMatch response will be set to valid (true).

If no candidates are returned (cancel button selected), the addressMatch response will remain invalid (false) and the current address will not be updated.




Route Preferences Control

The Route Preferences Control is used to specify the criteria used for the route request, and to trigger the route request action. The requested information is collected from the user interface and sent to the Envinsa Route Service.

The Route Preferences Control receives input mainly from the Route Locations Control or from any other Control able to generate and pass locations to Route Preferences (such as the Geocoding or Mobile Location Controls). The Route Preferences Control then requests the route and passes the previous response to the Route Instructions Control.

A typical workflow is as follows:

1. The user specifies the route preferences to be used for the route request.The following criteria will be exposed through the Route Preferences Control user interface. Refer to the Route Service Reference for more information.

• Route preference: fastest or shortest route for either driving or walking transportation.• Distance unit: (miles or kilometers).• Order of stopover points (if applicable). This is a flag indicating whether the stopover

points (via points) should be followed in the specified order.2. The user clicks the "Get Route" button in order to request the route.


Default ConfigurationThe default values are stored in the configuration, and include route preferences (fastest or shortest for driving and walking), and the distance unit (kilometers or miles).

The following section of a sample configuration file highlights these route attributes.

<Route version="4.0" url="http://localhost:8080/Route/services/Route" userName="demo" userPassword="demo">

<DetermineRouteRequest timeUnit="MIN" routeType="Fastest" transport="Driving" returnTurnIcon="url" >

<RouteGeometry maxPoints="1000" provideStartingPortion="false" provideInstructionsGeometry="true"/>

</DetermineRouteRequest></Route>




For a complete description and sample envinsa-config.xml file, refer to Configuring Web Controls on page 91.

Integrating the Route Preferences ControlTo integrate the Route Preferences Control in your application, you need to know about the provided JSF controls, JSP tags, Route Preferences Control files, Route Preferences API (Java Beans), and Route Preferences Control interactions.

Route Preferences Control JSP TagTo start using the Route Preferences Control, first make sure that you include the declaration of the tag library in your JSP page:


The Route Preferences Control tag is defined in the miwebcontrols.tld file and is located under the META-INF directory in the miwebcontrols.jar file. The following tag is defined for the control:

RoutePreferences Tag

The RoutePreferences tag has the following attributes:



• action – The action attribute allows you to associate a value binding expression to an action method. This will associate the action attribute with the action method. For example: <mi:routePreferences id="routePreferences1" title="RoutePreferences "action="#{pc_TestControls.doRoutePreferencesAction}"></mi:routePreferences>

where TestControls is the JSP page name, pc_TestControls is the name of the JSP page bean, and doRoutePreferencesAction is the name of the method from the JSP page bean. At the end of any model update initiated by the control the referenced method will be invoked. The user will be responsible for the business logic implemented by the method.

• value – The value attribute allows you to associate the control value to a persistent (session) routePreferences RouteBean backing bean. If this attribute is not defined the control will still set/get the data in a non persistent similar object using the component get/set methods. You can define the "mobile position" bean as a managed bean in the faces-config.xml:<managed-bean><managed-bean-name>routePreferences</managed-bean-name><managed-bean-class>com.mapinfo.envinsa.clientutil.beans.RouteBean</managed-bean-class><managed-bean-scope>session</managed-bean-scope></managed-bean>

Then you can bind the control with the defined bean as follows:<mi:routePreferences id="routePreferences1" value="#{routePreferences}" ...>




Using the Route Preferences Control APIThis section describes the Route Preferences Control API. This API is used to set up route preferences, start, end, via points, and gets route directions. The Route Preferences Control uses the Java Beans represented in the following illustration:

Where:

• RoutePreferencesBean – This class contains route preferences such as route transport, and distance units.

• RouteDirectionsBean – This class represents the route response data including the route instructions.

• RouteBean – The RouteBean class contains start, end, via points, route preferences, and result route directions.

• ViaPointsBean – This class has list of via points used in the route.• AddressPointBean – This class defined the location for start, end, or via points.• UIRoutePreferences – This is the JSF UIComponent that represents Route Preferences

control.• RouteHandler – This class contains methods to perform a routing with the specified bean

objects.

Note: Refer to the Web Controls Javadoc for the detailed description of the methods and classes of the beans for Route Preferences Control.




The following code demonstrates how to set up the start and end locations in the Route Preference control before getting the route instructions:

UIRoutePreferences uiRoute = getUIRoutePreferences();// route beanRouteBean route = uiRoute.getRoute();// set up start and end locationsroute.setStart(startAddress);route.setEnd(endAddress);

Where getUIRoutePreferences() method returns UIRoutePreferences object.

After performing the routing, for example in the method that handles Route Preference control action, you can get the route directions:

RouteBean route = getUIRoutePreferences().getRoute();// route directionsRouteDirectionsBean directions = route.getDirections();

Where getUIRoutePreferences() method returns UIRoutePreferences object.

This control will set the route preferences and will execute the route request/response sequence. The Route Preferences control uses the RouteHandler to perform routing:

RouteHandler.getRoute(RouteBean routeBean);

Where the routeBean is a RouteBean object that contains the request parameters and the response. The requested points are set in the RouteBean object and the preferences are set in the RoutePreferencesBean object contained in the routeBean.

In order to set the points, use any address control such as Geocoding, Mobile Device Location, or Route Locations, and pass the locations to the Route Preferences Control using an action referenced method. Refer to Control Synchronization on page 88 for more details.

The response is set in the RouteDirectionsBean that contains the instructions and the route geometry. If the response is valid, the RouteBean and the RouteDirectionsBean objects will be set to valid (true).

After the getRoute is completed, the route directions response is set the the RouteBean object. Refer to Control Synchronization on page 88 for more details.

Route Instructions Control

The Route Instructions Control displays the driving directions as text, route summary, and turn-by-turn instructions (optionally with turn icons). Each of the instructions can be selected to view the corresponding segment on the map. The Route Map button is selected to view the entire route. The Route Instructions Control relies on the Route Preferences Control to request the route and pass the instructions to the Route Instructions Control for presentation. Typically, you will also want to use the Mapping Control so that the route is displayed on the map.

If you select an instruction, the segment ID is set with the value of the instruction ID. You can use this segment ID to show the segment on the map. By pressing the RouteMap button, the segment ID is not set (null value), and the entire route is requested.





Default ConfigurationThere is no configuration for the Route Instructions Control.

For a complete description and sample envinsa-config.xml file, refer to Default Configuration mentioned in the Route Preferences Control and Configuring Web Controls on page 91.

Integrating the Route Instructions ControlTo integrate the Route Instructions Control in your application, you need to know about the provided JSF controls, JSP tags, Route Instructions Control files, Route Instructions API (Java Beans), and Route Instructions Control interactions.

Route Instructions Control JSP TagTo start using the Route Instructions Control, first make sure that you include the declaration of the tag library in your JSP page:


The Route Instructions Control tag is defined in the miwebcontrols.tld file and is located under the META-INF directory in the miwebcontrols.jar file. The following tag is defined for the control:

RouteInstructions Tag

The RouteInstructions tag has the following attributes:






• action – The action attribute allows you to associate a value binding expression to an action method. This will associate the action attribute with the action method. For example: <mi:routeInstructions id="routeInstructions1" title="RouteInstructions "action="#{pc_TestControls.doRouteInstructionsAction}"></mi:routeInstructions>

where TestControls is the JSP page name, pc_TestControls is the name of the JSP page bean, and doRouteInstructionsAction is the name of the method from the JSP page bean. At the end of any model update initiated by the control the referenced method will be invoked. The user will be responsible for the business logic implemented by the method.

• value – The value attribute allows you to associate the control value to a persistent (session) routeInstructions RouteDirectionsBean bean. If this attribute is not defined the control will still set/get the data in a non persistent similar object using the component get/set methods. You can define the routeInstructions bean as a managed bean in the faces-config.xml:<managed-bean><managed-bean-name>routeInstructions</managed-bean-name><managed-bean-class>com.mapinfo.envinsa.clientutil.beans.RouteDirectionsBean</managed-bean-class><managed-bean-scope>session</managed-bean-scope></managed-bean>

Then you can bind the control with the defined bean as follows:<mi:routeInstructions id="routeInstructions1" value="#{routeInstructions}" ...>

Using the Route Instructions Control APIThis section describes the Route Instructions Control API. This API let you set up and get the route instructions that are visualized by this control. The Route Instructions Control uses the Java Beans represented in the following illustration:

Where:

• RouteDirectionsPreferencesBean – This class contains the preferences that manage the route instructions output.

• RouteDirectionsBean – This class contains route directions including text instructions.




• UIRouteInstructions – This is the JSF UIComponent that represents Route Instructions control.

Note: Refer to the Web Controls Javadoc for the detailed description of the methods and classes of the beans for the Route Instructions Control.

The following example demonstrates how to set up route directions in the control:

UIRouteInstructions uiRouteInstructions = getUIRouteInstructions();uiRouteInstructions .setRouteDirections(directions);

Where getUIRouteInstructions() method returns the UIRouteInstructions object and directions is an instance of RouteDirectionsBean.

This control uses the RouteDirectionsBean object that is set by a route response (refer to Route Preferences Control on page 74 for more information on the RouteBean object). If the route response object is valid, the direction instructions will be displayed. If not, the control will not show a direction but the basic control screen.

The RouteDirectionsBean object should be set after the route request is completed and initiated by the Route Preferences Control action referenced method. Refer to Control Synchronization on page 88 for more details.

Search Preferences Control

The Search Preferences Control provides the Points of Interest search criteria around a given central location. For example, all restaurants and hotels within five miles around your office can be requested. When the Search button is clicked, a Find Nearest request is performed, based on the specified criteria.


Default ConfigurationThe configuration contains default values for search/find nearest requests such as search radius, maximum candidates defined in the envinsaws-config.xml file, and the list of values for supported distance units and search categories defined with beans in the faces-config.xml file.

The following section of a sample configuration file highlights these attributes.

<Directory version="4.0" url="http://localhost:8080/Directory/services/Directory" userName="demo" userPassword="demo">

<DirectoryRequest searchDistance="2" distanceUnit="KM" maxCandidates="5"/>




</Directory>

The supported category list will be set by the category bean:

<managed-bean>

<managed-bean-name>category</managed-bean-name><managed-bean-class>java.util.TreeMap</managed-bean-class><managed-bean-scope>session</managed-bean-scope><map-entries>


<key>PUBLIC;SampleDomain//Canadian Landmarks.By Provinces.Ontario Landmark</key> <value>Ontario Landmark</value>


<key>PUBLIC;SampleDomain//Washington DC.DC Child Day Care Services</key> <value>Child Day Care Services</value>


<key>PUBLIC;SampleDomain//Washington DC.DC Travel Agencies</key> <value>Travel Agencies</value>


<key>PUBLIC;SampleDomain//Washington DC.DC Offices of Lawyers</key> <value>Offices of Lawyers</value>


<key>PUBLIC;SampleDomain//Washington DC.DC Elementary and Secondary Schools</key> <value>Secondary Schools</value>

</map-entry>

....</map-entries>

</managed-bean>

The supported distance unit list will be set by the distanceUnit bean:

<managed-bean>

<managed-bean-name>distanceUnit</managed-bean-name><managed-bean-class>java.util.ArrayList</managed-bean-class><managed-bean-scope>session</managed-bean-scope><list-entries>

<value-class>java.lang.String</value-class><value>KM</value><value>MI</value>....


Search preferences will be set by the searchPreferences bean:

<managed-bean>




<managed-bean-name>searchPreferences</managed-bean-name><managed-bean-

class>com.mapinfo.envinsa.clientutil.beans.SearchPreferencesBean</managed-bean-class>

<managed-bean-scope>session</managed-bean-scope><managed-property>

<property-name>searchRadius</property-name><property-class>java.lang.String</property-class><value>3</value>

</managed-property><managed-property>

<property-name>maxCandidates</property-name><property-class>java.lang.String</property-class><value>6</value>

</managed-property></managed-bean>


Integrating the Search Preferences ControlTo integrate the Search Preferences Control in your application, you need to know about the provided JSF controls, JSP tags, Search Preferences Control files, Search Preferences API (Java Beans), and Search Preferences Control interactions.

Search Preferences Control JSP TagTo start using the Search Preferences Control, first make sure that you include the declaration of the tag library in your JSP page:


The Search Preferences Control tag is defined in the miwebcontrols.tld file and is located under the META-INF directory in the miwebcontrols.jar file. The following tag is defined for the control:

SearchPreferences Tag

The Search Preferences tag has the following attributes:



• action – The action attribute allows you to associate a value binding expression to an action method. This will associate the action attribute with the action method. For example: <mi:searchPreferences id="searchPreferences1" title="SearchPreferences "action="#{pc_TestControls.doSearchPreferencesAction}"></mi:searchPreferences>

where TestControls is the JSP page name, pc_TestControls is the name of the JSP page bean, and doSearchPreferencesAction is the name of the method from the JSP page bean. At the end of any model update initiated by the control the referenced method will be invoked. The user will be responsible for the business logic implemented by the method.




• value – The value attribute allows you to associate the control value to a persistent (session) searchPreferences SearchBean bean. If this attribute is not defined the control will still set/get the data in a non persistent similar object using the component get/set methods. You can define the "searchPreferences" bean as a managed bean in the faces-config.xml:<managed-bean><managed-bean-name>searchPreferences</managed-bean-name><managed-bean-class>com.mapinfo.envinsa.clientutil.beans.SearchBean</managed-bean-class><managed-bean-scope>session</managed-bean-scope></managed-bean>

Then you can bind the control with the defined bean as follows:<mi:searchPreferences id="searchPreferences1" value="#{searchPreferences}" ...>

• searchPreferences – This attribute will be used only if for some reason the user doesn't want to use the default bean name "searchPreferences" for the searchPreferences bean but another name, for example "mysearchPreferences". In this case the user should change the name of the "searchPreferences" bean to "mysearchPreferences" – refer to default values and configuration paragraph above. If used, the attribute will be defined as follows: <mi:searchPreferences id="searchPreferences1" title="SearchPreferences"searchPreferences="#{mysearchPreferences}" ></mi:searchPreferences>

• distanceUnit – This attribute will be used only if for some reason the user doesn't want to use the default bean name "distanceUnit" for the distanceUnit bean but another name, for example "mysearchPreferences". In this case the user should change the name of the "distanceUnit" bean to "mydistanceUnit" – refer to default values and configuration paragraph above. If used, the attribute will be defined as follows: <mi:searchPreferences id="searchPreferences1" title="SearchPreferences"distanceUnit="#{mydistanceUnit}" ></mi:searchPreferences>

• category – This attribute will be used only if for some reason the user doesn't want to use the default bean name "category" for the category bean but another name, for example "mycategory". In this case the user should change the name of the "category" bean to "mycategory" – refer to default values and configuration paragraph above. If used, the attribute will be defined as follows: <mi:searchPreferences id="searchPreferences1" title="SearchPreferences"category="#{mycategory}" ></mi:searchPreferences>




Using the Search Preferences Control APIThis section describes the Search Preferences Control API. The Search Preferences control API lets you set up the location to search around, and provides access to the search preferences and results. The Search Preferences Control uses the Java Beans represented in the following illustration:

Where:

• SearchPreferencesBean – This class contains the search preferences. For example, a search radius.

• SearchBean – The SearchBean class contains the search preferences and result data.• SearchResultsBean – This class contains the search results that are the POI points.• AddressPointBean – This class is used as a location to search around.• UISearchPreferences – This is the JSF UIComponent class representing the Search

Preferences control.• DirectoryHandler – The handler contains the methods to find the nearest locations.

Note: Refer to the Web Controls Javadoc for the detailed description of the methods and classes of the beans for the Search Preferences Control.

The following example demonstrates how to set up the location to search around (it should be done before searching):

UISearchPreferences uiSearch = getUISearchPreferences();// set up search location




uiSearch.setSearchLocation(address);

Where getUISearchPreferences() method returns UISearchPreferences object and address is an instance of AddressPointBean.

The following example shows how to get the search results:

UISearchPreferences uiSearch = getUISearchPreferences();// search beanSearchBean search = uiSearch.getSearch();// get search resultsif(search.isValid()) {

SearchResultsBean results = search.getResults();}

Where getUISearchPreferences() method returns UISearchPreferences object.

This control includes the search preferences and the search request/response sequence. The Search Preferences Control uses the DirectoryHandler to find nearest locations.

DirectoryHandler.findNearest(SearchBean searchBean);

Where the SearchBean object contains the request parameters and the response. The requested preferences radius, candidates, category, distance unit, and address are sent to the directory response.

To define the search address, you need another control, for example Geocoding or MobileLocation, that can get and set the SearchBean AddressPointBean location object. The response is set in a SearchResults object contained in the SearchBean object. After the search is complete, get the SearchResults object value to refer to the response. Refer to Control Synchronization on page 88 for more details.

Search Result Control

After results are returned from a Search operation (such as Find Nearest in Directory Service), the Search Result Control displays a tabular list of the returned Points of Interest. This table of features is dynamically generated following a Search operation. There are no configuration entries or default values associated with this control.

Default ConfigurationThere is no configuration for the Search Result Control.

For a complete description and sample envinsa-config.xml file, refer to Default Configuration mentioned in the Search Result Control and Configuring Web Controls on page 91.

Integrating the Search Result ControlTo integrate the Search Result Control in your application, you need to know about the provided JSF controls, JSP tags, Search Result control files, Search Result API (Java Beans), and Search Result control interactions.




Search Result Control JSP TagTo start using the Search Result Control, first make sure that you include the declaration of the tag library in your JSP page:


The Search Result Control tag is defined in the miwebcontrols.tld file and is located under the META-INF directory in the miwebcontrols.jar file. The following tag is defined for the control:

SearchResult Tag

The SearchResult tag has the following attributes:



• value – The value attribute allows you to associate the control value to a persistent (session) searchResult SearchResultsBean bean. If this attribute is not defined the control will still set/get the data in a non persistent similar object using the component get/set methods. You can define the "searchResult" bean as a managed bean in the faces-config.xml:<managed-bean><managed-bean-name>searchResult</managed-bean-name><managed-bean-class>com.mapinfo.envinsa.clientutil.beans.SearchResultsBean</managed-bean-class><managed-bean-scope>session</managed-bean-scope></managed-bean>

Then you can bind the control with the defined bean as follows:<mi:searchResult id="searchResult1" value="#{searchResult}" ...>




Using the Search Result Control APIThis section describes the Search Result Control API. This API lets you to set up or get the search results that are visualized by this control. The Search Result Control uses the Java Beans represented in the following illustration:

Where:

• SearchResultsBean – This class contains the Points of Interest for the location to search around.

• TableBean – This is an internal class that is used for results rendering.• UISearchResult – This is the JSF UIComponent that represents the Search Result control.

Note: Refer to the Web Controls Javadoc for the detailed description of the methods and classes of the beans for the Search Result Control.

The following code demonstrates how to set up the search results in the Search Result control:

UISearchResult uiSearchResult = getUISearchResult();uiSearchResult.setSearchResults(searchResults);

Where getUISearchResult() returns UISearchResult object and searchResults is an instance of SearchResultBean.

This control uses the SearchResultsBean object that is set by the search response (refer to Search Preferences Control on page 80 for more information on the SearchBean object). If the search response is valid, and the content of the table bean is not empty, the control shows the response in tabular form with column names and row values.




The SearchResultsBean object needs to be set after the search request is completed and initiated by the Search Preferences Control action referenced method. Refer to Control Synchronization on page 88 for more details.

Integrating Web Controls

In order to integrate Web Controls in your application, you need to understand how the Web Controls, JSP tags, Control APIs (Java Beans and service handlers) work together and how the Web Controls interact. To start using the Web Controls, first make sure that you include the declaration of the tag library in your JSP page:


The control tags are defined in the miwebcontrols.tld file. This file is located under the META-INF directory in the miwebcontrols.jar file.

Control SynchronizationThe Web Controls are designed as components that can work alone or work together with other controls (standard or user-defined) using JSF principles.

For example, the Geocoding Control can geocode addresses or airports and show the results. You can connect this control with other controls using an external synchronization or a control-initiated synchronization method.

External SynchronizationThis method uses the information stored in the resulting AddressMatchBean and passes it to another control (Mapping or RoutePreferences) by way of a user action. The user can use a button added to the JSP page that can call the corresponding method (doButtonAction()) from inside the page bean.

Assume you have a button named button1:

<h:commandButton id="button1" value="SetSearchLocation" type="submit"action="#{pc_TestControls.doButton1Action}">

</h:commandButton>

Where TestControls is the JSP page name, pc_TestControls is the name of the JSP page bean, and doButton1Action is the name of the method from the JSP page bean.

The bean entry in faces-config can be as follows:

<managed-bean><managed-bean-name>pc_TestControls</managed-bean-name><managed-bean-class>pagecode.TestControls</managed-bean-class><managed-bean-scope>request</managed-bean-scope>

</managed-bean>

When button1 is pressed, the method will get the latest geocoded address returned by the Geocoding Control and sets the Search Preferences Control location.

public String doButton1Action() {




// get the last geocoded addressAddressMatchBean addressMatch = ((UIGeocoding)

getGeocoding()).getAddressMatch();// check if is valid and update search preferences control locationif(addressMatch.getAddressPoint() != null &&

addressMatch.isAddressValidated()) {AddressPointBean location = new AddressPointBean(

addressMatch.getAddressPoint(), addressMatch.getAddressPoint().getPoint());

((UISearchPreferences) getSearchPreferences()).getSearch().setSearchLocation(location);

}return null;

}

Control Initiated SynchronizationThis method uses the referenced method defined inside the JSP page bean using the action tag attribute. Following the geocode action, the control will invoke the referenced method. The following is a JSP geocoding tag example that uses the pc_TestControls backing bean to handle the Web control actions:

<mi:geocoding id="geocoding" rendered="true" title="Geocoding"action="#{pc_TestControls.doGeocodingAction}">

</mi:geocoding>

where TestControls is the JSP page name and doGeocodingAction is the name of the method from the JSP page bean. The bean entry in the faces-config.xml file can be as follows:

<managed-bean><managed-bean-name>pc_TestControls</managed-bean-name><managed-bean-class>pagecode.TestControls</managed-bean-class><managed-bean-scope>request</managed-bean-scope>

</managed-bean>

After the Geocoding address is completed, the control will invoke the referenced method. The user will be responsible for the business logic implemented by the method. The following is an example of a doGeocodingAction method implementation:

public String doGeocodingAction() {// get the last geocoded addressAddressMatchBean addressMatch = ((UIGeocoding)

getGeocoding()).getAddressMatch();// check if is valid and update search preferences control locationif(addressMatch.getAddressPoint() != null &&

addressMatch.isAddressValidated()) {AddressPointBean location = new AddressPointBean(


((UISearchPreferences) getSearchPreferences()).getSearch().setSearchLocation(location);

}return null;

}

This method is called after every geocoding address action. If the response is valid, the location in the Search Preferences Control will be updated. Your can add logic and take action from inside this method. Multiple controls and associated data can be synchronized and updated.




To update the bean that contains the control's logic, you are required to provide code similar to the following example. Where search is a session SearchBean object used as a bean for Search Preferences Control:

public String doGeocodingAction() {// get the last geocoded addressAddressMatchBean addressMatch

=((UIGeocoding)getGeocoding()).getAddressMatch();// check if is valid and update search preferences control locationif(addressMatch.getAddressPoint()!=null &&

addressMatch.isAddressValidated()){AddressPointBean location = new AddressPointBean(


SearchBean sb = (SearchBean)BeanUtils.getBeanValue("search");sb.setSearchLocation(location);

}return null;

}

To include a Route Preferences Control, you are required to provide code similar to the following example, where TestControls is the JSP page name and doRoutePreferencesAction is the name of the method from the JSP page bean:

<mi:routePreferences id="routePreferences1" title="RoutePreferences "action="#{pc_TestControls.doRoutePreferencesAction}"></mi:routePreferences>

The following code will pass the response to the Route Instructions Control:

public void doRoutePreferencesAction() {RouteBean route = (RouteBean) ((UIRoutePreferences)

this.getRoutePreferences()).getRoute();if(route != null && route.isValid()) {

((UIRouteInstructions) this.getRouteInstructions()).setRouteDirections(route.getDirections());

}else {

((UIRouteInstructions) this.getRouteInstructions()).setRouteDirections(null);

}}

To include a Search Preferences Control, you are required to provide code similar to the following example, where TestControls is the JSP page name and doSearchPreferencesAction is the name of the method from the JSP page bean.

<mi:searchPreferences id="searchPreferences1" title="SearchPreferences "action="#{pc_TestControls.doSearchPreferencesAction}"></mi:searchPreferences>

The following code will pass the response to the Search Result Control, where searchResult is a session SearchResultsBean object used as a backed bean for the Search Result Control.

public String doSearchPreferencesAction() {SearchBean sBean

=((UISearchPreferences)this.getSearchPreferences()).getSearch();if(sBean!=null){




((UISearchResult)this.getSearchResult()).setSearchResults(sBean.getResults());}return null;

}

Web Controls and Data Beans Each Web Control has a data bean attached to it and is set and get by setValue()/getValue() or other specific control methods. For persistency, you can use session beans referred by the value tag attribute. The following example shows how the geocoding bean is referenced as a session bean and used as a value for the geocoding1 control:

<mi:geocoding id="geocoding1" rendered="true" title="Geocoding"action="#{pc_TestControls.doGeocodingAction}" value="#{geocoding}" >

</mi:geocoding>

To support this, you should add a managed bean entry into the faces-config.xml file:

<managed-bean><managed-bean-name>geocoding</managed-bean-name><managed-bean-class>com.mapinfo.envinsa.clientutil.beans.AddressMatchBean</

managed-bean-class><managed-bean-scope>session</managed-bean-scope>

</managed-bean>

Note: For more details, refer to the application examples and descriptions in Chapter 6: miTrip Application Tutorial.

Configuring Web Controls

There are two configuration files that control the Envinsa Web Controls:

1. The faces-config.xml file is an XML-based configuration file that governs the Envinsa JSF Web Controls User Interface. The entries in faces-config.xml define the values needed by the Web Controls User Interface (such as lists of supported countries, supported distance units, search categories, POI categories, etc.)

2. The envinsaws-config.xml file governs the Envinsa Services and contains default properties needed for the Envinsa Services requests. This file is regulated by a schema definition named envinsaws-config.xsd.

Both of these configuration files can be edited. For example you can modify the envinsaws-config.xml configuration file to point to the desired URL of each service, and you can modify the faces-config.xml file to configure the Web Control properties and default values. These configuration files must contain all properties required for each service and Web Control.

The envinsaws-config.xml File

By default, the envinsaws-config.xml file points to miplatform.mapinfo.com. (If you want to point to a different server, you change “miplatform.mapinfo.com“ to the URL of the desired server.) It is important to remember that the values defined in the faces-config.xml file will overwrite the values defined in the envinsaws-config.xml file. The following is the default envinsaws-config.xml file:




<EnvinsaToolsConfig xmlns="http://www.mapinfo.com/envinsatools" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.mapinfo.com/envinsatools envinsaws-config.xsd" version="4.0" distanceUnit="KM" maxCandidates="5" requestSRS="EPSG:4326">

<Locale countryCode="US"/><Directory url="http://miplatform.mapinfo.com/Directory/services/Directory"

userName="demo" userPassword="demo"><DirectoryRequest searchDistance="2" distanceUnit="KM" maxCandidates="5"/

></Directory><Gateway url="http://miplatform.mapinfo.com/Gateway/services/Gateway"

userName="demo" userPassword="demo"><GatewayRequest vendor="Ericsson" priority="NORMAL" distanceUnit="M"

horizontalAccuracy="3000.0"/></Gateway><LocationUtility url="http://miplatform.mapinfo.com/LocationUtility/services/

LocationUtility" userName="demo" userPassword="demo"><GeocodeRequest closeMatchesOnly="false"/>

</LocationUtility><Presentation url="http://miplatform.mapinfo.com/Presentation/services/

Presentation" userName="demo" userPassword="demo"><PortrayMapRequest basemapName="MapDisplay/high" defaultZoom="3"

distanceUnit="MI" zoomFactor="2"><Bounds llX="-152.829107" llY="24.878140" urX="-51.505651"

urY="84.651984"/><Output width="300" height="300" format="image/gif" content="URL"

transparent="true"/></PortrayMapRequest>

</Presentation><Route url="http://miplatform.mapinfo.com/Route/services/Route"

userName="demo" userPassword="demo"><DetermineRouteRequest timeUnit="MIN" routeType="Fastest"

transport="Driving" returnTurnIcon="url"><RouteGeometry maxPoints="1000" provideStartingPortion="false"

provideInstructionsGeometry="true"/></DetermineRouteRequest>

</Route></EnvinsaToolsConfig>

The faces-config.xml File

All beans for each control should be present in your application faces-config.xml file. If missing, the corresponding control will not show the appropriate data for all categories (distance unit, landmarks, etc.) and will fail during execution. The following is the default faces-config.xml file:

<managed-bean>

<managed-bean-name>countries</managed-bean-name><managed-bean-class>java.util.ArrayList</managed-bean-class><managed-bean-scope>session</managed-bean-scope><list-entries>

<value-class>java.lang.String</value-class><value>USA</value><value>CAN</value>....





<managed-bean>

<managed-bean-name>mobileids</managed-bean-name><managed-bean-class>java.util.ArrayList</managed-bean-class><managed-bean-scope>session</managed-bean-scope><list-entries>

<value-class>java.lang.String</value-class><value>4166881563</value><value>5185501000</value><value>2024440001</value>....


<managed-bean>

<managed-bean-name>landmarks</managed-bean-name><managed-bean-class>java.util.TreeMap</managed-bean-class><managed-bean-scope>session</managed-bean-scope><map-entries>










<key>10110200</key> <value>Tourist Attraction - Building</value>

</map-entry>....


<managed-bean>



<key>PUBLIC;SampleDomain//Canadian Landmarks.By Provinces.Ontario Landmark</key> <value>Ontario Landmark</value>





<key>PUBLIC;SampleDomain//Washington DC.DC Child Day Care Services</key> <value>Child Day Care Services</value>


<key>PUBLIC;SampleDomain//Washington DC.DC Travel Agencies</key> <value>Travel Agencies</value>


<key>PUBLIC;SampleDomain//Washington DC.DC Offices of Lawyers</key> <value>Offices of Lawyers</value>


<key>PUBLIC;SampleDomain//Washington DC.DC Elementary and Secondary Schools</key> <value>Secondary Schools</value>

</map-entry>....


<managed-bean>

<managed-bean-name>distanceUnit</managed-bean-name><managed-bean-class>java.util.ArrayList</managed-bean-class><managed-bean-scope>session</managed-bean-scope><list-entries>

<value-class>java.lang.String</value-class><value>KM</value><value>MI</value>....


<managed-bean>

<managed-bean-name>searchPreferences</managed-bean-name><managed-bean-

class>com.mapinfo.envinsa.clientutil.beans.SearchPreferencesBean</managed-bean-class>

<managed-bean-scope>session</managed-bean-scope>

<managed-property><property-name>searchRadius</property-name><property-class>java.lang.String</property-class><value>3</value>


<property-name>maxCandidates</property-name><property-class>java.lang.String</property-class><value>6</value>




<managed-bean><managed-bean-name>user</managed-bean-name><managed-bean-class>com.mapinfo.envinsa.clientutil.beans.UserBean</

managed-bean-class><managed-bean-scope>session</managed-bean-scope><managed-property>

<property-name>name</property-name><property-class>java.lang.String</property-class><value>demo</value>


<property-name>password</property-name><property-class>java.lang.String</property-class><value>demo</value>


If you want to change the name of a particular bean, set the appropriate tag attribute reference value. For example, to use a different name for the countries bean (supported country list) and landmarks bean (POI/place categories) you can modify the countries and landmarks tag attributes :

<mi:geocoding id="geocoding" rendered="true" title="Geocoding"countries="#{mycountries}" landmarks="#{mypois}"... >

</mi:geocoding>

where mycountries and mylandmarks are your new defined bean names. The bean data type definitions will be unchanged.

Note: You can extend the faces-config.xml file by adding your navigation rules or managed beans. You can also create your own configuration file and use this file in coordination with the faces-config.xml file. Refer to the documentation on JSF (javax.faces.CONFIG_FILES parameter in the web.xml file) for more information.

The user bean (UserBean class) should be added to faces-config.xml file only if you decide to:

• Use the user/password values for Envinsa service authentication.• Provide a user/password login screen that will use this bean.

Note: These user/password values will overwrite the values set in envinsaws-config.xml for each service. Only one user/password pair value can be set. If each service requires a different user/password pair then this solution will not be effective.




The Envinsa Web Services Configuration FileEach of the Envinsa Web Control configurations rely on the envinsaws-config.xml file to set preferences that are specific to the Envinsa Web Services. The following diagram illustrates the schema for the envinsaws-config.xml file:

The EnvinsaToolsConfig element contains settings that are commonly used among all Envinsa Web Services (for example version and distance units). You can specify the settings for each Web Service separately. For example the following diagram shows the configuration schema for the Presentation Service:




The Configuration APIThe Envinsa Web Controls include Java classes that reflect the envinsaws-config XML schema. These classes are located in the com.mapinfo.envinsa.clientutil.config package. The Apache Configuration API (refer to http://jakarta.apache.org/commons/configuration for details) is used to load XML configurations into configuration Java classes. The following diagram shows a subset of the configuration classes:

EnvinsaToolsConfig ClassThe EnvinsaToolsConfig class is the entry point for the configuration. This class is loaded once and has an application level scope. To get the configuration object you can use the following:

// get configurationEnvinsaToolsConfig config = EnvinsaToolsConfig.getInstance();

ServiceConfig Abstract ClassThe ServiceConfig abstract class has common methods and fields for all services and each Web service configuration class can extend it.

PresentationConfig ClassThe PresentationConfig class extends the ServiceConfig class and has an additional reference to the PortrayMapRequestConfig class. This class describes the configuration properties for the Presentation Service request.

// get Presenattion Service configurationPresentationConfig configPresentation = (PresentationConfig)

config.getServiceConfig(EnvinsaToolsConfig.PRESENTATION_SERVICE);



http://jakarta.apache.org/commons/configuration


FactoryServiceRequestConfig ClassThe FactoryServiceRequestConfig class is a helper that creates Envinsa SDK Web services request objects with the defined configuration values.

//create the portray map request with default configuration parametersPortrayMapRequestEx mapRequest = FactoryServiceRequestConfig.createPortrayMapRequest();

Localizing Web ControlsYou can localize the mimessages.properties file provided for the en_US mime type. For example, included is the Canadian version mimessages_en_CA.properties file.

Creating a Sample Geocode Application

This section provides a step-by-step example of how to implementat a simple Geocoder application in WebSphere Studio Developer. This application geocodes an input address and displays it on a map. Follow these steps in WebSphere Studio Developer:

1. Create a Dymamic Web ProjectSwitch to Web Perspective and create a new Dynamic Web Project by choosing File > New > Dynamic Web Project. Specify a new name for this project. For example:

Optionally configure advanced options.




Click Finish. The IDE creates the new project with the following structure:

2. Create a Faces JSP fileRight click on the project content and from the popup menu select New > Faces JSP File (or select from the main menu). In the Faces JSP File dialog enter the following:

a. Specify the file folder location Geocoder/WebContent.b. Enter geocoder as the file name.c. Select the Basic model. For example:




Click Finish. Your project now contains JSF resources, such as faces-config.xml, updated web.xml, and referenced JSF jars. For example:




The IDE Palette is now available with the Faces components including Envinsa Web Controls. For example:

3. Using Envinsa Web ControlsTo implement Geocoder application functionality, add Geocoding and Mapping controls to the JSP page:

a. Select geocoder.jsp file and switch to design mode:b. Drag and drop the Geocoding Web control from the Palette on the geocoder.jsp page.

Click ok when prompted to copy project resources:

Envinsa Web Controls resources (jars, and Web resources, such as styles and icons) are copied into your project.

You can also copy them manually as described in the Install Guide.




Your project now contains all Envinsa Web Controls Resources:




The Geocoding control appears in the geocoder.jsp file:

c. Put the Mapping Control with the toolbar and change the page title. You can also put these controls inside the table:

d. Save the geocoder.jsp page.e. Create an index.jsp file that redirects to our geocoder.jsp all faces requests. Right click the

project and select New > JSP File from the popup menu.




Specify the index as the file name. Select None as the model. For example:

Click Finish.

f. Go to page design mode. Drag the Forward JSP tag from the Palette onto the page.




g. Specify the page to forward. Ensure you typed "faces" in the context path. Click Ok.

h. Save the index.jsp file.4. Binding the Envinsa Web Controls

The Envinsa Web Controls are now in the JSP page and are fully functional. Before using them, you must add logic to the Geocoder application to display a geocoded address on a map. This involves intercepting a point from the Geocoding Control. This is done by executing a method each time the Geocoding Control gets a valid geocoded address.

To do this, edit the Geocoder.java class. This class is created by WebSphere Studio when you created a geocoder.jsp file. For example:

Create the following method:public String mapGeocodedAddress() {

UIGeocoding uiGeocoding = (UIGeocoding)getGeocoding1();UIMapping uiMapping = (UIMapping)getMapping1();

if(uiGeocoding != null && uiMapping != null) {

AddressMatchBean addressMatch = uiGeocoding.getAddressMatch();if(addressMatch.isAddressValidated()) {




AddressPointBean address = addressMatch.getAddressPoint();Overlay pointOverlay = new GeometryOverlay(address.getPoint());

uiMapping.getMapController().getMapBean().getOverlayLayers().clear();

uiMapping.getMapController().getMapBean().getOverlayLayers().add(pointOverlay);

uiMapping.getMapController().zoomToAllOverlays();}

}

return null;}

This method gets the AddressPointBean object from Geocoding control and creates an overlay to put it on the Mapping Control. Refer to the Web Controls API for a detailed description.

Edit the geocoder.jsp file and add the "action" attribute to the Geocoding Control. For example:<mi:geocoding title="Address" id="geocoding1" action="#{pc_Geocoder.mapGeocodedAddress}"></mi:geocoding>




This action has a method binding expression for the method that we defined in the Geocoder.java class. The "pc_Geocoder" name identifies the Geocoder.java and it is defined in the faces-config.xml:

Save all files and build the project.




5. Run the application.Inside the WebSphere Studio run (or debug) the created web application using the Test Environment. To do this, right click the project and select Run on Server. Create the Test Environment server that is Tomcat 4.1. For example (you can use WebSphere 5.1 as well):

Or use an already configured server.

Click Finish. The Tomcat server starts in the environment.




The application starts in a browser window. For example:

Enter address information into the geocoder fields to display the location on the map. For example, the following displays the address 10 Wall St, New York, NY:



5
Enhancing Envinsa Web Controls
Developers can enhance the Envinsa Web Controls to achieve additional or customized functionality. You can do so by enhancing the source code and modifying the configuration as required.

You can extend the Envinsa Web Controls four possible ways: adding new controls; adding new elements to an existing control, for example input/output fields; adding new tag attributes to an existing control; extending an existing control.

In this section:

Extending an Existing Control . . . . . . . . . . . . . . . . . . . . . . 111Adding a New Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Adding a new Element to an Existing Control . . . . . . . . . . 114Adding a new Attribute to an Existing Control . . . . . . . . . 114Modifying the Configuration to Support your Extension . 115

Client Developer Guide Chapter 5: Enhancing Envinsa Web Controls

Extending an Existing Control

If you are extending an existing control, you will need to follow the same steps mentioned in Adding a New Control on page 111. In many instances where the extensions are important, or are used in all of your applications, you may consider creating a new control rather than extending one.

If you decide to extend a control, follow these guidelines:

• In order to extend the Web Controls you need to know how the existing Web Controls are packaged. The Web Controls package contains the following directory structure:• /conf – Configuration files (faces-config.xml).• /lib – Required jar files (jsf-api.jar).• /source – All source code (beans, JSF controls, configuration, and Envinsa Web Service

clients).• /WebContent – Images, JavaScript, style sheets, web.xml, and miwebcontrols.tld.

• You need to add a new tag entry to the tld file and add a new component entry to the faces-config.xml file.

• You need to define the constructor in the extended component, similar to:public UINewComponentExtented() {setRendererType("com.mapinfo.envinsa.clientutil.jsf.newcomponent.NewComponentExtented"); }

• You may need to replace or extend the bean of the extended component, if the data is different.

• You need to overwrite the getComponentType() and getRendererType() tag methods to allow for the extended component references.

• You may need to overwrite one of the decode() or encodeBegin() renderer methods to support the extended component references or important user interface changes.

• Once your changes are made, you need to build the package.

Adding a New Control

In order to create the New component you need to create the following classes:

• UINewComponent.java• NewComponentTag.java• HtmlNewComponentRenderer.Java

The New component will be added to faces-config.xml file and the New tag will be added to the tld file (miwebcontrols.tld or user defined). Also a NewComponetBean will be defined based on control and component requirements.

Note: The following package could be changed as required for an application.

1. Create the UINewComponent.java file similar to the following:public class UINewComponent extends UIComponent {

public static final String FAMILY = "NewComponent";




public UINewComponent() {

setRendererType("com.mapinfo.envinsa.clientutil.jsf.newcomponent.NewComponent");

}

/* (non-Javadoc) * @see javax.faces.component.UIComponent#getFamily() */ public String getFamily() {

return FAMILY; }

/** * @return */public SearchBean getNewComponent() {

return (SearchBean)getValue();}public Object getValue() {

if(super.getValue() == null) { setValue(new NewComponentBean());

} return (super.getValue());

}/** * @param bean */public void setNewComponent(NewComponent bean) {

setValue(bean);}

}

2. Create the NewComponentTag.java file similar to the following. It is recommended that the NewComponentTag class extend the AbstractTag class.public class NewComponentTag extends AbstractTag {

public NewComponentTag() {super();

}public void release() { // the super class method should be called super.release(); }protected void setProperties(UIComponent component) { // the super class method should be called super.setProperties(component);

}public String getComponentType() { return "com.mapinfo.envinsa.clientutil.jsf.newcomponent.NewComponent";}public String getRendererType() { return "com.mapinfo.envinsa.clientutil.jsf.newcomponent.NewComponent";}

}




3. Create the HtmlNewComponentRenderer.java similar to the following. This example provides the main method that should be implemented. The decode method is used when updating the model.public class HtmlNewComponentRenderer extends Renderer {

public HtmlNewComponentRenderer() {super();

}/* (non-Javadoc) * @see

javax.faces.render.Renderer#decode(javax.faces.context.FacesContext, javax.faces.component.UIComponent)

*/public void decode(FacesContext context, UIComponent component) {

super.decode(context, component);.......

}/* (non-Javadoc) * @see

javax.faces.render.Renderer#encodeBegin(javax.faces.context.FacesContext, javax.faces.component.UIComponent)

*/public void encodeBegin(FacesContext context, UIComponent component)

throws IOException {

super.encodeBegin(context, component);......

} /* (non-Javadoc)

* @see javax.faces.render.Renderer#encodeEnd(javax.faces.context.FacesContext, javax.faces.component.UIComponent)

*/ public void encodeEnd(FacesContext context, UIComponent component)

throws IOException {super.encodeEnd(context, component);.......

}}

4. Add a newComponent entry to the faces-config.xml file:<component>

<component-type>com.mapinfo.envinsa.clientutil.jsf.newcomponent.NewComponent</component-type>

<component-class>com.mapinfo.envinsa.clientutil.jsf.newcomponent.UINewComponent</component-class>

</component>

5. Add a newComponent tag entry to the tld file (miwebcontrols.tld or a user defined file):<tag>

<name>newComponent</name><tag-

class>com.mapinfo.envinsa.clientutil.jsf.newcomponent.NewComponentTag</tag-class>

<body-content>JSP</body-content><description> New Component control tag.




</description> <attribute>

<name>id</name> <description>Component identifier of this component.</description> </attribute> <attribute>

<name>rendered</name> <description>Is this component rendered?</description></attribute><attribute>

<name>title</name> <description>Title of this component.</description>

</attribute><attribute>

<name>value</name><description>Value binding expression to newComponet bean</

description> </attribute>

</tag>

Adding a new Element to an Existing Control

You can add new elements to an existing Envinsa Web Control. For example, you can add a new input/output or selection component. To add a new element, you need to perform the following:

1. Add a rendering sequence for the new element to the existing renderer.2. Add the corresponding data if missing to the object (backing) bean.

Adding a new Attribute to an Existing Control

You can add new attributes to an existing Envinsa Web Control. To add a new attribute, you need to perform the following:

1. Add the new attribute to the Java class tag. For example, if you want to add the countries attribute to the NewComponent control you should add the countries String object member, the get/set countries methods, and set the new attribute in the setProperties() method. The NewComponentTag added code should look like the following:public class NewComponentTag extends AbstractTag {

String countries;public NewComponentTag() {

super();}............public String getCountries() {

return countries;}public void setCountries(String string) {

countries = string;}




...........protected void setProperties(UIComponent component) {

// the super class method should be called super.setProperties(component);

TagUtils.setString(component, "countries", countries);}

.......... }

2. Add the new attribute to the tag. For example, the country attribute entry will be added to the newComponent tag in the tld file (miwebcontrols.tld):<attribute>

<name>countries</name><description>Value binding expression to a countries bean</description>

</attribute>

Modifying the Configuration to Support your Extension

If you are adding your own parameters to the configuration, you need to perform the following:

• Update the envinsaws-config.xml schema adding your new attributes or elements.• Create a new configuration class, or update an existing one, providing the additional methods

to get the configuration values.• Create a load method for the newly created configuration class or update the existing load

method:protected void load(Configuration config, EnvinsaToolsConfig toolsConfig);

Make sure the load method is called when configuration objects are loaded.

• Update the configuration factory class (FactoryServiceRequestConfig) if you want to apply the new configuration properties in the request.

Sample Configuration ExtensionThe following steps are shown as an example of adding Coordinate Geometry (Cogo) Service default parameters to the configuration.

1. Update the configuration schema – Find the envinsaws-config.xsd file and add the Cogo Service to the services list:<xsd:group name="Services">

<xsd:annotation><xsd:documentation>

At least one of the service elements must be specified, but essentially, all are optional.

</xsd:documentation></xsd:annotation><xsd:sequence>

<xsd:element ref="Cogo" minOccurs="0"/><xsd:element ref="Directory" minOccurs="0"/><xsd:element ref="Gateway" minOccurs="0"/><xsd:element ref="LocationUtility" minOccurs="0"/><xsd:element ref="Presentation" minOccurs="0"/><xsd:element ref="Route" minOccurs="0"/>

</xsd:sequence>




</xsd:group>

Add elements for the Cogo Service and request. In this example, Cogo extends the Service element inheriting common service specific parameters. For simplicity, this example adds a distance unit parameter to the Cogo request. This parameter should be applied each time you create a Cogo request, and overwrites the global configuration distance units. <xsd:element name="Cogo">

<xsd:complexType><xsd:complexContent>

<xsd:extension base="Service"><xsd:sequence>

<xsd:element ref="CogoRequest"/></xsd:sequence>

</xsd:extension></xsd:complexContent>

</xsd:complexType></xsd:element><xsd:element name="CogoRequest">

<xsd:complexType><xsd:attribute name="distanceUnit" type="distanceUnit" use="required"/

></xsd:complexType>

</xsd:element>

2. Update the configuration file – Update your configuration file (envinsaws-config.xml) according to your changes in schema. <Cogo url="http://localhost:8080/Cogo/services/Cogo" userName="demo" userPassword="demo">

<CogoRequest distanceUnit="MI"/></Cogo>

3. Create a class to keep the configuration request parameters – Create a CogoRequestConfig class. This class will contain the configuration properties for the Cogo request. For now it contains only a distance unit property. This class has to load its properties from the configuration. To do this, you have to create a load() method that will read the configuration parameters using Apache Common Configuration API.public class CogoRequestConfig {

// distance unitsprivate DistanceUnit distanceUnit;/** * Default no-arg constructor. */protected CogoRequestConfig() {}/** * @return Returns the distanceUnit. */public DistanceUnit getDistanceUnit() {

return this.distanceUnit;}/** * @param distanceUnit The distanceUnit to set. */protected void setDistanceUnit(DistanceUnit distanceUnit) {

this.distanceUnit = distanceUnit;}/**




* @param toolsConfig * @param configuration */protected void load(Configuration config, EnvinsaToolsConfig toolsConfig)

{

if(config != null) {

// distance unitsDistanceUnit unit =

ConfigUtils.getDistanceUnit(config.getString(Tags.Attributes.DISTANCE_UNIT), toolsConfig);

setDistanceUnit(unit);

}}

4. Create a service configuration class – Create a configuration class for the Cogo Service and add the reference to the Cogo request. You can add the configuration class to the com.mapinfo.envinsa.clientutil.config package.public class CogoConfig extends ServiceConfig {

private CogoRequestConfig m_cogoRequest;/** * Default no-arg constructor. */protected CogoConfig() {

super();}/** * @return Returns the portrayMapRequest. */public CogoRequestConfig getCogoRequest() {

return this.m_cogoRequest;}

/** * @param portrayMapRequest The portrayMapRequest to set. */protected void setCogoRequest(CogoRequestConfig cogoRequest) {

this.m_cogoRequest = cogoRequest;}

/** * @see

com.mapinfo.envinsa.clientutil.config.ServiceConfig#getServiceName() */public String getServiceName() {

return EnvinsaToolsConfig.COGO_SERVICE;}/** * @param toolsConfig * @param configuration */protected void load(Configuration config, EnvinsaToolsConfig toolsConfig)

{super.load(config, toolsConfig);if(config != null) {

if(ConfigUtils.containsKey(config, Tags.Elements.COGO_REQUEST)) {




m_cogoRequest = new CogoRequestConfig();m_cogoRequest.load(config.subset(Tags.Elements.COGO_REQUEST),

toolsConfig);}

}

}

5. Update the EnvinsaToolsConfig class – To work with the newly created CogoConfig class you have to update the EnvinsaToolsConfig class by adding the Cogo configuration to the services list:public static String COGO_SERVICE = "Cogo";…

static {SERVICES_CONFIG.put(PRESENTATION_SERVICE, PresentationConfig.class);

…SERVICES_CONFIG.put(COGO_SERVICE, CogoConfig.class);

};

6. Use the configuration classes – The configuration classes are ready to use. You can use the following code to create a point-to-point Envinsa SDK Cogo request:public static CogoRequest createPointToPointRequest(Point point1, Point point2) {

CogoRequest cogoRequest = null;// get configurationEnvinsaToolsConfig config = EnvinsaToolsConfig.getInstance();// get Cogo Service configurationCogoConfig configCogo =

(CogoConfig)config.getServiceConfig(EnvinsaToolsConfig.COGO_SERVICE);if(configCogo != null) {

cogoRequest = new CogoRequest(METHOD_NAME, getVersion(configCogo),

FactoryServiceRequestConfig.class.getName()+"."+System.currentTimeMillis());RequestCalculation calc = new

RequestCalculation("POINTTOPOINTDISTANCE");PointToPointDistance dist = new PointToPointDistance(point1,

point2);

dist.setDistanceUnit(configCogo.getCogoRequest().getDistanceUnit());calc.setPointToPointDistance(dist);

cogoRequest.addRequestCalculation(calc);return cogoRequest;

}



6
miTrip Application Tutorial
This chapter describes the miTrip sample Web application that is provided with Envinsa 4.0. In addition to illustrating several Envinsa Services and Web Controls, miTrip can also be used as a model for building an application with the Envinsa Location Platform SDK.

Other sample applications will be available for download from the Mapinfo Web site at http://mapinfo.com

In this section:

Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Installation and Configuration. . . . . . . . . . . . . . . . . . . . . . . 121Using the miTrip Sample Application . . . . . . . . . . . . . . . . . 123miTrip Architectural Overview. . . . . . . . . . . . . . . . . . . . . . . 126Web Controls in miTrip . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Step-By-Step Application Implementation of miTrip . . . . . 127Building and Deploying An Application . . . . . . . . . . . . . . . 133

http://mapinfo.com

Client Developer Guide Chapter 6: miTrip Application Tutorial

Introduction

The sample application miTrip guides you in using the Envinsa SDK and to demonstrate a way of implementing Web based applications.

The miTrip application implements the following requirements and functionality:

1. Provide a user interface (UI) for popular PC and HTML browsers.2. Makes use of Envinsa Web Controls provided as productivity tools.3. Built on JavaServer Faces (JSF) technology.4. Offers basic functionality of finding routes, driving directions, displaying and navigating maps.5. Lets the user define start and end points for a route and optional via points using an address,

intersection, airport, or other landmark, to provide selections for geocoded candidates.6. Can select POI data from multiple categories in drop-down list.7. Supports mobile location as a start point.8. Allows selection of route preference method of transportation (driving. walking).9. Supports search preferences: search radius, maximum number of candidates, what category

to search.10. Can request a route and show result as text and a route map.11. Can present results in configurable table format.12. Zoom in/out and pan capabilities on any displayed map, and zoom to a selected route

segment.

This application makes use of the following Envinsa Web Controls:

• RouteLocations• Mobile Device Location• Map Control• Route Instructions• Route Preferences• Search Preferences• Search Results

miTrip also illustrates the use of a UDDI registry, which would normally be handled transparently in an application.

Refer to Using Envinsa Web Controls on page 51 for a description of all Envinsa-provided Web Controls.




Installation and Configuration

The following sections describe how to install and run the miTrip application tutorial.

Software Requirements and PrerequisitesThe following software versions (or newer) are required to build and run the miTrip application:

• Java JVM 1.5.0, which is bundled with Envinsa 4.0. JVM 1.4.2 is also supported.• JSP 1.2 or 2.0 (http://java.sun.com/products/jsp) and JSF 1.1 (http://java.sun.com/j2ee/

javaserverfaces) • Apache ANT 1.6.2 to build the application and WAR file http://ant.apache.org.• Tomcat versions 5.5.9, which is bundled with Envinsa 4.0. Tomcat 5.0.28 is also supported.

However, other Web application servers such as IBM WebSphere 5.1, 6.0 and BEA WebLogic 8.1.4 may be used to deploy and run miTrip.

• UDDI registry (optional).

Envinsa Requirements for miTripSince the miTrip sample application relies on several Envinsa Services and Web Controls, the following Envinsa components must be installed (or the Envinsa services must be accessible) to support the sample application:

• Envinsa Web Services• Sample Data

Installing miTripThe miTrip sample application is bundled with Envinsa Client SDK zip file and all required files and source code is located under "samples/applications/mitrip" directory. The miTrip application is contained within the miTrip WAR file.

The application can be installed without rebuilding. However, configuration changes are required if you wish to use locally installed Web Services and a local UDDI registry. To install the miTrip application, simply take the file mitrip.war from the samples/applications/ directory in the SDK package and install it to your Web Server. Use the appropriate tools and steps to deploy a .war file for your Web Server. For Tomcat installation:

1. Copy the miTrip.war file to the Tomcat /webapps directory.2. Restart the Tomcat Web server.

Configuring miTripThe miTrip application can be configured in several ways. You can modify the envinsaws-config.xml file (providing different settings for the Web Services that miTrip is using) or you can use the faces-config.xml file to set up the applications beans and managed beans of the Web Controls.



http://ant.apache.org



http://java.sun.com/products/jsp/


Locate envinsaws-config.xml in the directory where mitrip.war is expanded (/mitrip/WEB-INF/classes) and modify the properties for Web Services. For example, for the Location Utility service you can set up the Web Service endpoint URL and geocoding properties. Refer to Configuring Web Controls on page 91 for an example of all envinsaws-config.xml properties.

<LocationUtility url="http://miplatform.mapinfo.com/LocationUtility/services/LocationUtility" userName="demo" userPassword="demo">


Locate faces-config.xml in the mitrip/WEB-INF and adjust the managed bean's properties.

You can add a new category to the Search Preferences Web Control:

<managed-bean>



<key>PUBLIC;SampleDomain//Canadian Landmarks.By rovinces.Ontario Landmark</key>

<value>Ontario Landmark</value></map-entry><map-entry>

<key>PUBLIC;SampleDomain//Washington DC.DC Child Day Care Services</key>

<value>Child Day Care Services</value></map-entries>

</managed-bean>

Change the UDDI settings. The uddisettings bean contains properties to connect to the UDDI server that include the inquiry URL, user name, and password:

<managed-bean><managed-bean-name>uddisettings</managed-bean-name><managed-bean-class>com.mapinfo.envinsa.mitrip.beans.UDDISettings</managed-

bean-class><managed-bean-scope>application</managed-bean-scope>

<managed-property><property-name>inquiryURL</property-name><property-class>java.lang.String</property-class><value>http://oberon.mapinfo.com:9050/juddi/inquiry</value>

</managed-property>

<managed-property><property-name>userName</property-name><property-class>java.lang.String</property-class><value>demo</value>

</managed-property>




<managed-property><property-name>userPassword</property-name><property-class>java.lang.String</property-class><value>demo</value>

</managed-property>

</managed-bean>

Note: Configuration changes take effect only after restarting the Web Server where the miTrip application is deployed.

Importing Existing miTrip Code to WebSphere StudioYou can import the miTrip sample application code into your WebSphere Studio IDE. This allows you to examine the existing implementation and modify the application to suit your needs.

1. Create a Dynamic Web Project with JSF support. You should have an empty dynamic web project, a faces servlet defined in the web.xml, the faces-config.xml file in the WebContent/WEB-INF/ directory, and JavaSource and WebContent directories created in the project.

2. Copy envinsaws-config.xml and envinsaws-config.xsd files from the <mitrip>/conf directory to the JavaSource project directory.

3. Copy the jar files from the <mitrip>/lib directory to the WebContent/WEB-INF/lib directory.4. Copy the java source files from the <mitrip>/src directory to the JavaSource directory.5. Copy the web resources from the <mitrip>/WebContent directory to the project WebContent

directory. Overwrite the faces-config.xml and merge the web.xml files.6. Integrate the Web Controls files with your environment as it's described in the Integrating

Web Controls in Chapter 4 on page 88.

Using the miTrip Sample Application

After you have installed and configured the miTrip sample application, run miTrip by pointing your Internet browser to the address where you have installed the miTrip application. The following is the URL format for your miTrip application:

http://<hostname>:<portnumber>/miTrip

For verification and demonstration purposes, there is an installed version of this application available at the following address:


The miTrip sample application provides point-to-point driving directions and a find nearest function. This combines the functionality of the Location Utility, Route, Presentation, Directory, and Gateway Services.

Step-by-Step Instructions for Using miTripThe following basic instructions describe how to use the miTrip sample application:

1. Enter the Start, End, and Stop Points





2. Generate the Route and Map

You can also perform a Find Nearest search at a specified location, although this example is not illustrated in this document.

The following example produces a route from the corner of Wellington Street and Young Street in Toronto, Canada to Global View in Troy, NewYork, with a stop point at Adams St. and University Ave. in Syracuse, NY.

Enter the Start, End, and Stop PointsIn order to perform the route, you must enter two locations in miTrip, one as the starting point and the other as the ending point for the route. You can optionally specify one or more stop points (also known as via points, or intermediate stops on the trip). These locations can be an address, an intersection, an airport, or a landmark. If close matches are returned, select the most accurate candidate from the list. After you have specified the start, end, (and optionally stop points) for your trip, you can generate the route directions and map.

After starting the miTrip demo application, specify a start point for you trip. In this example, the intersection of Wellington Street and Young Street in Toronto, Canada is the start point. Make sure that Canada is the Country selection and the Intersection button is selected.

Change the Country selection to United States and click the Address button, then specify the end point as Global View, Troy NY. You may need to select the address you want from a list of close-matching candidates.

In this example, you are also using a stop point in Syracuse NY. With the Country selection set to United States, click the Intersection button, then specify the stop point as the intersection of Adams St. and University Ave. in Syracuse, NY.




The Specify Route Preferences window summarizes your start, end, and stop points and lets you specify the Route Preferences (fastest or shortest), Route Transport (driving or pedestrian), and the Distance Unit (miles or kilometers). In this example, fastest driving directions with mile measurements are selected. If more than one stop point was selected, you can specify the order of stop points by checking stop order. In this example, only one stop point (Syracuse, NY) was specified.

Generate the Route and MapAfter specifying the trip points and route preferences, click Get Route to generate the route directions and map. A map is displayed showing the route and the turn-by-turn directions. The following example shows the map and the first few turn directions. Total time and distance are also indicated.

The map controls lets you select a larger version of the map. You can also zoom in, zoom out, or pan the map. The following map shows the Syracuse stop point zoomed in to 1.25 miles. Note, that in addition to using the Zoom In or Out icons, you can also enter a specific zoom distance in the Zoom dialog at the upper right.




miTrip Application LimitationsThe miTrip application has the following limitations:

• Cannot perform a search at a mobile location.• City geocoding is supported by leaving the street field blank. However, you need to either

specify the full state or province name or leave the state/province field blank to obtain a list of candidates.

miTrip Architectural Overview

The miTrip application is built using JSF as a framework. For details, refer to Step-By-Step Application Implementation of miTrip on page 127.

For details on the JSF framework and information on how to build an application using JSF, consult the following Web site:http://java.sun.com/j2ee/javaserverfaces/.





Web Controls in miTrip

The miTrip application uses the following Web controls:

• Route Locations – Geocode the addresses that might be set as start/end/via route points.• Route Preferences – Perform a route for the specified route points and routing preferences.• Mapping – Display a route, start/end/via locations on the map and perform basic mapping

operations like zoom in, zoom out and pan.• Route Directions – Show route instructions.• Mobile Location – Get mobile location.• Search Preferences – Search nearest POIs with specified search preferences.• Search Result – Show nearest POIs.

The miTrip application combines Web Controls and adds interaction between them. For example, when a start trip address is geocoded the application gets an address from the Route Locations control, sets it as a start point in the Route Preferences control, then passes a geometry point of this location to Mapping control to display it on the map.

The following diagram illustrates the interactions between Web controls in the miTrip application.

Step-By-Step Application Implementation of miTrip

Like miTrip, most application implementation can contain the following basic steps.

1. Set up your IDE Environment for the JSF Web project and import the Envinsa Web Controls.2. Create the Application JSP Pages3. Create the JSF Backing Beans for the JSP Pages that are responsible for handling user

input.4. Define the Navigation Rules in faces-config.xml




Set up your IDE EnvironmentThis step depends on the environment that you are using and if it has JSF development support. The following files are necessary for the application that uses the Web Controls:

• Jar files from the <webcontrols>/lib directory• Web Resources from the <webcontrols>/WebContent directory• Configuration file envinsaws-config.xml (and schema envinsaws-config.xsd) from

<webcontrols>/conf that must be in the Web application classpath• faces-config.xml – You must merge the provided configuration file with the application’s

configuration file (or use different name declaring it in the web.xml, see corresponding JSF documentation)

The following steps describe how to set up a Web project using WebSphere Application Developer or IBM Rational Development Platform:

1. Create a new Dynamic Web Project. This creates a Web project with "JavaSource" and "WebContent" directories.

2. Create a JSP file with JSF support. This allows importing of JSF resources into your project. The environment updates your web.xml, adds a faces servlet to it, and adds faces-config.xml and necessary jar libraries.

3. Get Envinsa Web Controls from where they are installed and perform the following steps:a. Copy <webcontrols>/lib to WebContent/WEB-INF/lib project directory. Copy

<webcontrols>/WebContent to WebContent project directory. You can also use the IBM JSF implementation. In that case, do not copy the SUN's implementation from the <webcontrols>/lib directory. Instead, get the Envinsa client SDK jar files and copy them to the WebContent/WEB-INF/lib directory, then refresh the project and you are ready to use Envinsa Web Control

b. Merge <webcontrols>/conf/faces-config.xml with the project's faces-config.xml.c. If you would like to use WebSphere Application Developer or Rational Development

Platform as Test Environment, then copy <webcontrols>/conf/envinsaws-config.xml and envinsaws-config.xsd to the JavaSource project directory. These files will be copied to WEB-INF/classes when you rebuild the project.

Create the Application JSP PagesThe miTrip application contains several JSP pages as shown in the following illustration:

tripView.jspThis page contains the Web controls that are necessary to provide the basic functionality of the application (geocode start/end, get a route, mapping, etc):

• RouteLocations• RoutePreferences




• Mapping• RouteInstructions• MobileLocation

The following is an example of how to use the mapping tag in the tripView.jsp page:

<mi:mapping id="map" basemapName="MapDisplay/high">

<mi:maptoolbar id="toolbar" defaultTool="pan" skin="orange"><mi:maptool id="pan" name="pan" /><mi:maptool id="zoomin" name="zoomin" /><mi:maptool id="zoomout" name="zoomout" />

<mi:mapwidth id="zoom" />

</mi:maptoolbar>

</mi:mapping>

The following is an example of how to use the Route Preferences control. The route preferences tag contains an action attribute that defines the method in the trip bean. The action is called once after routing is performed. This action updates the state of other controls on the page.

<mi:routePreferences id="routePreferences" title="#{msgs.title_routing}" action="#{trip.doRouteAction}" />

searchPOIs.jspThis page contains Search Preferences, Search Result, and Mapping Web Controls. These controls provide the Find Nearest capability from the selected address.

searchLocator.jspThis page provides Envinsa Web Service URL lookup functionality and it uses standard JSF controls such as input text, output text, and command buttons.




Create the JSF Backing Beans for the JSP PagesThe miTrip application uses the beans that are represented in the following diagram:

TripModelThis is the main backing bean that handles almost all miTrip user requests, such as displaying start/end locations on the map, and updating route instructions.

SearchPOIsThis backing bean is responsible for setting up search results in the Search Result Web Control and displaying them on the map using the Mapping Control.

ServiceLocatorThis bean is responsible for providing the search Web service URL functionality using the UDDI registry. This is provided for demo purposes only.

MapSize, TripState, TripServiceUrls, UDDISettings These beans are responsible for keeping data that is needed for the miTrip application. They are defined as managed beans in the faces-config.xml.




The following example shows the implementation of doRouteAction() method. This method is called after routing is performed. At this step the application needs to map a route and set up the instructions in the Route Instructions control in case of success.

Note: This example has simplified code. Refer to the original java source code.public String doRouteAction() {

// get routePreferences bean and set up the start/end/via points for this beanRouteBean route = this.getUIRoutePreferences().getRoute();

// get Route Directions and GeometryRouteDirectionsBean directions = route.getDirections();

// display routeInstructions on the map in case of successif(directions != null) {

// we've got routePreferences instructions, set them up in the routeInstructions control

this.getUIRouteInstructions().setRouteDirections(directions);

// display route geometry on the map as overlayif(directions.getRouteGeometry() != null) {

MapController map = this.getUIMapping().getMapController();

RouteGeometryOverlay overlay = new RouteGeometryOverlay(directions.getRouteGeometry().getLineString());

MappingUtils.mapOverlay(map, overlay);

}}else {

// on error clear route instructions componentthis.getUIRouteInstructions().setRouteDirections(null);

}

// we stay on the same page, nothing to returnreturn null;

}

The following examples show the declaration of backing beans in the faces-config.xml:

TripModel

<managed-bean><managed-bean-name>trip</managed-bean-name><managed-bean-class>com.mapinfo.envinsa.mitrip.TripModel</managed-bean-

class><managed-bean-scope>request</managed-bean-scope>

</managed-bean>

ServiceLocator

<managed-bean><managed-bean-name>serviceLocator</managed-bean-name><managed-bean-class>com.mapinfo.envinsa.mitrip.ServiceLocator</managed-

bean-class>




<managed-bean-scope>request</managed-bean-scope></managed-bean>

SearchPOIs

<managed-bean><managed-bean-name>searchpois</managed-bean-name><managed-bean-class>com.mapinfo.envinsa.mitrip.SearchPOIs</managed-bean-

class><managed-bean-scope>request</managed-bean-scope>

</managed-bean>

Note: Some Java IDEs can generate backing beans for you when you create the faces JSP page.

Define the Navigation Rules in faces-config.xmlThis step links JSP pages that define the navigation rules based on the value from the submit form action.

This example shows two navigation cases for the tripView page. They define a transition to searchPOIs and serviceLocator pages

<navigation-rule>

<from-view-id>/tripView.jsp</from-view-id><navigation-case>

<from-action>#{trip.doServiceLocatorAction}</from-action><from-outcome>success</from-outcome><to-view-id>/serviceLocator.jsp</to-view-id><redirect/>

</navigation-case><navigation-case>

<from-action>#{trip.doSearchAction}</from-action><from-outcome>success</from-outcome><to-view-id>/searchPOIs.jsp</to-view-id><redirect/>

</navigation-case></navigation-rule>




Building and Deploying An Application

Refer to Configuring miTrip on page 121 for information on how to set up Web services URLs and UDDI settings.

A procedure to build the miTrip application is provided. It is based on Apache ANT. As an alternative to using ANT, you may use an IDE's capabilities directly to build and even deploy the application.

To use ANT to build the application, follow these steps:

1. For convenience on Windows, the BAT file build.bat is provided which runs ANT using the build file build.xml. To use it you need to adjust the settings of anthome and cliendsdk to fit your local installation. On other operating systems it should be straightforward to use an equivalent procedure. Ensure an appropriate Java VM is in your path.

2. Run the build procedure and check for any errors. If successful, the file mitrip.war is created which can be deployed to a Web Server. If Tomcat is used, copy this file to the webapps directory.

Consider other requirements such as security, privacy, use by subscription (for example, login required), and billing.



A
Country Codes
This appendix provides a list of all the country codes that are associated with the Envinsa 4.0 Location Platform. These ISO country Name codes are used by the Envinsa Presentation, Location Utility, and Route Services and during batch geocoding.

For official information on ISO country name codes, see http://www.iso.org/iso/en/prods-services/popstds/countrynamecodes.html.

http://www.iso.org/iso/en/prods-services/popstds/countrynamecodes.html



Client Developer Guide Chapter A: Country Codes

Country 2-Character Code 3-Character Code

AFGHANISTAN AF AFG

ALBANIA AL ALB

ALGERIA DZ DZA

AMERICAN SAMOA AS ASM

ANDORRA AD AND

ANGOLA AO AGO

ANGUILLA AI AIA

ANTARCTICA AQ ATA

ANTIGUA AND BARBUDA AG ATG

ARGENTINA AR ARG

ARMENIA AM ARM

ARUBA AW ABW

AUSTRALIA AU AUS

AUSTRIA AT AUT

AZERBAIJAN AZ AZE

BAHAMAS BS BHS

BAHRAIN BH BHR

BANGLADESH BD BGD

BARBADOS BB BRB

BELARUS BY BLR

BELGIUM BE BEL

BELIZE BZ BLZ

BENIN BJ BEN

BERMUDA BM BMU

BHUTAN BT BTN

BOLIVIA BO BOL

BOSNIA AND HERZEGOWINA BA BIH

BOTSWANA BW BWA

BOUVET ISLAND BV BVT




BRAZIL BR BRA

BRITISH INDIAN OCEAN TERRI-TORY

IO IOT

BRUNEI DARUSSALAM BN BRN

BULGARIA BG BGR

BURKINA FASO BF BFA

BURUNDI BI BDI

CAMBODIA KH KHM

CAMEROON CM CMR

CANADA CA CAN

CAPE VERDE CV CPV

CAYMAN ISLANDS KY CYM

CENTRAL AFRICAN REPUBLIC CF CAF

CHAD TD TCD

CHILE CL CHL

CHINA CN CHN

CHRISTMAS ISLAND CX CXR

COCOS (KEELING) ISLANDS CC CCK

COLOMBIA CO COL

COMOROS KM COM

CONGO, Democratic Republic of (was Zaire)

CD COD

CONGO, People's Republic of CG COG

COOK ISLANDS CK COK

COSTA RICA CR CRI

COTE D'IVOIRE CI CIV

CROATIA (local name: Hrvatska) HR HRV

CUBA CU CUB

CYPRUS CY CYP

CZECH REPUBLIC CZ CZE





DENMARK DK DNK

DJIBOUTI DJ DJI

DOMINICA DM DMA

DOMINICAN REPUBLIC DO DOM

EAST TIMOR TL TLS

ECUADOR EC ECU

EGYPT EG EGY

EL SALVADOR SV SLV

EQUATORIAL GUINEA GQ GNQ

ERITREA ER ERI

ESTONIA EE EST

ETHIOPIA ET ETH

FALKLAND ISLANDS (MALVINAS) FK FLK

FAROE ISLANDS FO FRO

FIJI FJ FJI

FINLAND FI FIN

FRANCE FR FRA

FRANCE, METROPOLITAN FX FXX

FRENCH GUIANA GF GUF

FRENCH POLYNESIA PF PYF

FRENCH SOUTHERN TERRITO-RIES

TF ATF

GABON GA GAB

GAMBIA GM GMB

GEORGIA GE GEO

GERMANY DE DEU

GHANA GH GHA

GIBRALTAR GI GIB

GREECE GR GRC

GREENLAND GL GRL





GRENADA GD GRD

GUADELOUPE GP GLP

GUAM GU GUM

GUATEMALA GT GTM

GUINEA GN GIN

GUINEA-BISSAU GW GNB

GUYANA GY GUY

HAITI HT HTI

HEARD AND MC DONALD ISLANDS

HM HMD

HONDURAS HN HND

HONG KONG HK HKG

HUNGARY HU HUN

ICELAND IS ISL

INDIA IN IND

INDONESIA ID IDN

IRAN (ISLAMIC REPUBLIC OF) IR IRN

IRAQ IQ IRQ

IRELAND IE IRL

ISRAEL IL ISR

ITALY IT ITA

JAMAICA JM JAM

JAPAN JP JPN

JORDAN JO JOR

KAZAKHSTAN KZ KAZ

KENYA KE KEN

KIRIBATI KI KIR

KOREA, DEMOCRATIC PEOPLE'S REPUBLIC OF

KP PRK

KOREA, REPUBLIC OF KR KOR





KUWAIT KW KWT

KYRGYZSTAN KG KGZ

LAO PEOPLE'S DEMOCRATIC REPUBLIC

LA LAO

LATVIA LV LVA

LEBANON LB LBN

LESOTHO LS LSO

LIBERIA LR LBR

LIBYAN ARAB JAMAHIRIYA LY LBY

LIECHTENSTEIN LI LIE

LITHUANIA LT LTU

LUXEMBOURG LU LUX

MACAU MO MAC

MACEDONIA, THE FORMER YUGOSLAV REPUBLIC OF

MK MKD

MADAGASCAR MG MDG

MALAWI MW MWI

MALAYSIA MY MYS

MALDIVES MV MDV

MALI ML MLI

MALTA MT MLT

MARSHALL ISLANDS MH MHL

MARTINIQUE MQ MTQ

MAURITANIA MR MRT

MAURITIUS MU MUS

MAYOTTE YT MYT

MEXICO MX MEX

MICRONESIA, FEDERATED STATES OF

FM FSM

MOLDOVA, REPUBLIC OF MD MDA

MONACO MC MCO





MONGOLIA MN MNG

MONTSERRAT MS MSR

MOROCCO MA MAR

MOZAMBIQUE MZ MOZ

MYANMAR MM MMR

NAMIBIA NA NAM

NAURU NR NRU

NEPAL NP NPL

NETHERLANDS NL NLD

NETHERLANDS ANTILLES AN ANT

NEW CALEDONIA NC NCL

NEW ZEALAND NZ NZL

NICARAGUA NI NIC

NIGER NE NER

NIGERIA NG NGA

NIUE NU NIU

NORFOLK ISLAND NF NFK

NORTHERN MARIANA ISLANDS MP MNP

NORWAY NO NOR

OMAN OM OMN

PAKISTAN PK PAK

PALAU PW PLW

PALESTINIAN TERRITORY, Occu-pied

PS PSE

PANAMA PA PAN

PAPUA NEW GUINEA PG PNG

PARAGUAY PY PRY

PERU PE PER

PHILIPPINES PH PHL

PITCAIRN PN PCN





POLAND PL POL

PORTUGAL PT PRT

PUERTO RICO PR PRI

QATAR QA QAT

REUNION RE REU

ROMANIA RO ROM

RUSSIAN FEDERATION RU RUS

RWANDA RW RWA

SAINT KITTS AND NEVIS KN KNA

SAINT LUCIA LC LCA

SAINT VINCENT AND THE GREN-ADINES

VC VCT

SAMOA WS WSM

SAN MARINO SM SMR

SAO TOME AND PRINCIPE ST STP

SAUDI ARABIA SA SAU

SENEGAL SN SEN

SEYCHELLES SC SYC

SIERRA LEONE SL SLE

SINGAPORE SG SGP

SLOVAKIA (Slovak Republic) SK SVK

SLOVENIA SI SVN

SOLOMON ISLANDS SB SLB

SOMALIA SO SOM

SOUTH AFRICA ZA ZAF

SOUTH GEORGIA AND THE SOUTH SANDWICH ISLANDS

GS SGS

SPAIN ES ESP

SRI LANKA LK LKA

ST. HELENA SH SHN





ST. PIERRE AND MIQUELON PM SPM

SUDAN SD SDN

SURINAME SR SUR

SVALBARD AND JAN MAYEN ISLANDS

SJ SJM

SWAZILAND SZ SWZ

SWEDEN SE SWE

SWITZERLAND CH CHE

SYRIAN ARAB REPUBLIC SY SYR

TAIWAN TW TWN

TAJIKISTAN TJ TJK

TANZANIA, UNITED REPUBLIC OF

TZ TZA

THAILAND TH THA

TOGO TG TGO

TOKELAU TK TKL

TONGA TO TON

TRINIDAD AND TOBAGO TT TTO

TUNISIA TN TUN

TURKEY TR TUR

TURKMENISTAN TM TKM

TURKS AND CAICOS ISLANDS TC TCA

TUVALU TV TUV

UGANDA UG UGA

UKRAINE UA UKR

UNITED ARAB EMIRATES AE ARE

UNITED KINGDOM GB GBR

UNITED STATES US USA

UNITED STATES MINOR OUTLY-ING ISLANDS

UM UMI

URUGUAY UY URY





UZBEKISTAN UZ UZB

VANUATU VU VUT

VATICAN CITY STATE (HOLY SEE) VA VAT

VENEZUELA VE VEN

VIET NAM VN VNM

VIRGIN ISLANDS (BRITISH) VG VGB

VIRGIN ISLANDS (U.S.) VI VIR

WALLIS AND FUTUNA ISLANDS WF WLF

WESTERN SAHARA EH ESH

YEMEN YE YEM

YUGOSLAVIA YU YUG

ZAMBIA ZM ZMB

ZIMBABWE ZW ZWE




B
Supported Coordinate Systems
The Envinsa API can transform geometries from one coordinate system to another. This transformation relies on spatial reference system identifiers to specify the source and target coordinate systems. The identifier must use either the European Petroleum Survey Group (EPSG) code or the MAPINFO code.

For more information on projections, coordinate systems, and how GML geometries can be transformed from one coordinate system to another, refer to the Coordinate System Transform Service Reference.

This appendix identifies the supported EPSG and MAPINFO codes.

In this section:

Supported Coordinate Reference Systems . . . . . . . . . . . . 145

Client Developer Guide Chapter B: Supported Coordinate Systems

Supported Coordinate Reference Systems

The Coordinate System Transform Service uses spatial reference system identifiers to specify the source and target coordinate systems for the transformation. The format must be either the European Petroleum Survey Group (EPSG) code or the MAPINFO code. The coordinate reference systems are specified as codespace and code, separated by a colon.

codespace:code

For example, a geometry in WGS 84 would look like:

"EPSG:4326"

For a complete list and more information on EPSG codes refer to the following Web site:http://www.epsg.org/. You can also see a complete listing of codes by extracting the micsys.txt file from the from any micsys.jar file. An micsys.jar file can be found in the WEB-INF\lib folder for any Web Service. For example, the Presentation Web Service micsys.jar file could be located in:

C:\MapInfo\Envinsa-4.0\WebServer\Tomcat-Presentation\webapps\Presentation\WEB-INF\lib\

You can “unzip” this file (or any micsys.jar file) to access the micsys.txt file.

Widely Used EPSG CodesThe following table lists the most widely used EPSG codes:

Further Supported EPSG and MAPINFO Codes

UTM WGS 84 - EPSG Code

The following table lists UTM Zones and their corresponding EPSG codes and MAPINFO codes.

Coordinate System EPSG Code

Longitude / Latitude (WGS 72) 4322

Longitude / Latitude (WGS 84) 4326

Longitude / Latitude (NAD 83) 4269

Longitude / Latitude (OSGB 36) 4277

UTM Zone EPSG Code

UTM Zone 1 Northern Hemisphere 32601

UTM Zone 1 Southern Hemisphere 32701







































UTM Zone EPSG Code

































UTM Zone EPSG Code

































UTM Zone EPSG Code































UTM Zone 1 (NAD 83) MAPINFO:coordsys365


UTM Zone EPSG Code




UTM Zone 3 (NAD 83) 26903"

UTM Zone 4 (NAD 83) 26904"

UTM Zone 5 (NAD 83) 26905"

UTM Zone 6 (NAD 83) 26906"

UTM Zone 7 (NAD 83) 26907



UTM Zone 10 (NAD 83) 26910

UTM Zone 11 (NAD 83) 26911

UTM Zone 12 (NAD 83) 26912

UTM Zone 13 (NAD 83) 26913

UTM Zone 14 (NAD 83) 26914

UTM Zone 15 (NAD 83) 26915

UTM Zone 16 (NAD 83) 26916

UTM Zone 17 (NAD 83) 26917

UTM Zone 18 (NAD 83) 26918

UTM Zone 19 (NAD 83) 26919

UTM Zone 20 (NAD 83) 26920

UTM Zone 21 (NAD 83) 26921

UTM Zone 22 (NAD 83) 26922

UTM Zone 23 (NAD 83) 26923

UTM Zone 24 (NAD 83) 26924

UTM Zone 25 (NAD 83) 26925

UTM Zone 26 (NAD 83) 26926

UTM Zone 27 (NAD 83) 26927

UTM Zone 28 (NAD 83) 26928


UTM Zone EPSG Code