v3.0 Developer Guide - Pitney Bowes...Ł API documentation for the MapInfo Routing J Server is...

$: v3.0 Developer Guide - Pitney Bowes...Ł API documentation for the MapInfo Routing J Server is located in \RoutingJServer-3.0\docs. For Windows installations, there$
v3.0
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.© 2003 MapInfo Corporation. All rights reserved. MapInfo, the MapInfo logo and MapInfo Routing J Server are trademarks of MapInfo Corporation and/or its affiliates. MapInfo Corporate Headquarters:Voice: (518) 285-6000Fax: (518) 285-6060Sales Info Hotline: (800) 327-8627Government Sales Hotline: (800) 619-2333Technical Support Hotline: (518) 285-7283Technical Support Fax: (518) 285-6080Contact information for MapInfo Corporation is located at: http://www.mapinfo.com/contact_us.cfm.

Portions copyright 2003 OPCOM Pty Limited. All rights reserved.

2003 Geographic Data Technology, Inc. All rights reserved. This product contains proprietary and confidential property of Geographic Data Technology, Inc. Unauthorized use, including copying, for other than testing and standard backup procedures, of this product is expressly prohibited. 2003 Tele Atlas N.V.�s-Hertogenbosch. All rights reserved.Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.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.June 2003

http://www.mapinfo.com/contact_us.cfm

Table of Contents

Chapter 1: Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1New in Version 3.0. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Migrating Routing J Server 2.5 Applications to 3.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3MapInfo Routing J Server Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Hardware Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Platform-Specific Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Performance Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 2: Installation and Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Installation Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Installing Routing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Installing the MapInfo Routing J Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Installing on UNIX without a Graphics Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Testing the Routing J Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Installed Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Uninstalling the MapInfo Routing J Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Deployment Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Deploying the Routing J Server in Other Web Server Environments . . . . . . . . . . . . . . . . 20Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Chapter 3: Understanding Routing Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Planning Your Routing Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Functionality Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Client Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Preference Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Routing Data Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Connection via HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Reference Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32MapInfo Support and Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Chapter 4: Working with Routing Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Routing Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Using the RoutingClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Using the MultiPointClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Using the MatrixRouteClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Developer Guide Table of Contents

Chapter 5: Modifying Routing Directions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Routing Directions Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Requesting Default Directions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42DirectionsPreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Using DirectionsPreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Custom Directions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Using Directions Generators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Creating a DirectionsGenerator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Directions Generators and DirectionsPreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Configuring the Server for Generator Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Using the Generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Routing Directions Strings Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Turn Angle Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Routing Directions Token Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Creating Custom Directions on the Client Side . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Additional Routing Directions Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Chapter 6: Customizing Routing with Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . 57RoutingPreferences Class Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Algorithm Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Returning Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Using Per Request Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Working with Includes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Setting the Timeout Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Setting Travel Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Working with Time-based Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Using Time Zones in Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Routing J Server Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66MultiPointPreferences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Chapter 7: Working with the IsoClient. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68IsoDefinition Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Using IsoPreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Expected Isochrone/Isodistance Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Donut Style Banding Suggestions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Obtaining Isochrones/Isodistances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Chapter 8: Using the RoutingDataClient and Data Updates . . . . . . . . . . . . . . . . . . . . 75Accessing Routing Data Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Modifying Data with Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Routing J Server 3.0

© 2003 MapInfo Corporation. All rights reserved. iv Routing30_eng_A4.pdf


Chapter 9: MapInfo Enterprise XML Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Working with the XML API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Document Type Definitions (DTD) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81HTTP Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82XML Elements Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84MI_XML_Protocol_RoutingRequestAndResponseEnvelope_3.0.dtd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86MI_XML_Protocol_RoutingCommonElements_3_0.dtd. . . . . . . . . . . . . . . . . . . . . . . . . . . . 86MI_XML_Protocol_RoutingRouteRequestAndResponse_3_0.dtd . . . . . . . . . . . . . . . . . . . 90MI_XML_Protocol_RoutingMultiRequestAndResponse_3_0.dtd . . . . . . . . . . . . . . . . . . . . 90MI_XML_Protocol_RoutingIsoRequestAndResponse_3_0.dtd. . . . . . . . . . . . . . . . . . . . . . 92MI_XML_Protocol_RoutingPersistentUpdatesRequestAndResponse_3_0.dtd. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93MI_XML_Protocol_RoutingMatrixRequestAndResponse_3_0.dtd . . . . . . . . . . . . . . . . . . . 94MI_XML_Protocol_RoutingDataRequestAndResponse_2_5.dtd . . . . . . . . . . . . . . . . . . . . 95XML Backwards Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Supported Road Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Chapter 10: Working with Routing Samples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98Diagnostic Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99RoutingClientGUI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99TestXML Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100Servlet Samples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Classic Routing Servlet Sample. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Isochrone Servlet Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106MultiPoint Servlet Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Sample Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Include/Exclude Sample Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Point and Click Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Directions Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Classpaths for Routing Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Localization of Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Chapter 11: Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119MapInfo Routing J Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Testing the Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Web Server Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Tomcat Installation on Windows 2000. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121


© 2003 MapInfo Corporation. All rights reserved. v Routing30_eng_A4.pdf


Appendix A: Web.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Sample web.xml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Appendix B: Initialization Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125RoutingServlet Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Appendix C: Deprecated API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128Deprecated Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128Deprecated Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128Deprecated Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Deprecated Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Appendix D: Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141


© 2003 MapInfo Corporation. All rights reserved. vi Routing30_eng_A4.pdf

1
Introduction
MapInfo Routing J Server is a Java-based development tool designed to find a route between points. It can find the route with the shortest distance or the route that takes the shortest time to travel. Finding a route is useful for providing driving or walking directions and determining where to lay cable, as well as a host of other uses. The Routing J Server can also be used to obtain a polygon or set of points representing an area that can be traversed in a network from a starting point in a given amount of time or a certain distance.

This product consists of the MapInfo Routing J Server, the Java API for building a routing client, an XML API (which can be used from non-Java clients), sample and diagnostic applications, and API documentation in HTML format.

In this chapter:

! New in Version 3.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2! Migrating Routing J Server 2.5 Applications to 3.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3! MapInfo Routing J Server Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4! Hardware Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4! Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5! Platform-Specific Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5! Performance Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Developer Guide Chapter 1: Introduction

New in Version 3.0

Some of the newest enhancements to the MapInfo Routing J Server 3.0 include:

Directions Generator

Routing J Server 3.0 provides the ability for an advanced user to perform server-side customization of directions. For more information see Using Directions Generators on page 46.

Datasets

In Routing J Server 3.0, data is organized into datasets. For more information see Routing Data Overview on page 31.

Timeout for Routes in API

Routing J Server 3.0 allows you to set the timeout value for route, iso, matrix, and multipoint clients. For more information see Setting the Timeout Value on page 61.

Time and Distance in Directions

Routing J Server provides you with the UnitFormat class to get a String representation of a time, distance, or angles. For more information see Implementation of the DirectionsGenerator Interface on page 48.

Time ZonesWith Routing J Server 3.0, you can produce routes that make use of time zones. For more information see Using Time Zones in Routes on page 63.

Update AbilityImprovements have been made to the way Routing J Server handles persistent and transient updates. For more information see Modifying Data with Updates on page 77.

LoggingThe Routing J Server can log various types of messages. For more information see Logging on page 27

Point and Click SampleThe new Point and Click sample application uses allows you to click on map to specify start and end points and route between those points. For more information see the section, Point and Click Sample Application on page 113.

Multi ThreadingRouting J Server 3.0 is now multi threaded.


© 2003 MapInfo Corporation. All rights reserved. 2 Routing30_eng_A4.pdf


Migrating Routing J Server 2.5 Applications to 3.0

When upgrading an existing 2.5 application to 3.0, be aware of the following items.

Incalculable RoutesRoutes that are incalculable will exhibit the following behavior:

� Incalculable routes will now throw a RouteCalculationException instead of returning a zero time and zero distance.

� Incalculable MultiPoint routes will also throw a RouteCalculationException instead of returning a zero time and zero distance.

� Incalculable routes in a matrix route request will throw a RouteCalculationException when the user tries to access the time/distance from the RouteCost. RouteCost has the isValid() method so that you can check if a RouteCost is calculable.

Client Side DirectionsBuilding direction on the client side is no longer supported. It is replaced by the server side directions modules. For more information see Using Directions Generators on page 46.

Include by SegmentInclude by segment is no longer supported. The data now consists of single bidirectional segments rather than two segments representing each direction of a single segment. This results in significantly smaller data size and makes the use of include by segment obsolete. It is in the API, but it is deprecated. However, it is a no-op (will not do anything). For a complete list of deprecated items, see Appendix C: Deprecated API.

Time ZonesIf you are using start or end times and want to use time zones, then the time zone should be specified when specifying start/end time. Otherwise, local time is assumed.

Recompiling Code Developed With Previous Versions of the MapInfo Rout-ing J Server

It is recommended that you recompile any code you've developed with previous versions of the MapInfo Routing J Server to ensure your code is compatible with the new API, and to take advantage of the new features.




Jar FilesThe names of the following jar files have changed:

MapInfo Routing J Server Documentation

Use the following documentation pieces to assist you with developing custom routing applications.

� MapInfo Routing J Server Developer�s Guide provides installation instructions for MapInfo Routing J Server and an overview of how to build routing applications.

Note: Throughout this documentation, generic file names are used. For example, .rmf files are referred to as *.rmf.

� API documentation for the MapInfo Routing J Server is located in <Install_Dir>\RoutingJServer-3.0\docs. For Windows installations, there is a shortcut menu option. See Index.html for an alphabetical index of all classes with their methods and properties.

� Information about data for the Routing J Server is located on the MapInfo Web site. For a list of the contents and organization of the data CDs, go to http://www.mapinfo.com/support/documentation/manuals.cfm, and refer to the information in the Routing J Server section.

� An object model diagram poster is included in the documentation set. It provides an overview of classes with their methods and properties.

� MapInfo COM Client for Routing J Server Developer�s Guide is provided as a PDF on your product CD. This document provides necessary information for developing COM Client applications.

� A readme file is also included at the root level of your product CD. This file contains the latest information and issues about the Routing J Server. Note that this file is not installed by the installer, you must copy it manually from the CD.

Hardware Requirements

The minimum system requirements are a 600 MHz CPU with 512 MB memory, 2 GB hard drive, and Pentium III or equivalent processor. For better performance, however, we recommend using at least 1 GB memory. The amount of memory depends on the number of computer processors that you set for the Routing J Server. Note that requirements vary based on the size of data that you use. For more information, see Performance Tuning on page 5.

Version 2.5 Version 3.0

RoutingJServer.jar rjsserver.jar

RoutingJServerClient.jar rjsclient.jar

RoutingJServerSamples.jar rjssamplesusa.jar



http://www.mapinfo.com/support/documentation/manuals.cfm



Software Requirements

Routing J Server is dependent upon the following software. If you perform a full installation, all of these components are installed for you.

� Java Runtime Environment 1.4.0 or higher.� JDOM beta9. Installed with the full installation, the server and client installation when

performing a custom installation.� Xerces 2.2.1. Installed with the full installation, the server and client installation when

performing a custom installation.� Web server that supports servlets or web server with plug-in to support servlets or

stand-alone servlet container. The servlet container or plug-in must support the 2.3 Servlet API specification.

Platform-Specific Requirements

Refer to the following sections for platform-specific information.

Windows 2000 You cannot use the Microsoft VM on the machine that will be using the MapInfo Routing J Server server because it does not support Java 2. The installer gives you the option of installing another JDK.

Sun Solaris Refer to the readme file that is included with your version of the JDK for relevant Java patch information for Solaris.

Performance Tuning

There are several things that can be done to improve the performance of the server.

� We strongly recommend using the Java HotSpot Server VM. Hotspot is included in the Java 2 SDK, Standard Edition v1.4. Information about hotspot is at http://java.sun.com/products/hotspot/. For UNIX, use the -server option of the Java application launcher to start the Java HotSpot Server VM. This option is available with JDK 1.4.

� We recommend installing data on a separate, stand-alone hard drive.� Do not distribute your virtual memory between partitions. We recommend having all of

your swap space in one location.



http://java.sun.com/products/hotspot/

http://java.sun.com/products/hotspot/

2
Installation and Setup
This chapter describes the installation process. The chapter also contains important setup and logging information.

In this chapter:

! Installation Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7! Installing Routing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7! Installing the MapInfo Routing J Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8! Installing on UNIX without a Graphics Card. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17! Testing the Routing J Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19! Installed Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19! Uninstalling the MapInfo Routing J Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20! Deployment Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20! Deploying the Routing J Server in Other Web Server Environments . . . . . . . . . . . . 20! Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Developer Guide Chapter 2: Installation and Setup

Installation Overview

Follow this general procedure as you install the MapInfo Routing J Server:

1. Install the data that your routing application will use. 2. Install the MapInfo Routing J Server.3. Test your installation.

Each step is described in detail in its own section, beginning on this page.

Installing Routing Data

Refer to the following sections for full or partial data installation instructions.

Full Data InstallationCopy the contents of the data CDs to one directory. To enhance performance, we recommend installing data on a separate, stand-alone hard drive. For a list of the contents and organization of the data CDs, go to http://www.mapinfo.com/support/documentation/manuals.cfm, and refer to the information in the Routing J Server section.

Partial Data InstallationBefore beginning a partial data installation, go to http://www.mapinfo.com/support/documentation/manuals.cfm, and refer to the information in the Routing J Server section for a list of the contents and organization of the data CDs. Use this information to determine the files necessary for your partial data install.

To install your routing data, copy the desired dataset(s) from the appropriate CDs. For example, for the Northeast region of the United States, copy the NorthEast directory.







Installing the MapInfo Routing J Server

To install the MapInfo Routing J Server:

1. Place the MapInfo Routing J Server Software CD in your CD-ROM drive.2. Run install.htm from the CD root. Select the link for your platform: Windows, Solaris,

Linux, or HP-UX. Alternatively, for the appropriate platform:� Windows

At the CD root, go to \InstData\Windows and run install.exe.

� SolarisAt the CD root, go to /InstData/Solaris and run install.bin.

� LinuxAt the CD root, go to /InstData/Linux and run install.bin.

� HP-UXAt the CD root, go to /InstData/Solaris and run install.bin.

3. At the Introduction dialog, read the information in the panel and click NEXT to proceed.




4. At the What�s New dialog, read about the new features in version 3.0 and click NEXT.

5. Choose to accept the License Agreement. Click NEXT. The Choose Product Features dialog displays.




6. At the Choose Product Features dialog, choose either FULL INSTALL or CUSTOM INSTALL. Click NEXT. A full install installs all product components, while custom gives you the option of which components to install. If you chose Full Install, proceed to step 8.

7. If you choose Custom Install in step 6, the Choose Product Components dialog displays. At the Choose Product Components dialog, select the components you want to install. Your options are:

� SERVER � installs the server components.� CLIENT � installs the client components.� SAMPLES � installs the product samples.� DOCUMENTATION � installs the product documentation.� EXAMPLE DEPLOYMENT ENVIRONMENT � installs an example web deployment

environment. This includes Tomcat 4.1.18.Depending on which components you choose, some of the following steps may not pertain to your installation process. CLICK NEXT. The Choose Install Folder dialog displays.

8. At the Choose Install Folder dialog, accept the default location to install the MapInfo Routing J Server or browse to another location. The Windows default location is <SYSTEM_DRIVE>\Program Files\MapInfo\RoutingJServer-3.0. On Solaris, Linux, and HP-UX, the default location is /opt/mapinfo/RoutingJServer-3.0. Click NEXT.




9. At the Locate Data dialog, choose the datasets or browse to the location of the datasets.

You will see the error message below if you do not specify a directory. Click NEXT.




10. At the Locate the Routing Update File Path dialog, choose the directory where update files are located when persistent updates are used. Accept the default directory or choose an existing directory from your machine. The Routing J Server installer needs write permission to this directory. Click NEXT.

11. At the Choose Shortcut Folder dialog, accept the default location to install application icons or browse to another location, or choose one of the other available options. Click NEXT.

12. At the Choose Java Virtual Machine dialog, select a Java VM from the available list. This must be a Java VM 1.4 or higher. Click NEXT.




13. At the Configure Sample Application dialogs, click YES if you want to configure. If you click NO, proceed to step 16 (if you choose not to configure the samples).




14. If you chose to integrate, specify the root location of the MapMarker J Server USA 3.1, the host name, and port number. By default, on Windows, MapMarker J Server USA 3.1 is installed at <SYSTEM_DRIVE>\Program Files\MapMarkerJServer-USA. Specify <SYSTEM_DRIVE>\Program Files in the By default, on Windows, MapMarker J Server USA 3.1 is installed at <SYSTEM_DRIVE>\Program Files\MapMarkerJServer-USA. Specify <SYSTEM_DRIVE>\Program Files\MapMarkerJServer-USA in the Specify the root location of MapMarker J Server 3.1 field.

Note: The installer looks for the location of the MapMarker-2.0 directory.

For Solaris, Linux, and HP-UX, MapMarker J Server USA 3.1 is installed at /opt/mapinfo/MapMarkerjserver-usa. Specify /opt/mapinfo/ in the Specify the root location of MapMarker J Server 3.1 field.

Click NEXT.




15. If you chose to integrate, enter the location of the installation folder for MapXtreme Java 4.5, the host name, and port number of the MapXtreme server at the second Configure sample application dialog.By default, on Windows, MapXtreme Java is installed at <SYSTEM_DRIVE>\Program Files\MapInfo\MapXtreme-4.5.0. Specify <SYSTEM_DRIVE>\Program Files\MapInfo in the Specify the root location of MapXtreme Java field.

For Solaris, Linux, and HP-UX, MapXtreme Java is installed at /opt/mapinfo/MapXtreme-4.5.0. Specify /opt/mapinfo/ in the Specify the root location of MapXtreme Java field.

Click NEXT.

16. At the Setup Web Environment dialog, enter the host name and port number at the Setup Web Environment dialog. Click NEXT.




17. The Pre-Installation Summary dialog displays. Review the information and click INSTALL or click PREVIOUS to make changes.

18. The Installing Routing J Server dialog launches.




19. At the View Read me dialog, click YES to look through the readme or click NO. Click NEXT.

20. At the Install Complete dialog, click DONE to leave the software installer.

Installing on UNIX without a Graphics Card

While it is possible to manual install the Routing J Server, MapInfo strongly recommends that you install on a machine that uses a graphics card. If you must perform a manual install, use the X-windows option or the Silent or Console option as described in the following sections.

X-windows Installation OptionUNIX developers who do not have a graphics card on their UNIX boxes need to have X-windows (X11) to run the Routing J Server installer. Using an X emulator, such as eXceed or KEA!X, will let you run and install on remote systems, without being at the computer itself. It is possible to install the product in X, but problems may occur. In general, make sure that you are using the certified versions of this type of software. There could be issues with the display manager, if it is set incorrectly. As MapInfo does not produce these X managers, we recommend that you run the installer in GUI mode, then use a UNIX box which has a graphics card installed in it. Once you have done this, follow the Solaris installation steps in the section, Installing the MapInfo Routing J Server on page 8.

Silent or Console Installation OptionOn a UNIX machine that does not have a graphics card to support the GUI install and does not have X-windows, you may perform a silent install and manually configure the files. You can use the Routing J Server, but will not be able to run the samples that come along with Routing J Server.

To run the installer in silent mode from the command line, type the command:

install.bin -i silent



When you perform a silent installation of Routing J Server, the product is by default installed at/opt/mapinfo/RoutingJServer-3.0. The chart below describes the changes that need to be made to the web.xml file after performing a console install.

Location: The place where you installed the product.

On a UNIX platform the default installation location is /opt/mapinfo/RoutingJServer-3.0.

Files: The files that need to be configured to use the Routing J Server.

Tags: The Routing J Server installer configures some files to deploy the product on your machine. It does this by replacing tags in the files with values specific to your environment. When you run the installer at the command line prompt, this configuration does not occur. Therefore, you will need to manually replace the tags in each file. The files that need to be changed, and the tags to replace in each file are as follows:

The following is an sample of the web.xml file that contains the two places where information must be added.

<init-param>

<param-name>datasetList</param-name><param-value></param-value>

</init-param><init-param>

<param-name>routingUpdateFilePath</param-name><param-value></param-value>

</init-param>

First, specify the parameter values for the parameter name datasetList. For example, for the United States installation, the datasets are: canada, central, midwest, northeast, pacific, and south. If the directories containing these datasets were in /opt/rjsDataUsa, you would specify the directories: /opt/rjsDataUsa/Canada; /opt/rjsDataUsa/Central, etc.

Second, specify the parameter values for the parameter name routingUpdateFilePath. This is the location where you want routing logs to be generated.

The following is an example of the web.xml file that has been modified correctly.

<init-param>

<param-name>datasetList</param-name><param-value>/opt/rjsDataUsa/Canada;/opt/rjsDataUsa/Central</param-value>

</init-param><init-param>

<param-name>routingUpdateFilePath</param-name><param-value>/opt/mapinfo/RoutingJServer-3.0/updates

Location Files Tags Replaced With

Tomcat-4.1\webapps\routing30\WEB-INF

web.xml parameter value for datasetlist � see the example below the table.

The semicolon separated list of data directories, which are used by Routing engine./opt/Data/Canada;/opt/Data/NorthEast;

parameter value for routingupdatefilepath � see the example below the table.

The directory where persistent updates will be stored. Files are created here at run-time by Routing J Server.


</param-value></init-param>

Testing the Routing J Server

Test the connection by opening an browser and going to http://<HOSTNAME>:<PORT_NUMBER>/routing30/servlet/routing?debug=true where HOSTNAME and PORT_NUMBER are the values you specified in step 16 of the installation process. The Server Status page displays useful information about the Routing J Server on your system.

Installed Components

The key routing files that are installed on your system are listed below.

Jar FilesThe jar files that are installed are listed below.

� rjsserver.jar � class files for MapInfo Routing J Server. It is installed only for Server Install and includes both server and client-side classes.

� rjsclient.jar � class files for MapInfo Routing J Server client. It is installed when the Client Install option is chosen and contains client classes only.

� rjssamplesusa.jar � class files for the samples that ship with the United States version of the Routing J Server.

Note: Versions of the Routing J Server for different geographies will have the appropriate jar file for their geography installed.

� micsys.jar � class files for units of measurement such as linear unit, time unit, angular unit, and velocity unit.

� miutil.jar � utility classes.� rjsdtds.jar � Routing J Server DTDs.� xmlParserAPIs.jar � XML parser.� xercesImpl.jar � xerces version 2.0.1 files.� jdom.jar � used for Java representation of an XML document.� log4j.jar � used to convey information such as errors and request tracing messages.� commons-collections.jar � used to convey information such as errors and request

tracing messages.� commons-lang.jar � used to convey information such as errors and request tracing

messages.� commons-logging.jar � used to convey information such as errors and request tracing

messages.




SamplesRouting places a directory of sample applications on your system. For Windows, the directory is at <INSTALL_DIR>\MapInfo\RoutingJServer-3.0\examples-<ISO 3 letter country code> (for example, \examples-usa). For Solaris, Linux, and HP-UX, the directory is at /opt/mapinfo/routingjserver-3.0/examples-<ISO 3 letter country code>. Refer to Chapter 10: Working with Routing Samples for more information.

Uninstalling the MapInfo Routing J Server

To uninstall the MapInfo Routing J Server from Windows, choose the uninstall shortcut on the Program menu under Routing J Server 3.0 or run the uninstall.exe from the directory <INSTALL_DIR>\Uninstall RoutingJServer-3.0.

To remove the MapInfo Routing J Server from Solaris, Linux, or HP-UX, run the uninstall.sh from the directory /opt/mapinfo/Uninstall RoutingJServer-3.0.

Deployment Environment

The MapInfo Routing J Server uses a servlet model to service requests. The Routing J Server requires a web server/servlet container to run, such as Apache/Tomcat, iPlanet, WebLogic, etc. As a convenience to users, we install and integrate Tomcat 4.1.18 with the Routing J Server as part of the product installation.

After installation, you will find the Tomcat directory in <INSTALL_DIR>\RoutingJServer-3.0\Tomcat-4.1. In the <INSTALL_DIR>\RoutingJServer-3.0\Tomcat-4.1\webapps directory will be the servlet contexts for the Routing J Server (\routing30) and routing samples (\rjssamples30<ISO 3 letter country code> for example, rjssamples30usa).

Deploying the Routing J Server in Other Web Server Environments

As part of the installation process, web archive (war) files are created and placed in the <INSTALL_DIR>\RoutingJServer-3.0\wars directory. The war files are:

� routing30.war � the main routing context� rjssamples30usa.war � routing samples

These war files can be deployed in any servlet container that supports war files.

Note: These files have information in them that ties them to the host machine on which they were installed.

Using the WARFile GeneratorTo run the WARFile Generator:




1. Download the WARfile generator from http://www.mapinfo.com/products/Download.cfm?ProductID=1144.

2. Click NEXT at the Introduction screen.

3. At the Choose Product Features screen, select the DEFAULT ROUTING WAR FILES option to create war files that represent the routing servlet context and routing sample context or select USER-SPECIFIED CONTEXT. This option allows you to choose a folder that points to a servlet context and creates a war file to a specified location with a specified name. Click NEXT.



http://www.mapinfo.com/products/Download.cfm?ProductID=1144

http://www.mapinfo.com/products/Download.cfm?ProductID=1144


4. At the Choose Install Folder screen, if you chose Default Routing War Files in the previous step, choose a directory to install the war files that represent the routing servlet context and routing sample context files. Click NEXT.If you chose User-Specified Context in the previous step, choose the directory where you want the war file to be created. Click NEXT and proceed to step 7.

5. At the Locate Data dialog, choose the datasets or browse to the location of the datasets.

You will see the error message below if you do not specify a directory. Click NEXT.




6. At the Locate the Routing Update File Path dialog, choose the directory where update files are located when persistent updates are used. Accept the default directory or choose an existing directory from your machine. The Routing J Server installer needs write permission to this directory. Click NEXT.

7. At the Configure Sample Application dialogs, click YES if you want to configure. If you click NO, proceed to step 10 (if you choose not to configure the samples).




8. If you chose to integrate, specify the root location of the MapMarker J Server USA 3.1, the host name, and port number. By default, on Windows, MapMarker J Server USA 3.1 is installed at <SYSTEM_DRIVE>\Program Files\MapMarkerJServer-USA. Specify <SYSTEM_DRIVE>\Program Files in the Specify the root location of MapMarker J Server 3.1 field.

For Solaris, Linux, and HP-UX, MapMarker J Server USA 3.1 is installed at /opt/mapinfo/mapmarkerjserver-usa. Specify /opt/mapinfo/ in the Specify the root location of MapMarker J Server 3.1 field.

Click NEXT.




9. If you chose to integrate, enter the location of the installation folder for MapXtreme Java 4.5, the host name, and port number of the MapXtreme server at the second Configure sample application dialog.By default, on Windows, MapXtreme Java is installed at <SYSTEM_DRIVE>\Program Files\MapInfo\MapXtreme-4.5.0. Specify <SYSTEM_DRIVE>\Program Files\MapInfo in the Specify the root location of MapXtreme Java field.

For Solaris, Linux, and HP-UX, MapXtreme Java is installed at /opt/mapinfo/mapxtreme-4.5.0. Specify /opt/mapinfo/ in the Specify the root location of MpXtreme Java field.

Click NEXT.

10. At the Network Information dialog, enter the host name and port number. Click NEXT.




11. At the Samples Logging file Location dialog specify the location where log files will be generated for the routing samples. For more information about logging, see Logging on page 27. Click NEXT.

12. At the Routing Logging file Location dialog specify the location where log files will be generated. For more information about logging, see Logging on page 27. Click NEXT.




13. The Pre-Installation Summary dialog displays. Review the information and click INSTALL or click PREVIOUS to make changes.

14. The Installing dialog launches.

15. At the Install Complete dialog, click DONE to leave the installer.

Logging

Routing J Server uses the Jakarta Commons logging API to convey information to you such as errors and request tracing messages. The Jakarta Commons logging API is an abstraction on top of a specific logging implementation. It allows you to make logging calls against a generic, high-level API, which will delegate to a real implementation discovered at run-time. The Routing installer sets up the Routing J Server to use log4j as a back-end logging implementation. It also provides the default log4j configuration files. On the server side, the log4j.properties file is installed in WEB-INF/classes folder under the tomcat routing context. On the client side, it is installed in the sample applications folder. Log4j configuration files can be




changed to suit your particular needs. Refer to the log4j manual at http://jakarta.apache.org/log4j/docs/manual.html for more information on how to configure logging levels, output destinations and logging message format.

Routing J Server uses the following logging levels:

Level Description/Purpose Example

FATAL An unexpected error has occurred, and has left the system in an unstable/unus-able state. Program execution cannot continue and the application must be restarted.

Servlet initialization failed because a configuration file could not be accessed.

ERROR An unexpected error has occurred which prevents the system from completely ful-filling the user's request. Program execu-tion can continue.

Wrong request HTTP header.

WARN An "expected" error has occurred from which the system can recover and com-plete the user's request.

A route or a multi-point route nor-mal calculation has failed and the query was processed using only major roads.

INFO Way to convey meaningful information to the user.

Server initialization messages.

DEBUG Shows trace information that can help prove that something is working as it should, or help decipher a problem.

� request type� time to parse request� time to get response from

engine� time to create xml response



http://jakarta.apache.org/log4j/docs/manual.html

http://jakarta.apache.org/log4j/docs/manual.html

3
Understanding Routing Basics
This chapter serves as an introduction to the basics of routing and the Routing J Server. Use the following sections as a starting point for developing your routing application.

In this chapter:

! Planning Your Routing Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30! Functionality Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30! Client Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30! Preference Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31! Routing Data Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31! Connection via HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32! Reference Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32! MapInfo Support and Resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Developer Guide Chapter 3: Understanding Routing Basics

Planning Your Routing Application

As you begin to think about the application that you are going to build, consider the following questions and topics to help you organize your plans. Start by answering these high-level questions.

� What specific issues will your application resolve?� How much customization do you want to do? Do you want to modify the text of the

directions that is returned by the server?� What other software will your application require? Does your application require the

geocoding capability of MapMarker or the display that MapXtreme Java provides?

Read through the overviews in this chapter to help guide you in finding the areas of documentation to explore further. Remember, too, that the sample applications are a valuable resource in designing your application.

Functionality Overview

The Routing J Server gives you the ability to create robust applications. MapInfo Routing J Server is servlet-based and can handle concurrent routing requests. The server can be optimized for shortest time or shortest distance with accompanying drive time estimates and distance travelled. When developing applications, you have a number of options in choosing functionality to meet your needs.

The Routing J Server provides you with six client classes and a multitude of preferences that you can use in designing your application. Learn more about the client classes and preferences available to you in this chapter and the following chapters.

Client Overview

The Routing J Server Java API provides you with five different types of client classes to meet your needs.

RoutingClientThe RoutingClient is used for creating routing client applications. An application initiates a connection with the server by creating a RoutingClient object. For more information, see Working with Routing Functionality on page 34.

MultiPointClientMultiPoint routing is the ability to route between intermediate points. The maximum number of points is limited by system capabilities. The routing server will find the shortest time or distance between all the points. For more information, see Working with Routing Functionality on page 34.




MatrixRouteClientUsing the MatrixRouteClient allows you to find the shortest paths between a number of start points and a number of destinations, and return the route costs. For more information, see Working with Routing Functionality on page 34.

IsoClientUsing the IsoClient allows you to obtain isochrones/isodistance. Isochrones and isodistance can be extremely valuable information for making decisions. For more information, see Working with the IsoClient on page 68.

RoutingDataClientThe RoutingDataClient is used for creating Java client applications that access the routing data. For more information, see Using the RoutingDataClient and Data Updates on page 75.

Preference Overview

The routing preference classes hold the client's routing preferences for the routing engine. There are a multitude of preferences that allow you to add the necessary functionality to your routing application. The preferences may be overridden by server preferences if the server preferences are more restrictive. For example, if the user requests driving directions and the server has them disabled, driving directions would not be returned. For a discussion of preferences, see Customizing Routing with Preferences on page 57.

Routing Data Overview

There are two types of data files: major roads and minor roads. The major road network data is used to route over long distances. The major road network is loaded into RAM. At least one file from the major road network must be loaded into RAM when the server starts. The minor road data (street-level data) contains the local streets. This data is used for local routing and to route from the major roads to the source and destination.

DatasetsData in Routing J Server 3.0 is organized differently than in previous versions. Data is now organized into datasets. A dataset is a collection of Routing J Server files stored in a single directory that allow for routing over some area. To use a specific dataset, copy the data from the data CD, keeping the directory structure. Then specify the directory when prompted during the software installation so the appropriate parameter is set in the web.xml.




To add a dataset after installation, add the directory name to the datasetList in the web.xml file.

For example:

<init-param><param-name>datasetList</param-name><param-value>

d:\mapinfo\RJS30data\usa\NorthEast;d:\mapinfo\RJS30data\usa\Pacific

</param-value></init-param>

Note: Unlike prior versions of Routing J Server, there is no longer an .omd file to rebuild.

Connection via HTTP

Requests are sent to a Web server via HTTP. The Web server communicates with the Routing J Server. The HTTP method requires a Web server that supports servlets and the URL of the machine with the servlet running to make the connection.

� This URL is of the format: http://localhost:8090/routing30/servlet/routing. Localhost is the name or IP address of the machine running the Web server. The port '8080' is the port that the Tomcat usually uses to listen for HTTP requests. By default, the installer will set up Tomcat to use port 8090 so that it does not conflict with any existing Tomcat installations (i.e., Tomcat used for MapXtreme Java).

� If you plan to create a Web server-based application, be sure to install all of the required jar files to a location that is acceptable to your Web server.

Reference Information

There are a number of places to obtain information while working on your routing documentation. For a complete listing of all Routing J Server product documentation, see the section, MapInfo Routing J Server Documentation on page 4.

If you are developing applications with the Java API, refer to the HTML documentation located in <Install_Dir>\RoutingJServer-3.0\docs.

If you are developing an application with the XML API, refer to the DTDs, or see Chapter 9: MapInfo Enterprise XML Protocol.

MapInfo Support and Resources

MapInfo�s Web site, www.mapinfo.com, provides a wealth of information and resources to help you with your Routing applications. The following areas may be of use when developing your applications.



http://www.mapinfo.com


Knowledge BaseMapInfo Technical Support also publishes a full knowledge base on all MapInfo products to the Support section of the Web site. For more information, go to http://testdrive.mapinfo.com/kbase_by_product.

Consulting ServicesThe MapInfo Consulting Services group works closely with customers to design, develop, and implement custom solutions. We provide a variety of consulting and technical advisory services to help you make the most of your investment in MapInfo technology. For more information, go to http://www.mapinfo.com/products/services/index.cfm.

TrainingGet the most out of your MapInfo investment with our comprehensive training courses. MapInfo training may be tailored to your specific needs so schedule the courses that fit your needs-in the order and at the level that best suits you. For more information, go to http://www.mapinfo.com/support/training/index.cfm.

Technical SupportMapInfo Corporation offers unparalleled technical support for users of MapInfo software products. You don't need to be an expert in all aspects of our products in order to get results as our Technical Support Department provides technical assistance to registered users of MapInfo software. For more information, go to http://www.mapinfo.com/support/tech_support/index.cfm.



http://www.mapinfo.com/products/services/index.cfm

http://www.mapinfo.com/support/tech_support/index.cfm

http://www.mapinfo.com/support/tech_support/index.cfm

http://www.mapinfo.com/support/training/index.cfm

http://www.mapinfo.com/support/training/index.cfm

http://testdrive.mapinfo.com/kbase_by_product


4
Working with Routing Functionality
This chapter explains routing functionality of the Routing J Server. Use this information to learn how to create simple routes, multipoint routes, and matrix route requests.

In this chapter:

! Routing Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35! Using the RoutingClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35! Using the MultiPointClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37! Using the MatrixRouteClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Developer Guide Chapter 4: Working with Routing Functionality

Routing Overview

The function of routing in Routing J Server is a simple one. Given two points, it finds either the route with the shortest distance or the route that takes the shortest time. Once the route has been found, you can interrogate the results to pull out the desired information. There are two types of information returned. The first is the point information that makes up the route. The Routing J Server breaks up the route into streets which contain segments that all have similar name(s) or attribution. The segments are made up of two or more points. Points are used for graphical display of the route. The user can specify what type of point information should be returned: all, end, or none. If all points are returned, all the points that make up the route will be returned. If end is specified, only the end points of the segments will be returned. If none is specified, no points will be returned. Specifying end or none will increase performance since returning points to the client is a significant data exchange.

In addition to the point information, driving direction information can be returned. Driving directions are used for giving a text description of the route. This information is returned as attributes on the route, street, and segment. A route is a path to travel from one place to another. The route contains total time and length information. A street a logical grouping of segments based on their attribution (including names). The street contains time, length, and name information. A segment is a portion of the street. The segment contains the turn angle, the distance, time, speed limit, road type, toll road, compass direction, alternate names, one way indicator, and roundabout indicator.

Using the RoutingClient

The RoutingClient is used for creating routing client applications. An application initiates a connection with the server by creating a RoutingClient object.

The following outlines the general process of finding a route using the Routing J Server. For more detail, refer to the RoutingClient section of the Javadocs.

1. Create a RoutingClient object.2. Create RoutePoint objects for the start and destination of the route.3. Find the route.4. Obtain the results.

Each step is explained in detail in the following sections.

Create a RoutingClient ObjectBefore you can use a RoutingClient object or its methods in your application, you must first initialize it. This is done with the following Java code:

routingClient = new RoutingClient("http://host:port/routing30/servlet/routing");




Create RoutePoint ObjectsOnce the RoutingClient object has been created, you must create the RoutePoint objects. This is done with the following Java code:

double startLong = -73.69996643;double startLat = 42.68251038;double endLong = -73.69578552;double endLat = 42.72847748;long roadLevel = 0;

RoutePoint startPoint = new RoutePoint(startLong, startLat, roadLevel);RoutePoint endPoint = new RoutePoint(endLong, endLat, roadLevel);

Find the RouteAfter you have created RoutePoint objects for the start and end points of the route, you can find the route. Create a RouteResult object and use the findRoute method to find a route and retrieve the information.

RouteResult result = routingClient.findRoute(startPoint, endPoint);

Obtain the ResultsThe last step in finding a route is extracting the result information. This example uses the getDirections method. Once you have obtained the directions, you can print them. This example prints the directions to the console window.

String directions = result.getDirections();System.out.println(directions);

Sample ResultsAfter you have executed the code, you should see the following results.

Route total time = 10.4 min, distance = 5.08 mi.Turn left on GLOBAL VW and travel East 0.01 mi (0.01 min).Turn right on JORDAN RD and travel South 0.8 mi (1.9 min).Turn left on US HWY 4/N GREENBUSH RD and travel North 3.9 mi (7.5 min).Turn left on DIVISION ST and travel West 0.3 mi (0.8 min).Turn right on RIVER ST and travel North 0.03 mi (0.10 min).Turn left on STATE HWY 2/FERRY ST and travel West 0.09 mi (0.2 min).Turn right on FRONT ST and travel North 0.00 mi (0.01 min).Turn left to reach your destination to the West.

RoutingClient FlexibilityThe RoutingClient() lets you specify preferences to use. If you do not create your own preferences, it uses the server preferences. To have the server return the preferences used when calculating routes, use the RoutingPreferences.setReturnActualPreferences(true) method. The preferences can then be retrieved using the RouteResult.getPreferences method. For more information on preferences, see Customizing Routing with Preferences on page 57.




Route InterfaceRouteResult, MultiPointResult and RouteSection implement Route interface. Route interface defines a route as a collection of street objects. Generic code can be written to handle all the objects implementing Route interface, for example:

public void processResult (Route result) throws DataNotAvailableException { // Get directions summary String directionsSummary = result.getDirectionsSummaryString(); // Get the points that make up the route. RoutePoint[] routePoints = result.getRoutePoints(); // Get the street information RouteStreet[] routeStreets = result.getRouteStreets(); String[] streetDirections = result.getStreetDirections(); Time [] streetTimes = result.getStreetTimes(); Distance [] streetDistances = result.getStreetDistances(); for (int i = 0; i < routeStreets.length; i++) { //Process each street. String streetName = routeStreets[i].getStreetName(); String streetDirection = streetDirections[i]; Time streetTime = streetTimes[i]; Distance streetDistance = streetDistances[i]; }

// Exercise other Route methods String directions = result.getDirections(); Time time = result.getTime(); Distance distance = result.getDistance(); Calendar startTime = result.getStartTime(); Calendar endTime = result.getEndTime(); RoutePoint[] intersections = result.getIntersections();}

Using the MultiPointClient

MultiPoint routing is the ability to route with intermediate points. The maximum number of points is limited by system capabilities. The routing server will find the shortest time or distance between all the points.

Generating a MultiPoint RouteUse the following steps as a guideline to generate a multipoint route using the Java API. For more detailed information, refer to the MultiPointClient section of the Javadocs.

1. Create MultiPointClient object.2. Optionally create a MultiPointPreferences object to specify user preferences.

Preferences include most of the routing preferences plus a few additional preferences for MultiPoint routing. Set the preferences for the MultiPointClient via MultiPointClient.setMultiPointPreferences().

3. Call MultiPointClient.findRoute(startPoint, endPoint, intermediatePointList) to find the route. The number of intermediate points is limited by system capabilities.




You can also specify a duration for each intermediate point in a MultiPoint route. For example, you can tell the server that the route should start at location A and pass through locations B, C, and D where you spend 5 minutes at each talking to customers. The route will then end at location E.

4. FindRoute returns a MultiPointResult object. This object can be queried for the results of the route. The route is returned as a list of RouteSections. Each RouteSection corresponds to a route between the start point and an intermediate point, two intermediate points, or an intermediate point and the end point. Since the RouteSection implements the Route interface, it will be similar to using the RouteResult. If a duration is specified on an intermediate point, it does not affect the previous section's end time, but does affect the next section's start time. For example, if the duration of 5 minutes is specified for location B, and B is reached at 4:00 PM, then the next section's start time would be 4:05 PM.

Using the MatrixRouteClient

Using Matrix routing allows you to find the shortest paths between a number of start points and a number of destinations, and return the route costs. The costs are the total time and distance of the individual route. The matrix route feature is extremely useful for situations such as the following. Given 500 start and 500 destination points, find the shortest paths between all the start points and all the destinations, and return the routes costs, i.e. their times and distances.

A Matrix route request defines N start points and M destinations. Almost all the algorithm constraints applicable to Route request are applicable to Matrix Route request. The constraints not available are include by point and time constraints.

The server response will contain an NxM matrix of route costs. The server will not return a fault response when the start and end points are the same.

Creating a Matrix RouteUse the following steps as a guideline to generate a matrix route using the Java API. For more detailed information, refer to the MatrixRouteClient section of the Javadocs.

1. Create a MatrixRouteRequest object with multiple start points and multiple destination points. There must be at least one start point and one destination point.

2. Optionally create a MatrixRoutePreferences object to specify user preferences. Set the preferences for the MatrixRouteRequest via MatrixRouteRequest.setPreferences().

3. Create a MatrixRouteClient object.4. Call MatrixRouteClient.findMatrixRoute(MatrixRouteRequest) to find the matrix route.

findMatrixRoute returns a MatrixRouteResponse object. This object can be queried for the results of the matrix route. The matrix route is returned as an array of route costs between start points and destinations, where RouteCost[i][j] is the cost of the route from start point number i to destination number j.

Successful Matrix Route Request ResponsesIn a successful response, MatrixRouteServlet returns an NxM matrix of route costs, where N is the number of start points and M is the number of destinations.




In an XML response, these route costs are delivered in the element MatrixRouteList. MatrixRouteList contains a number of RouteCostList elements, where each RouteCost contains route costs from one source to all destinations.

RouteCostList1 contains route costs: (start1, destination1),(start1, destination2) .. (start1,destinationM)

RouteCostList2 contains route costs: (start2, destination1),(start2, destination2) .. (start2,destinationM)

RouteCostListN contains route costs: (startN, destination1),(startN, destination2) .. (startN,destinationM).

In the Java API, MatrixRouteResponse is returned to the client, where the MatrixRouteResponse.getRouteCosts() method returns a matrix of RouteCost objects.

The RouteCost object stores the total time and distance of the route. It also has a flag indicating whether the cost was calculated by falling back to major roads. The engine will fall back to major roads if the following two conditions are satisfied:

� The engine failed to calculate a route in a normal way, for example, when routing from an island to the continent with no ferry between them.

� Fallback is allowed (the RoutingServlet initialization parameter, allowFallback, is set to true).If fallback is not allowed, and the data is disconnected, the RouteCost object will throw a RouteCalculationException and fellBackToMajorRoads=false.

For XML, the FallBackToMajorRoads RouteCost attribute is optional. It is only sent when it is true.

The fact that some routes in the matrix fall back to major roads or are incalculable does not affect the routes that can be calculated as normal. The matrix will contain the best possible routes that the server can find. Therefore, it may contain a mixture of normal, fallback, and zero costs.

The server will not return a fault response when the start and end points are the same. Instead, it will return the route cost of zero (i.e. total time and total distance equal to zero). This is different from simple route request processing. For simple routes, the server throws an exception in this case.

The server does not check whether you specify the same start point (or same end point) more than once, it is your responsibility to do so. Therefore, the resulting matrix route dimensions always match the request dimensions. The response to a successful request of N start points and M destinations will always contain an NxM MatrixRouteResponse.




Matrix Route Fault ResponseA routing fault response is returned if a problem occurs when calculating a matrix.

In the Java API, findMatrixRoute will throw a RoutingException.

A fault response applies to the entire matrix. For example, if the server Java heap size is not high enough, the RoutingException thrown by the server has the following message and code:

Message = "Out of memory reached while attempting request", error code = 5007.

If some routes in the matrix fail, but it is still possible to calculate others, an NxM matrix is returned to the user. Route costs of the failed routes are then set to zero. Routing from a point to itself, or a data disconnect are possible causes of such a failure.

Performance InformationSimilar to simple routes, matrix route performance is highly dependent on the nature of your request. Doing long distance routes, for example, takes longer and requires more RAM.

Large performance gains can be achieved for doing a matrix of routes with one source to multiple destinations. For example, performance gains can be achieved by doing a 1x5 route as opposed to 5 1x1 routes.

The quality of routes may be different when doing an NxM matrix and NxM routes sequentially. Matrix route distance may be slightly shorter when optimizing by distance, and matrix route time may be slightly smaller when optimizing by time.



5
Modifying Routing Directions
Routing directions are text instructions returned from Routing J Server that describe the how to follow the route. This feature is one of the most customizable features provide by Routing J Server.

In this chapter:

! Routing Directions Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42! Requesting Default Directions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42! DirectionsPreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43! Using DirectionsPreferences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45! Custom Directions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46! Using Directions Generators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46! Creating a DirectionsGenerator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47! Directions Generators and DirectionsPreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . 49! Configuring the Server for Generator Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50! Using the Generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50! Routing Directions Strings Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51! Turn Angle Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52! Routing Directions Token Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53! Creating Custom Directions on the Client Side . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54! Additional Routing Directions Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Developer Guide Chapter 5: Modifying Routing Directions

Routing Directions Overview

Routing J Server generates directions on the server-side for point-to-point and MultiPoint routes. A request can specify preferences to control the type and amount of information that is returned in the directions. In the default configuration, Routing J Server can return directions in a number of languages.

This chapter discusses the directions that Routing J Server returns and the effect of preference settings on the directions. At times, an application may require more customized directions than the default directions returned by Routing J Server. This chapter also discusses situations where you may require custom directions and how they may be created on the server.

Requesting Default Directions

By default, Routing J Server is configured to return directions. There are two places where this is configured. The first place is in the server settings. In order to obtain directions, the returnDirections initialization parameter of Routing J Server must be set to true (the installed default). The second place is in the preferences sent by the individual request. Once the server is configured to return directions, an individual request can have directions returned by setting DirectionPreferences.setReturnDirections() to true. By default, the DirectionsPreferences have setReturnDirections() set to true. If the server is configured not to return directions, the client will not be able to get these directions.

The following code sample illustrates how to get default directions:

Note: Routing preferences are not set because the server default is to return directions.// tell Routing J Server to calculate the route and return directionsRoutePoint startPoint = new RoutePoint(-81.9445, 41.4066, 0);RoutePoint endPoint = new RoutePoint(-87.7242, 41.8370, 0);RoutingClient routingClient = new RoutingClient

("http://localhost:8090/routing30/servlet/routing");RouteResult result = routingClient.findRoute(startPoint, endPoint);

There are several ways to get the directions:

// example 1: get the directions as an array of StringsString[] directionsArray = result.getStreetDirections();

// example 2: get the directions as a single String // (Note that this string contains a summary // string for the route in addition to the directions for each RouteStreet.String directionsString = result.getDirections();

//example 3: get the directions from each individual RouteStreetRouteStreet[] streets = result.getRouteStreets();for (int i=0; i < streets.length; i++) {directionsString = streets[i].getDirections();}




DirectionsPreferences

DirectionsPreferences are used to control the information returned in the default directions. In prior versions of Routing J Server, these preferences were directly part of RoutingPreferences and MultiPointPreferences. In Routing J Server 3.0, preferences that are related to directions generation were moved into the DirectionsPreferences class. A DirectionsPreferences object is now set on RoutingPreferences and MultiPointPreferences with the setDirectionsPreferences() method.

The preferences in DirectionPreferences are:

� directions style� focus� directions break turn angle� return directions� show time� show distance� show primary names only� directions generator name

Each of these preferences is discussed in the following sections.

Directions StyleRouting J Server returns two types of directions, normal and terse. Terse directions are shorter directions that are more suitable for wireless devices. The setDirectionsStyle() method is used to request normal or terse directions with the default being normal.

Note: The use of a custom generator may cause this specification to have no effect. Refer to the section, Using Directions Generators on page 46 for more information.

FocusA focused route is a subset of the whole route that concentrates on either the beginning or end of the route. A route focused at the start will route the user from their origin to (and including) the first major highway. A route focused at the end will route the user from the last major highway in the route (including that highway) to the destination. If there are no major highways in the route, the focused route will be the same as an un-focused route.

The setFocus() method is used to indicate whether to return directions for the whole route, only the start of the route, or only the end of the route. The default is to have no focus (i.e., return directions for the entire route).

DirectionsTurnBreakAngleThe setDirectionsTurnBreakAngle() method sets the turn angle value that determines when a street is broken into a new directions string. Sometimes, when following a route a street will make a significant turn while keeping the same name. By using this value, the user can specify the turn angle at which a new direction should be started. Valid values are 0 to 180 degrees. The default is 45 degrees.




ReturnDirectionsThe setReturnDirections() method is used to indicate whether or not directions for the route should be returned. The default is true.

ShowTimeThe showTime() method is used to indicate whether or not to show the time it takes to follow a direction in the route. In previous versions of Routing J Server, the only way to control showing time as part of the directions was to edit the properties file. For version 3.0, the showTime() method should be used. The default is true.


ShowDistanceThe showDistance() method is used to indicate whether or not to show the distance of a direction in the route. In previous versions of Routing J Server, the only way to control showing distance as part of the directions was to edit the properties file. For version 3.0, the showDistance() method should be used. The default is true.


ShowPrimaryNamesOnlyIt is often the case that a street contains multiple names. The showPrimaryNamesOnly() method is used to indicate whether all names for the street should be shown in the directions or only the primary name. If this method is set to true, only the primary name of the street will be used in the directions. If it is set to false, the primary name and all alternate names will be used. The default is false.


DirectionsGeneratorNameThe setDirectionsGeneratorName() method is used to specify which custom, server-side directions generator should be used. If the server is configured with one or more directions generators, this preference may be used to force directions generation to be handled by a specific generator. For instance, calling setDirectionsGeneratorName("myGenerator") will force the server to use the generator that has been configured with the name "myGenerator." If a generator with this name does not exist, an exception is thrown. Additionally, if the specified generator does not support the requested locale, an exception is thrown. By default, no value (null) is specified and the DefaultDirectionGenerator is used. The default direction generator works in the same manner as directions generation in previous versions of Routing J Server.




Using DirectionsPreferences

To use DirectionsPreferences:

1. Create a DirectionsPreferences object.2. Set the desired preferences.3. Use RoutingPreferences.setDirectionsPreferences(yourDirectionsPrefs) or

MultiPointPreferences.setDirectionsPreferences(yourDirectionsPrefs) to set the DirectionsPreferences

4. Use RoutingClient.setPreferences(yourRoutingPrefs) or MultipointClient.setPreferences(yourMultiPointPrefs) to set the preferences.

Use the following code as a guide to using DirectionsPreferences:

public DirectionsPreferences buildDirectionsPreferences() {

// create a DirectionsPreferencesDirectionsPreferences dirPrefs = new DirectionsPreferences();

// request terse directionsdirPrefs.setDirectionsStyle(DirectionsPreferences.STYLE_TERSE);

// set the focus to none, so the whole route is returneddirPrefs.setFocus(DirectionsPreferences.FOCUS_NONE);

// set the angle where streets are broken to 45 degreesdirPrefs.setDirectionBreakTurnAngle(

newAngle(45,AngularUnit.degree));

// indicate that we do want directions returneddirPrefs.setReturnDirections(true);

// the directions will not include the time to // travel each directions instructiondirPrefs.setShowTime(false);

// the directions will include the distance to// travel for each directions instructiondirPrefs.setShowDistance(true);

// only the primary street name will be included //in the directionsdirPrefs.setShowPrimaryNameOnly(true);

// if we had a generator regiestered that was called myGenerator,// the next line shows how to request that it be used// dirPrefs.setDirectionsGeneratorName("myGenerator");

// return the DirectionsPreferences. These preferences are // included in the request preferences by calling either // RoutingPreferences.setDirectionsPreferences(dirPrefs) for// a point to point route request or MultiPointPreferences.// setDirectionsPreferences(dirPrefs) for a multipoint route// request.return dirPrefs;}




Custom Directions

There may be times when your application requires directions in a style or format that can not be generated by simply setting the DirectionsPreferences. Some examples of these cases are:

� Your application requires natural language directions in a language in which words (such as articles) change based on the gender of other words.

� Your application requires directions with a different sentence structure than provided by the default directions.

� Your application requires specialized processing of streets and segments for the creation of directions.

� Your application requires the use of additional information (i.e. database, lookup table) to generate directions.

Depending on your application's needs, custom directions can be generated in a number of ways:

� Using a Directions Generator. (recommended)� Editing the DirectionsStrings.properties files.� Writing custom directions on the client side. (not recommended)

Using Directions Generators

Routing J Server provides the ability for an advanced user to perform server-side customization of directions via a new DirectionsGenerator interface that provides a mechanism for creating a direction string for each transition in the route. A transition is the definition of the passage of one street to another in a route. Examples of transitions include: going from a street to another street; going from a street to a highway; going from a street to a roundabout, going from a ferry to a street, exiting a street via a ramp, etc. Refer to the javadocs of the Transition class for a complete list. A directions generator is responsible for examining each transition in the route and creating an appropriate directions string. These generators may be added or removed as necessary via an XML configuration file. Note that the servlet must be restarted for any changes in this configuration file to take effect.

A new instance of the generator is created for each request that uses it. Therefore, it is important to note that any non-static member variables defined in the generator will not persist through multiple requests.

How to Create a Directions Generator1. Create the DirectionsGenerator.

a. Create a class that implements the DirectionsGenerator interface (or inherits from DefaultDirectionsGenerator)

b. For your class, implement the methods:init()

getSupportedLocales()

generateSummaryString()

generateDirections()

c. Compile your directions generator with rjsserver.jar on your classpath.




2. Configure the Routing J Server, through the directions-registry.xml file, so that it knows about the generator.

3. Test the server�s use of the generator.

Creating a DirectionsGenerator

When creating a DirectionsGenerator, you can use the extension of an existing generator or implement the DirectionsGenerator interface. These situations are explained in the following sections.

Extension of an Existing GeneratorFor simple customization, it may be sufficient to use the default directions generator as a basis for a new generator. This can be done by extending the DefaultDirectionsGenerator class (or another existing generator). For instance, to create a module that changes how ferry directions are handled, create a new class that inherits from DefaultDirectionsGenerator and override the generateDirections() method as follows:

public String generateDirections(Transition t) {if (t.getDescription() == Transition.TRANSITION_TYPE_STREET_TO_FERRY) {return "Get on the ferry";} else if (t.getDescription() ==

Transition.TRANSITION_TYPE_FERRY_TO_STREET) {return "Get off the ferry and turn onto " +

t.getToStreet().getStreetName();} else {

return super.generateDirection(t);}}

Since the DefaultDirectionsGenerator handles multiple languages, any custom generator that inherits from it should either support the same locales or override the getSupportedLocales() method to specify which locales are handled by this extension. For instance, the previous example has hard-coded English strings so this module should also override getSupportedLocales() as follows:

public Locale[] getSupportedLocales() {return new Locale[] { new Locale("en") };}

Otherwise, the server may use this generator for a language it does not support. For instance, if German directions are requested and the getSupportedLocales() method is not overridden, this module would be used and directions for ferries would be in English while the rest would be in German.

If customization requires the knowledge of the DirectionsPreferences or Locale for the requested route, the DefaultDirectionsGenerator makes these available through the getDirectionsPreferences() and getLocale() methods. For example, if the user has requested that all names (not just primary) be returned in the directions (via the DirectionsPreferences.showPrimaryNamesOnly() method), the previous example would not




handle this case. It is coded such that only the primary name will always be returned for ferry-to-street directions (since the getStreetName() method is being used). To fix this, we would need to modify our code as follows:

else if (t.getDescription() ==Transition.TRANSITION_TYPE_FERRY_TO_STREET) {if (getDirectionsPreferences().showPrimaryNameOnly()) {

return "Get off the ferry and turn onto " +t.getToStreet().getStreetName();

} else {return "Get off the ferry and turn onto " +DirectionsUtil.getStreetNamePlusAlts(t.getToStreet);

}}

It is important to note that a new instance of the generator object is created for each request with the init() method being called to initialize that instance. Therefore, if the init() method is being overridden in the custom generator, it is important to call super.init() to ensure that the DefaultDirectionsGenerator is initialized properly.

Implementation of the DirectionsGenerator InterfaceIn some cases, it may not be possible or useful to inherit the functionality of the DefaultDirectionsGenerator or another existing generator. These cases would include situations where many of the directions would need to change. For example, when implementing a generator to provide natural language directions in languages where the gender of the street name would affect the article in the sentence, it would probably be necessary to change every string generated.

Another example would be when your application requires additional information in the directions such as from a database or lookup table. Since the directions generator modules are defined by the DirectionsGenerator interface (which the DefaultDirectionsGenerator also implements), it is possible to implement this interface to create a generator.

For your class, you will need to implement the methods:

� init()� getSupportedLocales() � generate SummaryString()� generateDirections()

Additionally, there are two classes that may help in building your own directions generator. The DirectionsUtil class contains methods provide further analysis and processing of route information.

The UnitFormat class, which was modeled after NumberFormat, is used to get a String representation of a time, distance, or angles. Instead of creating a string with the scalar value of the unit and the unit itself (.5 mi.), it may convert the value to a more appropriate scale. For instance, when formatting a distance of .001 mi, it may be more appropriate to write 1.76 yd or 5.28 ft.




The following table describes the hierarchy of units:

For distances, the Routing J Server moves to the next unit in the hierarchy if the value distance is less than .2 units. For time, the Routing J Server moves to the next unit in the hierarchy if the value time is less than 1 unit.

For simple localization, the UnitFormat class uses the abbreviation of the unit in the formatted string rather than the English name of the unit. For more information on DirectionsUtil and UnitFormat, please refer to the Routing J Server javadocs.

For an example of how to create a custom generator, see the sample directions generator sample code provided with the Routing J Server samples in the RoutingJServer-3.0/examples-usa/direction directory.

Directions Generators and DirectionsPreferences

Regardless of how the custom module is created, it is important to remember that certain preferences (in DirectionsPreferences) rely on the implementation of the generator. If a custom generator does not handle these preferences (or inherits from the DefaultDirectionsGenerator and breaks the existing implementation of these preferences), client applications may not function correctly. For instance, correct functionality of DirectionsPreferences.showPrimaryNameOnly() relies on code in the generator to set the street name of the direction string according to how this preference is set. Currently, the following directions preferences are affected by this:

� Show time� Show distance� Primary name only� Directions style (normal vs. terse)

English Metric Time

Mile Kilometer Hour

Yard Meter Minute

Foot Centimeter Second

Inch



Configuring the Server for Generator Use

The generators to be used by Routing J Server are specified in the directions-registry.xml configuration file to be placed in the classpath (e.g., {RJS_TOMCAT_CONTEXT}\classes). The following DTD describes the format of this file:

<!ELEMENT DirectionsRegistry (DirectionsGenerator*)><!ELEMENT DirectionsGenerator (Name, Class, Description?, Comment?)><!ELEMENT Name (#PCDATA)><!ELEMENT Class (#PCDATA)><!ELEMENT Description (ShortDescription, LongDescription?)><!ELEMENT ShortDescription (#PCDATA)><!ELEMENT LongDescription (#PCDATA)><!ELEMENT Comment (#PCDATA)>

The directions-registry.dtd can also be found in rjsdtds.jar provided with the full installation of Routing J Server.

Using the Generator

Routing J Server is responsible for finding an appropriate DirectionsGenerator for each route and multipoint request. There are several ways that the Routing J Server determines the appropriate generator to use.

User Specified Generator (By Name)A request, through DirectionsPreferences.setDirectionsGeneratorName(), may specify a specific generator to be used. The specified name corresponds to the "Name" field in the configuration file. If the name is not found or the generator specified by name does not support the directions' locale for the route, an exception is thrown.

By LocaleIf a DirectionsGenerator name is not specified, the Routing J Server attempts to match an available generator based on the requested locale.

By LanguageIf an exact match to the locale is not found, Routing J Server attempts to match based on just the language specified by the user. This is analogous to the way the ResourceBundle will fall back to a language locale if no country specific locale is available. Finally, if no generator has been found, the default generator is used.


Default GeneratorThe default generator works similar to the way directions generation worked in earlier versions of Routing J Server. It uses the DirectionsStrings.properties files located in rjsserver.jar.

Routing Directions Strings Files

DirectionsStrings_xx_YY.properties, where xx is the two letter language code and YY is the two letter country code, (located in the RoutingJServer.jar file) contains template strings that are used in creating the default directions returned by Routing J Server.

When to Edit the FilesYou may want to edit the DirectionsStrings.properties files in cases where you are generally satisfied with the default directions, but want to change an individual word. For example, the default properties file says "travel" and you want your directions to say "proceed". If you find that you need to change the structure of the sentences, then a DirectionsGenerator would be a better solution. Note that editing these files affects the expected behavior of the DefaultDirectonsGenerator since the DefaultDirectonsGenerator uses these files.

How the Direction Strings files Are UsedThe Routing J Server reads these strings from the DirectionsStrings.properties file and replaces the first occurrence of the {0}, {3}, {5}, and {1} tokens with the turn angle, distance, time, and street name strings respectively. Routing J Server also has the ability to provide terse directions (terseDirectionsStrings_xx_YY.properties). The following sections exhibit both normal and terse strings. You can edit these strings to change the way directions are described. Be aware that changing these files will affect the DefaultDirectionsGenerator.

The normal directions strings are:

//Strings for the street and route directions stringsPOINT_TO_ROAD_DIRECTIONS=BEGIN_ON_ROAD_DIRECTIONS=Begin on {1} {2} and travel {3} {4} ({5}).FOCUSED_BEGIN_ON_ROAD_DIRECTIONS=Continue from {1}{2} and travel {3}.FIRST_STREET_DIRECTIONS={0} on {1} {2} and travel {3} {4} ({5}).NAMED_LAST_STREET_DIRECTIONS={0} on {1} to reach your destination to the {3}.LAST_STREET_DIRECTIONS={0} to reach your destination to the {3}.FOCUSED_NAMED_LAST_STREET_DIRECTIONS={0} on {1} and continue to your destination.FOCUSED_LAST_STREET_DIRECTIONS={0} and continue toward your destination.STREET_DIRECTIONS={0} on {1} {2} and travel {3} {4} ({5}).RAMP_DIRECTIONS={0} on {1} to {6} {2} bearing {3} {4} ({5}).FERRY_DIRECTIONS=Board {1}.ROUNDABOUT_DIRECTIONS=Enter {1}.HIGHWAY_FROM_RAMP_DIRECTIONS=Continue onto {1} {2} and travel {3} {4} ({5}).UNNAMED_STREET=Un-named streetUNNAMED_RAMP_NAME=the rampUNNAMED_FERRY_NAME=the ferryUNNAMED_ROUNDABOUT_NAME=the roundaboutLEFT_EXIT=Exit to the leftRIGHT_EXIT=Exit to the rightSTRAIGHT_EXIT=Exit




TOLL_ROAD=(Toll road)ROUTE_SECTION_SUMMARY=Route section total time = {5}, distance = {4}.ROUTE_SUMMARY=Route total time = {5}, distance = {4}.INTERMEDIATE_POINTS_SUMMARY=Intermediate points in order are:INTERMEDIATE_POINTS_DETAIL= ({0}, {1}, {2})NORTH=NorthSOUTH=SouthEAST=EastWEST=WestNORTHEAST=NortheastNORTHWEST=NorthwestSOUTHEAST=SoutheastSOUTHWEST=Southwest

The terse strings are:

//Strings for the street and route driving directions stringsPOINT_TO_ROAD_DIRECTIONS=BEGIN_ON_ROAD_DIRECTIONS=Begin on {1} {2} and travel {4}.FOCUSED_BEGIN_ON_ROAD_DIRECTIONS=Continue from {1}{2} and travel {3}.FIRST_STREET_DIRECTIONS={0} on {1} {2} {4}.NAMED_LAST_STREET_DIRECTIONS={0} on {1} to reach your destination to the {3}.LAST_STREET_DIRECTIONS={0} to reach your destination to the {3}.FOCUSED_NAMED_LAST_STREET_DIRECTIONS={0} on {1} and continue to your destination.FOCUSED_LAST_STREET_DIRECTIONS={0} and continue toward your destination.STREET_DIRECTIONS={0} on {1} {2} {4}.RAMP_DIRECTIONS={0} on {1} to {6} {2} {4}.FERRY_DIRECTIONS=Board {1}.ROUNDABOUT_DIRECTIONS=Enter {1}.HIGHWAY_FROM_RAMP_DIRECTIONS=Continue on {1} {2} {4}.UNNAMED_STREET=Un-named streetUNNAMED_RAMP_NAME=the rampUNNAMED_FERRY_NAME=the ferryUNNAMED_ROUNDABOUT_NAME=the roundaboutLEFT_EXIT=Exit LRIGHT_EXIT=Exit RSTRAIGHT_EXIT=ExitTOLL_ROAD=(Toll road)ROUTE_SECTION_SUMMARY=Route section total time = {5}, distance = {4}.ROUTE_SUMMARY=Route total time = {5}, distance = {4}.INTERMEDIATE_POINTS_SUMMARY=Intermediate points in order are:INTERMEDIATE_POINTS_DETAIL= ({0}, {1}, {2})NORTH=NSOUTH=SEAST=EWEST=WNORTHEAST=NENORTHWEST=NWSOUTHEAST=SESOUTHWEST=SW

Turn Angle Strings

The string used for the turn angle can be customized. In the DirectionsStrings_xx_YY.properties file, where xx is the two letter language code and YY is the two letter country code, (located in the rjsserver.jar file) there are a series of strings defining the text to display for the turn angle in 10 degree increments. Negative turn angles are for right




turns and positive turn angles are for left turns. You can edit these strings to change the way turns are described. Terse turn angle strings are also available (terseDirectionsStrings_xx_YY.properties). The following sections exhibit both normal and terse strings.

Some examples of the normal turn angle strings are:

// The following strings are for the turn anglesANGLE_0_TO_10=ContinueANGLE_11_TO_20=Turn leftANGLE_21_TO_30=Turn leftANGLE_31_TO_40=Turn leftANGLE_41_TO_50=Turn leftANGLE_51_TO_60=Turn leftANGLE_61_TO_70=Turn leftANGLE_71_TO_80=Turn leftANGLE_81_TO_90=Turn leftANGLE_91_TO_100=Turn leftANGLE_101_TO_110=Turn leftANGLE_111_TO_120=Turn leftANGLE_121_TO_130=Turn leftANGLE_131_TO_140=Turn leftANGLE_141_TO_150=Turn leftANGLE_151_TO_160=Turn leftANGLE_161_TO_170=Turn leftANGLE_171_TO_180=Make a sharp leftANGLE_MINUS_0_TO_10=ContinueANGLE_MINUS_11_TO_20=Turn rightANGLE_MINUS_21_TO_30=Turn rightANGLE_MINUS_31_TO_40=Turn rightANGLE_MINUS_41_TO_50=Turn rightANGLE_MINUS_51_TO_60=Turn rightANGLE_MINUS_61_TO_70=Turn rightANGLE_MINUS_71_TO_80=Turn rightANGLE_MINUS_81_TO_90=Turn rightANGLE_MINUS_91_TO_100=Turn rightANGLE_MINUS_101_TO_110=Turn rightANGLE_MINUS_111_TO_120=Turn rightANGLE_MINUS_121_TO_130=Turn rightANGLE_MINUS_131_TO_140=Turn rightANGLE_MINUS_141_TO_150=Turn rightANGLE_MINUS_151_TO_160=Turn rightANGLE_MINUS_161_TO_170=Turn rightANGLE_MINUS_171_TO_180=Make a sharp rightANGLE_DEGREES=Turn degrees =

Routing Directions Token Definitions

In Routing J Server versions 1.0 through 1.5.1, the replaceable parameters were specified by tokens

in the strings of the form %a, %s, %c, etc. These values have been changed to {1}, {2}, etc. as per

JAVA string formatting standards. The following table lists the old to new conversions.



.
Creating Custom Directions on the Client Side

With the addition of server side DirectionsGenerators in Routing J Server 3.0, it is no longer recommended that custom directions be generated on the client side. As a result, the preferences for changing directions string templates are no longer available on the client side.

There are several advantages to creating directions on the server-side using a DirectionsGenerator:

� Allows for a thinner client.� Data returned in request may be minimized.� More powerful.� Cleaner implementation.

The information provided in this section is provided for backwards compatibility purposes only. It will be removed in a future release.

Although it is not recommended to access segment data directly and build your own directions on the client-side, you are able do this by processing the street, segment, and point structures. Each street is made up of a number of segments that all have similar attribution, and each segment is made up of a number of points.

Note: To get this information on the client, the server must be configured to return segment data via the returnSegmentData initialization parameter.

Here is an example of processing the street, segment, and point structures to retrieve the information:

public void processResult(Route result) throwsDataNotAvailableException{

RouteStreet[] routeStreets = result.getRouteStreets();for (int i = 0; i < routeStreets.length; i++){// Get the information about the streetRouteStreet street = routeStreets[i];tring streetName = street.getStreetName();

Version 1.5.1 tokenVersion 2.0 and

above token Definition

%a {0} turn angle

%s {1} street name

%e {2} toll road indicator

%c {3} compass direction

%d {4} distance

%t {5} time

%n {6} next street name

n/a {7} roundabout exit count




Time streetTime = street.getStreetTime();Distance streetDistance = street.getStreetDistance();

// Now get the segments that make up this street.RouteSegment[] routeSegments = street.getRouteSegments();for (int j = 0; j < routeSegments.length; j++){

RouteSegment segment = routeSegments[j];// Get the information about the segmentString[] alternateNames = routeSegments[j].getAltNames();Time segmentTime = segment.getSegmentTime();Distance segmentDistance = segment.getSegmentDistance();Angle turnAngle = segment.getSegmentTurnAngle();int compassDirection = segment.getCompassDirection();Velocity speedLimit = segment.getSegmentVelocity();RoadType roadType = segment.getRoadType();boolean isTollRoad = segment.getIsTollRoad();int oneWayIndicator = segment.getOneway();boolean isRoundabout = segment.getIsRoundabout();

// Get the points that make up the segment.RoutePoint[] segmentPoints = segment.getRoutePoints();

}}

Additional Routing Directions Information

Removing Parentheses from DirectionsBy default, times for directions display with parentheses. To remove these parentheses, delete the parentheses in the appropriate properties file. Notice in the following example ({5}) becomes {5}.

Line in unedited properties file:

BEGIN_ON_ROAD_DIRECTIONS=Begin on {1} {2} and travel {3} {4} ({5}).

Line in edited properties file:

BEGIN_ON_ROAD_DIRECTIONS=Begin on {1} {2} and travel {3} {4} {5}.

Roundabout SupportRouting J Server 3.0 also includes improved roundabout support. For directions requested in English, the directions may read "Take third exit onto MAIN ST...." While not available for other languages by default, the information needed to create this type of string in a custom module is available through the DirectionsUtil class. For simple usage of this information, the {7} token definition (for the DirectionsStrings.properties files) is the integer that corresponds to the exit count. Currently, none of the DirectionsStrings.properties make use of this value.




Directions Strings that Contain ApostrophesAn error may occur if there is an apostrophe in the DirectionsStrings file. The occurrence of an apostrophe causes an error that prevents the tokens from being replaced with the correct words. For example:

NAMED_LAST_STREET_DIRECTIONS={0} sur {1} avant d'arriver à votre destination au {3}. // causes problemNAMED_LAST_STREET_DIRECTIONS={0} sur {1} avant d''arriver à votre destination au {3}. // works

The workaround is to replace the apostrophe with two apostrophes.



6
Customizing Routing with Preferences
The Routing J Server provides preference classes that allow you to customize your routing application to meet any of your needs. The following sections discuss the preference classes and methods that are available to you. For a complete listing, refer to the object model diagram and the HTML API documentation.

In this chapter:

! RoutingPreferences Class Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58! Returning Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58! Using Per Request Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60! Working with Includes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60! Setting the Timeout Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61! Setting Travel Preferences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61! Working with Time-based Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62! Routing J Server Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66! MultiPointPreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Developer Guide Chapter 6: Customizing Routing with Preferences

RoutingPreferences Class Overview

The RoutingPreferences class holds the client's routing preferences for the routing engine. You can specify settings in a preferences object. The preferences may be overridden by server preferences if the server preferences are more restrictive. For example, if the user requests driving directions and the server has them disabled, driving directions would not be returned. For server settings, the web.xml file is used to configure server preferences on a system-wide basis. Default settings are divided into server defaults and client defaults. Server defaults are what the server uses when no init parameter is set. Client defaults are used when the you set some, but not all, preferences in a preferences object.

Algorithm Preferences

The Routing J Server provides you with optimizeBy to determine the best way to return your route.

optimizeBySets the optimization target to distance or time. It may be one of the following values:

� RoutingPreferences.OPTIMIZATION_SHORTEST_TIME � RoutingPreferences.OPTIMIZATION_SHORTEST_DISTANCE

Returning Data

The Routing J Server gives you a number of options to return data. The following methods are available to you.

returnActualPreferencesSets the flag to return actual preferences used for the route. This flag is false by default. If false, the RouteResult.getPreferences() method will return null. The returnActualPreferences flag can be set to true if the client wants to have the preferences that the server actually used for the for the route request) returned.

If a routing preference is not set on the client, the server default is used. If a client preference is set but the server preference is more restrictive, it overrides the client preference.

optimizeBySets the optimization target to distance or time. It may be one of the following values:

� RoutingPreferences.OPTIMIZATION_SHORTEST_TIME � RoutingPreferences.OPTIMIZATION_SHORTEST_DISTANCE




returnAllPointsReturns true if all shape points are being returned, false otherwise.

returnEndPointsReturns true if end points are being returned, false otherwise.

returnSegmentDataSets the flag to return segment data. The segment data is the data that is necessary to create the driving directions and contains detailed information on each segment in the route. This information is necessary if you want to create your own driving directions. It includes the following:

� the street names (including alternate names) � the languages for the street names� compass direction � ID � one way boolean � roundabout boolean � toll road boolean � road type � speed limit � turn angle � time to traverse the segment � distance along the segment

returnSegmentGeometrySpecifies what shape points to return. The following are the valid values:

� RoutingPreferences.NONE � RoutingPreferences.END � RoutingPreferences.ALL

returnSegmentGeometryStringReturns a string that indicates what shape points are being returned: all, end or none.




Using Per Request Updates

Per request updates allow you to change road values for an individual route request. The following per request update method is available to you.

addUpdateUse this method to add any of the following types of updates:

� SegmentSpeedUpdate � SegmentSpeedUpdateRelative � SegmentSpeedPercentageUpdate � PointSpeedUpdate � PointSpeedUpdateRelative� PointSpeedPercentageUpdate� RoadTypeSpeedUpdate � RoadTypeSpeedUpdateRelative � RoadTypeSpeedPercentageUpdate � SegmentExclude � PointExclude � SegmentRoadTypeUpdate

For more information on updates, see Modifying Data with Updates on page 77.

Working with Includes

Include gives you the ability to specify what points and/or segments to include from a given route. These includes can be specified as a RoutingPreference.

There are also methods in RoutingPreferences to:

� get back the points or segments that were specified in the include,� clear include.

Using IncludeTo use include:

1. Create a RoutingClient application.2. Create a RoutingPreferences object.3. Use RoutingPreferences.setIncludedPoints() to specify what to include.

Note: When you set coordinates, the x parameter is the longitude and the y parameter is the latitude.

4. Set the RoutingPreferences via RoutingClient.setRoutingPreferences().5. To see the impact on results, generate a route.




IncludeIncludes can be specified by a point. When including points, the points will be included in the order that you add them to the preferences. In the route, include a specific point. If more than one point is specified, be sure to include points in the order that they should be traversed.

Note: Includes to do not apply to multipoint routes.

Setting the Timeout Value

The timeout value specifies the approximate maximum amount of time (in milliseconds) to try to calculate the shortest path. Once the timeout value is reached, the server will stop and throw a RoutingException. You can not set the timeout value to be more than the timeout value on the server. The following table list the default values.

Using a high timeout value uses more server resources but will return a route more often than a low timeout value. Using a low timeout value ensures that no one request uses too much server resources, but may result in more failed routes.

Setting Travel Preferences

This set of preferences allows you to set the desirability for each RoadType. For instance, you can request that the server attempt to avoid all of the major road types. There are four levels of desirability:

� High � there is a strong preference towards this RoadType� Medium � treat this RoadType with a normal preference� Low � there is a strong preference against this RoadType� Avoid � If at all possible, do not use this RoadType

Note: In no case will the server guarantee that the RoadType is avoided. Depending on the situation, the alternative to an avoided RoadType may be so poor that the server will still choose a route that uses the avoided RoadType. Also, if the starting or ending point lies along a segment whose RoadType has been avoided, the server will still use that segment.

If no preference is specified for a RoadType, the server defaults to Medium.

Client Value (in milliseconds)

Route 500000

Data 500000

Multi 600000

Matrix 1200000

Iso 600000000




Using a Travel PreferenceTo use a Travel preference:

1. Create a RoutingClient application.2. Create a RoutingPreferences object.3. Use RoutingPreferences.setTravelPreference(RoadType, short) with any of the

available road types and any of these four available static member variables (RoutingPreferences.ROAD_TYPE_PREFERENCE_LOW, RoutingPreferences.ROAD_TYPE_PREFERENCE_MEDIUM, RoutingPreferences.ROAD_TYPE_PREFERENCE_HIGH, RoutingPreferences.ROAD_TYPE_PREFERENCE_AVOID).

4. Set the RoutingPreferences via RoutingClient.setRoutingPreferences().5. To see the impact on results, generate a route.

Working with Time-based Routing

Routing J Server allows you to return routes with the addition of data in the form of time and date. Adding time as a component to routing allows you to specify a start time or end time for the route. Both cannot be specified.

You can also specify a duration for each intermediate point in a MultiPoint route. For more information, see Generating a MultiPoint Route on page 37.

Usage ExampleUse the following code sample as a guide for creating time-based routes.

RouteResult result = null;RoutingClient routingClient = null;try {// initialize the clientroutingClient = new RoutingClient(ROUTING_URL);

// get the preferences for the clientRoutingPreferences routingPreferences = new RoutingPreferences();

// create an instance of the calendar objectjava.util.Calendar cal = java.util.Calendar.getInstance();

// optional - set to a specific timecal.set(2005, Calendar.NOVEMBER, 12, 3, 16);

// set the start time for the route to the newly created calendar objectroutingPreferences.setStartTime(cal);// or - routingPreferences.setEndTime(cal);

// set the preferences on the clientroutingClient.setRoutingPreferences(routingPreferences);

// get the routeresult = routingClient.findRoute(start, end);}catch (java.net.MalformedURLException e) { e.printStackTrace(); }catch (java.io.IOException e) { e.printStackTrace(); }catch (RoutingException e) { e.printStackTrace(); }




// create a format object to output the calendar objectjava.text.DateFormat df = java.text.DateFormat.getDateTimeInstance(java.text.DateFormat.LONG, java.text.DateFormat.LONG);

// make sure we found a routeif (result != null) {// output the total time of the routeSystem.out.println("TotalTime: " + result.getRouteTimeString());

// output the start and end time for the routeSystem.out.println("Start Time: " + df.format(result.getStartTime().getTime()));System.out.println("End Time: " + df.format(result.getEndTime().getTime()));

// loop through each street in the routeRouteStreet[] streets = result.getRouteStreets();for (int n = 0; n < streets.length; n++) {

// output the street name, start, and end time for each streetSystem.out.println(street.getStreetName());System.out.println(" Start Time: " +

df.format(street.getStartTime().getTime()));System.out.println(" End Time: " +

df.format(street.getEndTime().getTime()));}}

Using Time Zones in Routes

Making Routing J Server aware of time zones is important for any routes that pass through multiple time zones. Time zones support includes the following:

� Specify a local time at the route start point or a local time at the destination.� Specify an offset from Coordinated Universal Time for the route start or end time. � The route result returned will provide local time at the start point and local time at the

destination. The start and destination points' time zone information will also be included in the result.

Key terms for using time zones include:

� Time-of-day � An absolute time consisting of the 24 hour clock time, date and time zone information.

� Time interval � A duration of time consisting of a numeric value and time unit, e.g. 3 hours.

� Local time-of-day � The time-of-day relative to the route points. � UTC offset � The total offset from Coordinated Universal Time considering both GMT

offset and DST offset. See the ISO 8601 standard for the complete definition.� Time zone � A time zone is defined as an area through out which time-of-day is the

same. � Time zone specification � The data that identifies a time zone: UTC offset, time zone

name and abbreviation.� Local time zone � The time zone relative to the route points.




Start Time To leave a location at a certain local time, you can specify a start time and date, and omit any time zone information. This is convenient for wireless users, who do not have to figure out the UTC offset of the time zone they are in. The route result will have start time and end time specified in local times relative to the route.

To leave a location at a certain time in a certain time zone, you can specify a start time, date, and UTC offset. The result will have start time and end time specified in local times, which are not necessarily in the same time zone as the input start time.

The following table illustrates the server behavior:

End TimeTo arrive at a location at a certain local time, you can specify an end time and date, and omit any time zone information.

To arrive at a location at a certain time in a certain time zone, you can specify an end time, date and UTC offset. The result will have start time and end time specified in local times, which are not necessarily in the same time zone as the input end time.

Specifying the RequestIf you specify a start or end time, time zone information can be included. If missing, local time is assumed.

In the Java API, there are two ways to specify start or end time. The code samples below demonstrate how to set start times. End times are set using the same logic.

Setting local start time.

RoutingPreferences prefs = new RoutingPreferences();LocalTime localTime = new LocalTime(year, month, date, hour, minute, second);prefs.setLocalStartTime(localTime);

In this case, prefs.getStartTime() will return null.

Setting start time with GMT and DST offsets.

RoutingPreferences prefs = new RoutingPreferences();Calendar calendar = new GregorianCalendar();calendar.setTimeZone(TimeZone.getTimeZone("America/New_York"));prefs.setStartTime(calendar);

In this case, prefs.getLocalStartTime() will return null.

Note: If you set the Calendar version after the local time version, it would override it.

Obtaining the ResponseIf a start or end time is requested, the result will have start and end times expressed as local times with time zone information included.

Route start point location Input start time Output start time

New York 9:00AM Mountain Standard Time 11:00AM Eastern Time

New York 9:00AM local time 9:00AM Eastern Time

New York 9:00AM Eastern Standard Time 9:00AM Eastern Time




In the Java API, time zone information can be accessed as follows:

Calendar startTime = route.getStartTime();TimeZone tz = startTime.getTimeZone();String name = tz.getDisplayName(); // localized time zone name

Time zone data may not available on the server. In this case, Route.getStartTime() and Route.getEndTime() will work as follows:

� If you have not specified a start or an end time, Route.getStartTime() and Route.getEndTime() return null.

� If you have specified a start or an end time, Route.getStartTime() and Route.getEndTime() throw TimeZoneNotAvailableException.

If you request to return actual preferences for local time back to the client, actualPreferences.getLocalStartTime() will behave as shown in the following code fragment.

RoutingPreferences prefs = new RoutingPreferences();prefs.setReturnActualPreferences(true);LocalTime localTime = new LocalTime(year, month, date, hour, minute, second);prefs.setLocalStartTime(localTime);

prefs.getStartTime(); // returns null

Route route = null;try { route = routingClient.findRoute(myRoutePoint1, myRoutePoint2); } catch (RoutingException e) {�}

Calendar routeStartTime = route.getStartTime();Calendar routeEndTime = route.getEndTime();TimeZone startTZ = routeStartTime.getTimeZone();TimeZone endTZ = routEndTime.getTimeZone();// return a localized name for the start time zonerouteStartTime.getDisplayName();routeEndTime.getDisplayName();// returns a localized name for the end time zoneRoutingPreference actualPrefs =route.getPreferences();// same as localTimeLocalTime localTimeUsed = actualPrefs.getLocalStartTime(); actualPrefs.getStartTime(); // returns null

If you request to return actual preferences for start time back to the client, actualPreferences.getStartTime() will behave as shown in the following code fragment.

RoutingPreferences prefs = new RoutingPreferences();prefs.setReturnActualPreferences(true);Calendar startTime = Calendar.getInstance();prefs.setStartTime(startTime);

prefs.getLocalStartTime(); // returns null

Route route = null;try { route = routingClient.findRoute(myRoutePoint1, myRoutePoint2); } catch (RoutingException e) {�}

Calendar routeStartTime = route.getStartTime();Calendar routeEndTime = route.getEndTime();TimeZone startTZ = routeStartTime.getTimeZone();TimeZone endTZ = routEndTime.getTimeZone();

// return a localized name for the start time zonerouteStartTime.getDisplayName();




// returns a localized name for the end time zonerouteEndTime.getDisplayName();

RoutingPreference actualPrefs =route.getPreferences();// return actual start time usedCalendar startTimeUsed = actualPrefs.getStartTime(); // return raw offset from GMT in msstartTimeUsed.get(Calendar.ZONE_OFFSET); TimeZone tzUsed = timeUsed.getTimeZone(); // returns local time zonetzUsed.getOffset(); //returns UTC offset used// return a string in the format "GMT[-]hh:mm"tzUsed.getDisplayName();

actualPrefs.getLocalStartTime(); // returns null

Time zones on streets and sectionsThe following table illustrates a situation when two consecutive streets of the route lie in different time zones:

Note: The end point of street 1 is the start point of street2. However, street1's end time is in a different time zone than street2's start time. The same logic holds for two consecutive sections of multi-point route.

Routing J Server Internationalization

For Routing J Server, internationalization means generating a response that is specific to a locale. This includes providing information in formats commonly used in that locale (such as date, time, and currency formats) as well as in the language of that locale such as driving directions in the German language.

There are two general uses for this feature. The primary use is to allow directions to be returned in different languages. This is important for any application used by people who speak different language, i.e. online applications or tourist centered applications.

The second use of this feature is to present the XML data in a format that is correctly internationalized for a given requestor. This does not impact the end user necessarily, but would make it easier for a programmer to interpret the XML response data. It also allows a programmer to generate an XML request that contains data in a familiar locale.

Setting Up a LocaleProgrammers working with the client need to communicate with the server administrator to determine what locales are supported by their server. The steps to setup a locale on a server are as follows:

1. Create a new DirectionStrings.properties file for a given locale. Only strings that need to be changed are required to be in the new properties file.

Street1 time zone

Street2 time zone

Street1 start time

Street1 end time

Street2 start time

Street2 end time

Central time Eastern time 9:00AM Central time

10:00AM Central time

11:00AM Eastern time

12:00 AM Eastern time




� If one does not exist, create a properties file with the following name: DirectionsStrings_xx.properties (where xx is the two letter language code). Place all language generic string changes in this file.

� Create a properties file, if changes from language are needed, with the following name: "DirectionsStrings_xx_YY.properties"(where xx is the two letter language code and YY is the two letter country code). Place all country specific string changes in this file.

Note: You must create both a DirectionsStrings and TerseDirectionsStrings file for each available locale.

� Add the above properties files to the rjsserver.jar file on the server.2. Make sure the NumberFormat resources for the required locale are installed. This is

handled by the installation of the Java Virtual Machine.

User Locale Methods The method, setUserLocale, is used to set a user specified locale. This locale will determine what locale the directions for a route are returned in. If not specified, the default for the current virtual machine will be used.

The method, getUserLocale, is used to retrieve the user locale. This locale determines in what locale the directions for a route are returned.

MultiPointPreferences

The MultiPointPreferences class holds the client's multipoint routing preferences for the routing engine. The MultiPointPreferences class extends the RoutingPreferences class. The OptimizeByIntermediatePoints method is specific to the MultiPointPreferences class.

OptimizeIntermediatePointsThe OptimizeIntermediatePoints preferences setting is used to control whether or not Routing J Server re-orders the intermediate points in an optimal manner during route computation. When this preference is set to false, Routing J Server preserves the specified order of the points. The default setting is true (i.e., optimally order the intermediate points).



7
Working with the IsoClient
Using the IsoClient allows you to obtain isochrones or isodistances. An isochrone is a polygon or set of points representing an area that can be traversed in a network from a starting point in a given amount of time. An isodistance is a polygon or set of points representing the area that is a certain distance from the starting point.

In this chapter:

! IsoDefinition Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69! Using IsoPreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69! Expected Isochrone/Isodistance Behavior. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72! Donut Style Banding Suggestions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73! Obtaining Isochrones/Isodistances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Developer Guide Chapter 7: Working with the IsoClient

IsoDefinition Overview

An IsoDefinition is the simplest iso request. An IsoDefinition contains:

� A starting point.� A unit, either linear or time.� One or more costs and their associated tags. Cost refers to the amount of time or

distance to use in calculating an iso. A tag is a string that identifies the cost and is used to match the corresponding result.

Using IsoPreferences

The IsoClient lets you specify preferences to use. If you do not create your own preferences, it uses the server preferences. IsoPreferences are the settings used to calculate the isochrone or isodistance.

Default ambient speedThis setting determines the off-road network speed. Ambient speed is the speed to travel a certain distance off identified roads to find the boundary when determining the isochrone. Roads not identified in the network can be driveways or access roads, among others. The ambient speed can be set for all road types or overridden for specific road types. For example, it may be set to 0 for major highways. This option is available for isochrones only.

Ambient speed overridesAmbient speed can be changed by road type. This option is available for isochrones only. The image on the left shows an isochrone without ambient speed overrides. The image on the right shows an isochrone that has used ambient speed overrides.

Default propagation factorThis is similar to default ambient speed, except that it applies to isodistances. The propagation factor is a percentage of the cost used to calculate the distance between the starting point and the isodistance. Propagation factor serves the same purpose for isodistances as ambient speed does for isochrones. For instance, if you are at a point with 5 minutes left on an isochrone, boundary points would be put at a distance based on the ambient speed and the




time left. So, if the ambient speed in this case was 15 miles per hour, boundary points would be put at a distance of 1.25 miles. Similarly, if you were at a point with 5 miles left to go on an isodistance, boundary points would be put at a distance based on the propagation factor and the time left. So, if the propagation factor was 0.16, boundary points would be put at a distance of 0.8 miles. This option is available for isodistance only.

Propagation factor overridesThis is similar to ambient speed overrides, except that it applies to isodistances. This option is available for isodistance only.

Major roadsThis setting determines what road network is used in the calculation. The network can include major roads only or all roads. A major road is a main road or highway. If you choose to use major roads, performance will improve, but accuracy may decrease. The images below illustrate the behavior of the major roads option. The image on the left shows majorRoadsOnly set to true while the image on the right shows majorRoadsOnly set to false. Notice that the sever uses side streets and other types of secondary roads when calculating the iso response if majorRoadsOnly set to true.

Maximum off-road distanceMaximum off-road distance is the maximum amount of distance to come off the road network when using either ambient speed or the propagation factor. The following image shows maximum off-road distance set to 0.2 miles.

Note: The server may not be able to generate a response for a maximum off-road distance set to a very small value.




HolesHoles are areas within the larger boundary that cannot be reached within the desired time or distance, based on the road network. These pockets of territory are often neighborhoods of local roads that are cumbersome to traverse. Holes can be returned as is, or removed entirely.

IslandsIslands are small areas outside the main boundary that can be reached within the desired time or distance. These areas are frequently located off exit ramps of major highways. Islands can be returned as is, or removed entirely.

Simplification factorThe reduction factor for polygon complexity. The simplification factor indicates what percentage of the original points should be returned or that the resulting polygon should be based on. The polygon or set of points may contain many, many points. The simplification factor is a decimal number between 0 and 1.0. Lower numbers mean lower storage and lower transmission times. The images below illustrate the behavior of the simplification factor option. The image on the left shows the simplification factor set to 0.01 while the image on the right shows the simplification factor set to 1.

Result typeResult types can be geometry, starting nodes, or all accessible nodes (illustrated below, respectively).




Banding styleBanding styles are the types of multiple isochrone or distance bands that can be displayed. The styles include donut or encompassing. Multiple isochrone or isodistance bands may be requested by specifying multiple cost factors, such as asking for the isochrone 5 minutes away and 15 minutes away from the same starting point. These end up as concentric bands, more or less. The requestor may choose to show both complete sets of data (encompassing style, which shows everything) or just the band between the two (donut style), everything between 5 and 15 minutes away.

Expected Isochrone/Isodistance Behavior

This section illustrates iso behavior under certain circumstances or when using different options.

Isos near the waterWhen generating an isochrone/isodistance near a body of water, the resultant polygon may display partially in the water. The following image displays the behavior of the Routing J Server when generating an isochrone/isodistance near a body of water.

Notice that the isochrone generated in this example stretches into the water.




Donut Style Banding Suggestions

A banded iso request is an iso request that has one starting point with multiple costs. There are two ways for the boundaries to be returned in the response. The standard way is encompassing, which means that each boundary is determined independent of all others. Another way is donut, which means that each boundary is determined by subtracting out the next smallest boundary, creating a donut.

The calculation that creates the donut can cause the server to stop responding. The specific situation that causes a problem is when two boundaries are nearly coincident. There are certain settings and requests that you should be careful of using in order to avoid this situation.

� Do not use the max off road distance setting if possible. If you must use this setting, set it as large as possible.

� Do not use low ambient speed or propagation factor settings. � Do not make requests with cost increments that are small relative to the cost. For

example, requesting 4, 5, and 6 minute costs (1 minute increments starting at 4 minutes) isn't likely to be a problem, but 120, 121, and 122 minute costs may be a problem. The larger the cost the larger the cost increments will need to be.

Obtaining Isochrones/Isodistances

Use the following code sample as a guide for using isoClient to obtain isochrones/isodistance:

//create a definitionIsoDefinition definition = new IsoDefinition();//set the unit for the cost.definition.setUnit(LinearUnit.mile);//add a cost for the isodefinition.addCost(10);

//set the result type to return a polygonIsoPreferences prefs = new IsoPreferences();

prefs.setResultType(IsoPreferences.RESULT_TYPE_GEOMETRY);

prefs.setReturnHoles(true);

//set the starting point for the isodefinition.setLongitude(-73.79466);definition.setLatitude(42.6635);

//create the requestIsoRequest req = new IsoRequest();req.addIsoDefinition(definition);req.setPreferences(prefs);

IsoClient client = null;

//create the isoClientclient = new IsoClient

("http://localhost:8090/routing30/servlet/routing");

//run the requestisoResponse = client.findIso(req);




//get results back from the response objectIsoResult[] isoResults = isoResponse.getIsoResults();

//create an IsoPolygonResult objectIsoPolygonResult isoPolyResult = (IsoPolygonResult)isoResults[0];

//get a RoutingMultiPolygonRoutingMultiPolygon rtgMultiPoly = isoPolyResult.getMultiPolygon();

//return all the polygons as an arrayRoutingPolygon[] allPolygons = rtgMultiPoly.getPolygons();

//get the inner and outer boundaries of the polygonRoutingBoundary outerBoundary = allPolygons[0].getOuterBoundary();RoutingBoundary[] innerBoundaries =

allPolygons[0].getInnerBoundaries();

//get all of the points that comprise the outer boundaryRoutePoint[] outerBoundaryPoints = outerBoundary.getPoints();

//get all of the points that comprise the inner boundariesRoutePoint[] innerBoundaryPoints = {};//set up the array as a listList innerBoundaryView =

new ArrayList(Arrays.asList(innerBoundaryPoints));



8
Using the RoutingDataClient and Data Updates
This chapter describes the RoutingDataClient and provides a usage example and information about working with persistent updates.

In this chapter:

! Accessing Routing Data Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76! Modifying Data with Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Developer Guide Chapter 8: Using the RoutingDataClient and Data Updates

Accessing Routing Data Information

Routing Data Access provides you with the ability to obtain segment data for a point or segment id. When you specify a point, the closest RouteSegments are returned. When you specify a segment id, the RouteSegment for that segment id is returned.

Obtaining Segment Data1. Create a RoutingData client.2. Create a RoutingDataRequest object.3. On the RoutingDataRequest object, set the requested object.4. Set RoutingDataPreferences via RoutingDataRequest.setPreferences().5. Invoke RoutingDataClient.getData to retrieve routing data information. This returns a

routing data result object.6. Use RoutingDataResult.getSegments to retrieve data that was returned.

Usage ExampleInitialization:

// set up new routing data clientRoutingDataClient rdc =new RoutingDataClient("http://localhost:8090/routing30/servlet/routing", true);

Note: The true parameter means debug.

Requesting data and getting the result:

//create a request object.RoutingDataRequest request = new RoutingDataRequest(); //set a point on the request.RoutePoint point = new RoutePoint(longitude, latitude, 0);request.setRequestedObject(point);

// set up the preferencesRoutingDataPreferences prefs = new RoutingDataPreferences();prefs.setReturnSegmentData(true);

//tell the request to use specific preferences.request.setPreferences(prefs); //run the request.RoutingDataResult result = rdc.getData(request); // do something with the resultsRouteSegment[] rs = result.getSegments();

If you have MapXtreme Java and the server set to return segment data, you can display the RouteSegment information and draw the segment in a MapXtreme Java annotation layer.




Modifying Data with Updates

Data modification updates means that the routing network can be updated without reprocessing the base data. You have the ability to make persistent and transient updates.

Persistent UpdatesPersistent updates are updates made to the server that apply to all requests. These updates remain intact if the server is restarted.

Transient UpdatesTransient updates are updates made on a request that only apply to the particular request. This may be an exclude or a speed change for a road type, segment, or point.

Update FunctionalityBy making these types of modifications, you have the ability to:

� exclude a point� exclude a segment� set the speed of a point, segment, or road type� change (increase or decrease) the speed of a point, segment, or road type by some

value � change (increase or decrease) the speed of a point, segment, or road type by some

percentage� set the road type for a segment

Keep in mind that because persistent updates are changes made on a system-wide basis they should be used with caution.

You have the ability to set a speed for a point, a segment id, or a road class, as well as the ability to update the road class for a segment (specified by the segment id). Specifying a point will find the closest segments to that point and set the speed for those segments. This will be slower than setting a segment via the segment id directly. You can reset any of these updates to their default values or reset them all at once. Changes to the speed of a road class are written to a rjs.rts file while changes to individual segment speeds are written to a rjs.as file.




Update DeltaDelta updates to persistent updates allows you to increase or decrease the speed of a RoutePoint, RoadType, or RouteSegment by some amount or by some percentage (instead of specifying the new speed). For instance, increasing the speed by 40 percent or decreasing it by 30 miles per hour is a delta update. Setting the speed to 20 miles per hour is not a delta update. Delta updates can very useful when you do not know the existing speed for a RoutePoint, RoadType, or RouteSegment but need to increase or decrease it by some amount or percentage. To specify a 40 percent change, you would simply use 40 in the Percentage element.

Keep in mind that the server throws an error if an invalid percentage (non-positive integer) value is specified. The server also throws an error if a delta update will yield an invalid speed (less than 0).

For more information, see the section, MI_XML_Protocol_RoutingCommonElements_3_0.dtd on page 86.



9
MapInfo Enterprise XML Protocol
Routing J Server continues to move toward embracing diverse enterprise applications with its introduction of the MapInfo Enterprise XML Protocol. This protocol, based on the Extensible Markup Language (XML), defines how requests and responses for map information and data are handled by MapInfo enterprise products, such as Routing J Server, MapXtreme Java, and MapMarker J Server.

In this chapter:

! Working with the XML API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80! Document Type Definitions (DTD) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81! HTTP Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82! XML Elements Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84! MI_XML_Protocol_RoutingRequestAndResponse Envelope_3.0.dtd . . . . . . . . . . . . 86! MI_XML_Protocol_RoutingCommonElements_3_0.dtd . . . . . . . . . . . . . . . . . . . . . . . 86! MI_XML_Protocol_RoutingRouteRequestAndResponse_3_0.dtd . . . . . . . . . . . . . . . 90! MI_XML_Protocol_RoutingMultiRequestAndResponse_3_0.dtd . . . . . . . . . . . . . . . . 90! MI_XML_Protocol_RoutingIsoRequestAndResponse_3_0.dtd . . . . . . . . . . . . . . . . . 92! MI_XML_Protocol_RoutingPersistentUpdatesRequestAnd Response_3_0.dtd . . . . 93! MI_XML_Protocol_RoutingMatrixRequestAndResponse_3_0.dtd. . . . . . . . . . . . . . . 94! MI_XML_Protocol_RoutingDataRequestAndResponse_2_5.dtd . . . . . . . . . . . . . . . . 95! XML Backwards Compatibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95! Supported Road Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Developer Guide Chapter 9: MapInfo Enterprise XML Protocol

Working with the XML API

In addition to the Java API, Routing J Server also supports an XML API. This API allows you to send XML requests to the Routing J Server and receive XML responses. This chapter discusses the XML API available with Routing J Server.

When to use the XML APIThe XML API is intended for use with non-Java applications that support XML (e.g., VB, C++, etc). If you are writing your application in Java, then you should use the Java API. If you are not writing in Java, then you should use the XML API.

Required Skill SetsTo work with the XML API, you should have proficiency in the language that you choose. You should also have an understanding of XML, including writing XML requests and handling XML responses, DTDs and validation.

Requests/ResponsesRequests and responses for all of the major Routing J Server functionality are supported: Route, MultiPoint, Matrix, Isochrone, RoutingData, and Persistent Updates. PersistentUpdates is supported only through the XML API. All other request types are supported through both the Java and XML APIs.

The DTDs for the RJS XML API are in the rjsdtds.jar file. Be sure that this file is in your classpath. This file is found under {Install_dir}\RoutingJServer-3.0\lib\server. For more information on DTDs, see Document Type Definitions (DTD) on page 81.

Note: MI_XML_Protocol_RoutingRequestAndResponseEnvelope_3_0.dtd is dependent on all of these DTDs. It defines the common wrapper around each of the specific request and response types. The associated DTDs for each request type are also dependent on common (MI_XML_Protocol_RoutingCommonElements_3_0.dtd) and OGC DTDs.

Tips for Using the XML APIThe following sections provide helpful information for using the XML API.

Request/Response Type Associated DTD*

Route MI_XML_Protocol_RoutingRouteRequestAndResponse_3_0.dtd

MultiPoint MI_XML_Protocol_RoutingMultiRequestAndResponse_3_0.dtd

Matrix MI_XML_Protocol_RoutingMatrixRequestAndResponse_3_0.dtd

Isochrone MI_XML_Protocol_RoutingIsoRequestAndResponse_3_0.dtd

RoutingData MI_XML_Protocol_RoutingDataRequestAndResponse_2_5.dtd (unchanged from RJS 2.5)

PersistentUpdate MI_XML_Protocol_RoutingPersistentUpdatesRequestAndResponse_3_0.dtd




Become familiar with the DTDs The DTDs for the XML API are in the file rjsdtds.jar. The elements in these dtds are explained in this chapter. The information in this chapter, in conjunction with the DTD files, show the Routing J Server XML API.

Look at the example requests in the TestXML sampleThe TestXML sample (under samples\diagnostics) is an example that shows usage of the XML API. There are .xml files that contain various requests for each major type of request (route, multipoint, iso, routingData, persistent update).

Turn on validation during developmentRouting J Server will validate the XML requests when the validation initialization parameter of RoutingServlet is set to true. During development of your application, having validation turned on will save some time and help you find errors in your requests. Once the application is moved into production, validation should be turned off to avoid a performance penalty.

Use a template document for similar requestsIf your application always sends the same request with only changes in the start and end points, then it may be easier to have a file containing the request. This request would have tags where the start and end longitude and latitude values go. Your application can then replace those tags with the actual values before making the request.

Note: This tip is intended for requests where very little changes. If your user can set preferences, then you would be better off building the request in your application.

Document Type Definitions (DTD)

Document type definitions (DTDs) specify a set of rules for the structure of an XML document. Routing J Server includes a number of DTDs that support the MI Enterprise XML protocol. The DTDs are located inside a jar file named rjsdtds.jar. Please refer to your servlet container documentation for information on access and security.

When developing an XML client application against the Routing J Server, we recommend turning validation on at the server. Once the development stage is over, turn validation off to avoid a performance hit. You also need know the DTD URL and have access permission.

The DTD defines the syntax of each valid element.

Note: Use the XML DOCTYPE header for XML client development only. Once the development stage is finished, remove it from your XML requests. Otherwise, it may have a performance impact since some parsers (like xerces) will still try to look for the DTD even if validation is off.




The following table describes the DTDs that are supported in this release. The Routing J Server also supports 2.0 and 2.5 DTDs. For more information, see the section, XML Backwards Compatibility on page 95.

* These DTDs are dependent on the MI_XML_Protocol_ OGC DTDs.

HTTP Headers

The current version of MapInfo XML Enterprise protocol is implemented using HTTP 1.1 POST.

DTD Description

MI_XML_Protocol_RoutingRequestAndResponseEnvelope_3_0.dtd *

Defines request and response envelope ele-ments, which are the common wrappers around each specific request and response type XML document.

MI_XML_Protocol_RoutingRouteRequestAnd Response_3_0.dtd *

Defines route requests and responses between client and server.

MI_XML_Protocol_RoutingMultiRequestAnd Response_3_0.dtd *

Defines multiPoint requests and responses between client and server.

MI_XML_Protocol_RoutingIsoRequest AndResponse_3_0.dtd *

Defines iso requests and responses between client and server.

MI_XML_Protocol_RoutingPersistent UpdatesRequestAndResponse_3_0.dtd *

Defines persistent updates requests and responses between client and server.

MI_XML_Protocol_RoutingCommon Elements_3_0.dtd *

Defines routing elements common for different types of routing requests such as start and end points, routing algorithm and response con-straints, street, segment, segment geometry, and segment data elements.

MI_XML_Protocol_RoutingDataRequestAnd Response_2_5.dtd *

Defines routing data requests and responses between client and server.

MI_XML_Protocol_RoutingMatrixRequestAnd Response_3_0.dtd*

Defines matrix requests and responses between client and server.

MI_XML_Protocol_CommonElements_1_0.dtd *

Defines measurements for time, distance, angle, and velocity. The measurements are product independent and support routing, geoc-oding, and mapping.

MI_XML_Protocol_OGC_GML_1_0.dtd Defines simple GML (Geographic Markup Lan-guage) geometry elements for points, poly-gons, polylines, and collections, as defined by the Open GIS Consortium (OGC).

MI_XML_Protocol_OGC_Identification_1_0.dtd

Defines OGC identification elements.

MI_XML_Protocol_OGC_Units_1_1.dtd Defines OGC units of measurement for time, distance, angle, and pixel spacing.




The following HTTP headers identify the request:

The following HTTP headers identify the response:

HTTP header names specific to MapInfo are prepended with "MI_".

An HTTP error is sent back to the client in the following cases:

� A required HTTP header is missing or specified incorrectly.� RoutingServlet does not support a given type of request.

If the request HTTP headers are correct, but a problem occurred while processing the XML request, the HTTP response code is set to success (200) and the RoutingFaultResponse xml document is sent to the client. RoutingFaultResponse is defined in MI_XML_Protocol_RoutingCommonElements.dtd.

HTTP header Values

Required or

optional Description

Content-Type text/xml required Specifies input character encoding to be text/xml as defined in HTTP 1.1 spec.

MI_XMLProtocolRequest RouteRequest, IsoRe-quest, MultiPointRe-quest, PersistentUpdates Request, MatrixRou-teRequest

required Identifies the request type.

MI_XMLProtocolVersion 3.0 required XML protocol version.

MI_XMLProtocol TransactionId any string optional Optional header for conve-nience of client. If provided, it is sent back to client in HTTP response header.

HTTP header ValuesRequired

or optional Description

Content-Type text/xml required Specifies character encoding to be text/xml as defined in HTTP 1.1 spec.

MI_XMLProtocolResponse RouteResponse, IsoRe-sponse, MultiPointRe-sponse, PersistentUpdates Response, MatrixRoute

required Identifies the response type.

MI_XMLProtocolVersion 3.0 required XML protocol version.

MI_XMLProtocol TransactionId any string optional Optional header for conve-nience of client. If pro-vided in request, it is sent back to client in HTTP response header.




XML Elements Description

The following sections provide information about the XML elements for use with the Routing J Server.

XML Naming and Usage MapInfo Enterprise XML protocol adopts the following practices:

� Use camel case for element and attribute names.� Use elements for data.� Use attributes for metadata about an element.� Use lower case for attribute values.� An identifier of type "XXXList" means the order of the contents matters. An identifier of

type "XXXSet" means the order of the contents does not matter.

OGC Elements OverviewSome of the DTDs in the MapInfo Enterprise Protocol contain elements that have been defined by the Open GIS Consortium (OGC). References to the specific OGC recommendation papers are provided below.

MI_XML_Protocol_OGC_GML_1_0.dtd contains simple geometry objects defined according to recommendations in the following paper: Geography Markup Language (GML) 2 OGC Recommendation Paper, 20 February 2001 OGC Document Number: 01-029 http://www.opengis.net/gml/01-029/GML2.html. The gid and srsName optional attributes defined in this DTD are not currently used.

MI_XML_Protocol_OGC_Identification_1_0.dtd contains Identification Data defined according to recommendations in the following paper: "Recommended Definition Data for Coordinate Reference Systems and Coordinate Transformations," Section 6.8, OGC Recommendation Paper, 15 January 2001, OGC Document Number 01-014.

Only the name sub-element of NameSet is currently used.

MI_XML_Protocol_OGC_Units_1_1.dtd contains units of measure defined according to recommendations in the following paper: "Recommended Definition Data for Coordinate Reference Systems and Coordinate Transformations," Section 6.9, OGC Recommendation Paper, 10 November 2001, OGC Document Number 01-014r5.

An identifier element is not currently used. A unit is usually specified by a name (from NameSet element) and a conversion coefficient (e.g., unitsPerMeter). A LinearUnit element is used to measure distances.

Common ElementsMI_XML_Protocol_CommonElements_1_0.dtd defines measurements for time, distance, angle, and velocity. These measurements are product independent and support routing, geocoding, and mapping.

Routing ElementsThe following tables provide a description of the elements and attributes defined in routing-specific DTDs.



http://www.opengis.net/gml/01-029/GML2.html

http://www.opengis.net/gml/01-029/GML2.html


Routing RequestsRouting requests usually consist of three parts:

� Request data. For example, route request data are starting and ending points; iso request data is an iso definition.

� Algorithm constraints (preferences) that determine an algorithm for getting a solution. For example, route algorithm constraints determine whether to get the shortest or a quickest route, what points to exclude from the route, etc.

� Response constraints (preferences) that determine how to format the given result. For example, response constraints determine what units of measure to use for times and distances.

Algorithm and response constraints are optional elements. The most economical XML request contains only request data. All unspecified values in the algorithm and response constraints will assume the server default settings. Constraints may also be overridden by the server if the server settings are more restrictive. For example, if you request driving directions and the server has them disabled, driving directions would not be returned.

Routing ResponsesResponse elements for all types of requests have the following common features:

� If a request fails due to invalid XML or an algorithmic reason, RoutingFaultResponse is sent back to the user.

� In the case of success, response elements have the RequestConstraintsOverridden true/false attribute. It has a value of true if: Any request constraint was overridden by the server.

A constraint was defaulted to an unexpected server setting. For example, if an XML request does not specify whether to return the shortest time or the shortest distance, the server default is used. However, this server setting could be changed at startup. In this case, the value of the preference on the server will be returned and RequestConstraintsOverridden will be set to true in the response XML document.

� In the case of success, response elements have the xxxServerConstraints optional sub-element where xxx refers to the type of request (route, iso, etc.). It contains algorithm and response constraints actually used for the request. These constraints may not have the same values as the request constraints if some of them were defaulted or overridden. ServerConstraints are returned only if the includeActualConstraints attribute of the SuccessResponse element (in ResponseConstraints) is set to true.

� The most economical route and multiPoint successful responses contain only a summary element.




MI_XML_Protocol_RoutingRequestAndResponseEnvelope_3.0.dtd

The table below provides a description of the elements defined in MI_XML_Protocol_RoutingRequestAndResponseEnvelope_3.0.dtd.

MI_XML_Protocol_RoutingCommonElements_3_0.dtd

The tables below provide a description of the elements and attributes defined in MI_XML_Protocol_RoutingCommonElements_3_0.dtd.

Constraint Elements.

Element Description

RoutingRequestEnvelope The type of request: RouteRequest, MultiPointRequest, IsoRe-quest, PersistentUpdatesRequest, RoutingDataRequest, or| MatrixRouteRequest.

Locale The locale attribute on the request envelope. This attribute indi-cates the locale that the request is formatted in. All numbers will be read in that locale.

Element Default Description

ShortestTime Requests the quickest route.

ShortestDistance Requests the shortest route.

UsePersistentUpdates true If this element value is true, persistent updates are used when calculating a route.

ReturnStreetDirections true If true, returns driving directions per street. These driving directions are fully formatted on the server.

ReturnSegmentGeometry all Segment geometry flag that indicates what shape points are being returned: all, end or none.

ReturnSegmentData false If true, returns segment data.

SuccessResponse, Include-ActualConstraints attribute

false If true, constraints that are used are included in the successful response.

PrimaryNameOnly false If true, only the primary name of the street will be used in the street directions. If false, the pri-mary name and all alternate names will be used.




The following constraint elements have no default settings on the server.

DirectionBreakTurnAngle 45 The turn angle value that determines when a street is broken into a new directions string. Sometimes, when following a route, a street will make a significant turn while keeping the same name. By using this value, the user can specify the turn angle at which a new direction should be started. Valid values are integer val-ues between 0 to 180.

MajorRoadsOnly false If true, minor roads will not be used.

Element Description

MustIncludeList Defines what points or route segments (specified by segment ids), to include in the route.

SpeedIncrease Increase the speed by some value or by a percentage.

SpeedDecrease Decrease the speed by some value or by a percentage.

Percentage A positive integer value representing some percentage.

TravelPreferenceSet A set of the preferences for RoadType

TravelPreference Specifies a RoadTypePreference for a given RoadType

RoadTypePreference The preference for a RoadType: high, medium, low, or avoid.

UserLocale Indicates how XML user areas are formatted/translated in the response. User areas are currently limited to directions, but may be expanded in the future to include other areas that are expected to be directly displayed to the user.

DataLocale Indicates how XML data areas are formatted/translated in the response. For example, a longitude of "-72.346" in a "en_US" response will be formatted as "-72,346" with a locale of "de_DE".

UpdateList Ordered list of updates.

Update Specifies whether the update is a PointUpdate, SegmentUp-date, or| RoadTypeUpdate.

PointUpdate Contains the point to be updated.

SegmentUpdate Contains the segment to be updated.

RoadTypeUpdate Contains the road type to be updated.

SpeedUpdate Specifies the Velocity, SpeedIncrease, SpeedDecrease.

Exclude Specifies an exclude.

Reset Specifies the type of reset: PointReset, SegmentReset, or RoadTypeReset.

PointReset Contains the point to be reset.

SegmentReset Contains the segment to be reset.

Element Default Description




The following constraint elements override the server defaults specified in the file DirectionStrings.properties.

Other ElementsThe following table lists additional elements in MI_XML_Protocol_RoutingCommonElements_3_0.dtd.

RoadTypeReset Contains the road type to be reset.

StartDateTime Specifies the start date.

EndDateTime Specifies the end date.

dateTime A string representing the date, time, and time zone.

ShowDistance If true, the distance displays in the directions.

ShowTime If true, the time displays in the directions.

Element Description

DirectionConstraints Direction constraints for combining street driving directions on the server side.

DirectionsStyle Type of description for directions. This can be normal or terse.

DirectionsGeneratorName Specifies the name of the directions generator.

Element Description

RoutePointList Contains route start and end points.

StartPoint Route start point.

EndPoint Route end point.

IntermediatePoint An intermediate point that encapsulates a point and a duration.

TimeConstraints Determines if start time or end time is used.

StartTime Specifies a start time.

EndTime Specifies an end time.

TimeZone Specifies the time zone.

DstInfo If present, time zone makes daylight savings time switchover.

DstOffset The amount of time to offset to account for daylight savings time.

DstStartTime The start time for daylight savings.

DstEndTime The end time for daylight savings.

TimeZoneNotAvailable If present, time zone data is not available on the server.

Element Description




StreetList Ordered list of streets. StreetList element also includes the units of measure for all the elements contained inside of it. In particular the LinearUnit sub-element of StreetList can be used as a unit of mea-sure for LinearValue contained in SegmentData several levels deeper.

Street Street contains a name, and possibly driving directions and a list of segments, if requested.

StreetName Street name is a string.

StreetDirections Prose directions for one street.

DirectionsSummary Direction summary string.

SegmentList Ordered list of segments.

SegmentSet Non-ordered list of segments with units of measure for segment data elements.

Segment Segment is present in response only if routing data and/or segment geometry are requested. It contains a unique segment id and possi-bly a LineString (for storing segment geometry) and segment data.

RoutingSegmentID A unique string segment id used internally by the server for segment identification. Note: segment ids for the same segments will differ from version to version.

SegmentData Returns segment data information if set to true.

PrimaryName Segment primary name.

AlternateNameList An ordered group of AlternateName elements.

AlternateName Segment alternate name.

TurnAngleString Angle that determines if a turn occurs.

CompassDirection Segment compass direction:NSEWNENWSESW

CompassValue Integer value that is used to verify CompassDirection.

RoadType Segment road type. A listing of supported road types is at the end of this chapter.

TollRoad If true, it is a toll road. If false or absent, it is not a toll road.

Oneway If false or absent, it is not a one way road. If true, it is a one way road. Possible type attribute values are: bidirectional (default), from_to, to_from, non_traversable.

Roundabout If true, it is a roundabout. If false or absent, it is not a roundabout. (Roundabouts are sometimes referred to as circles or rotaries.)

Element Description




MI_XML_Protocol_RoutingRouteRequestAndResponse_3_0.dtd

The table below provides a description of the elements and attributes defined in MI_XML_Protocol_RoutingRouteRequestAndResponse_3_0.dtd. The following constraint elements have no default settings on the server.

MI_XML_Protocol_RoutingMultiRequestAndResponse_3_0.dtd

The table below provides a description of the elements and attributes defined in MI_XML_Protocol_RoutingMultiRequestAndResponse_3_0.dtd.

RouteSummary Summary of the time and distance of a route.

RoutingFaultResponse Indicates request failure. It contains information about the failure.

Element Description

RouteRequest Request for a route.

RouteConstraints Route algorithm constraints. All unspecified values will assume the server default settings.

RouteResponseCon-straints

Route response constraints. All unspecified values will assume the server default settings.

RouteResponse A successful route response must contain at least a route summary. It may possibly contain a Street List and RouteServerConstraints. RequestConstraintsOverridden attribute has a true value if� any request constraint was overridden by the server� a constraint was defaulted to a unexpected server setting

RouteServerConstraints Contains the RouteConstraints actually used and RouteRespon-seConstraints.

Focus Determines if a route concentrates on the starting point or destina-tion or if there is no focus at all.

ElementExpected Default Description

TimeOut 0 Specifies the approximate maximum amount of time (in milliseconds) to calculate the short-est path.

Element Description





StopThreshold 0.01 Sets the stop threshold. A stop threshold of 0.01 is equal to a 1% change from the time/distance calculated in an iteration to find the best route. Valid values are any positive num-bers. For best performance, a positive number less than one is recommended. When the stop threshold is reached, the current best route is returned. Setting the stop threshold is a bal-ancing factor between accuracy and speed. The lower the threshold value on average, the more accurate the result and the longer the calculation time. The stop threshold has a min-imal effect on routes with few intermediate points (under 10).

OptimizeIntermediatePoints true If set to false, OptimizeIntermediatePoints allows a MultiPoint route to be run without the re-ordering of points

Element Description

MultiPointRequest Request for multiPoint routing.

MultiPointList MultiPoint route start, end, and intermediate points.

IntermediatePointList Intermediate points of a multiPoint request.

MultiPointConstraints MultiPoint preferences.

MultiPointResponse A successful multiPoint response must contain at least a multi-Point summary. RequestConstraintsOverridden attribute has a true value if:� any request constraint was overridden by the server� a constraint was defaulted to a unexpected server setting

MultiPointSummary Contains total route time, total route distance, directions sum-mary (defined in MI_XML_RoutingCommonElements_2_5.dtd) and intermediate points.

MultiPointRouteSection Route corresponding to a path between two of the intermediate points.

MultiPointServerConstraints The actual constraints used by the server.

MultiPointResponseCon-straints

MultiPoint response constraints. MultiPoint response con-straints define how to format a multiPoint result: - units of measure to use for time, distance and velocity- whether to return street driving directions - whether to return all, end, or no route shape points- whether to return segment data necessary to combine driving directions on the client side- whether to return actually used constraints on success- the UserLocale for the request - the DataLocale for the request.All unspecified values will assume the server default settings.





MI_XML_Protocol_RoutingIsoRequestAndResponse_3_0.dtd

The table below provides a description of the elements and attributes defined in MI_XML_Protocol_RoutingIsoRequestAndResponse_3_0.dtd.


DefaultAmbientSpeed 15 MPH The default ambient speed used for the cal-culation of the iso. Default ambient speed is the ambient speed that is used for all road types that do not have specific ambient speed overrides. Ambient speed is the speed at which travel is allowed off network roads. This property only applies to isochrones, i.e., an iso with a time unit.

DefaultPropagationFactor 0.16 The default propagation factor used for the calculation of the iso. Default propagation factor is the propagation factor that is used for all road types that do not have specific propagation factor overrides. Propagation factor is the percentage of the remaining cost for which off network travel is allowed. This property only applies to isodistances, i.e., an iso with a distance unit.

MaxOffRoadDistance no limit The maximum distance ambient travel will be allowed to go off roads.

ResultType geometry The result type requested. geometry - returns a MultiPolygon represent-ing the area that can be reached for the iso.startNodes - returns a MultiPoint with one point representing the starting point of the iso. accessibleNodes - returns a MultiPoint with one point for each node accessible for the iso. Nodes are either intersections or sig-nificant geometry features.

SimplificationFactor 0.05 The simplification percentage used in the cal-culation of the iso. Applies only if geometry is the result type.

BandingStyle encompassing The banding style used for the calculation of an iso. This applies only if multiple costs were specified in the iso definition, and geometry is the requested result type. encompassing - each cost will generate a result that starts at the starting point. Donut - each cost will generate a result that starts where the previous cost ended.

IncludeHoles true If true, holes will be returned in the result. Applies only if geometry is the result type.

IncludeIslands true If true, islands are allowed in the result. Applies only if geometry is the result type.





MI_XML_Protocol_RoutingPersistentUpdatesRequestAndResponse_3_0.dtd

The table below provides a description of the elements and attributes defined in MI_XML_Protocol_RoutingPersistentUpdatesRequestAndResponse_3_0.dtd. The following constraint elements have no default settings on the server.

Element Description

IsoRequest Request for an iso.

IsoDefinition Definition of iso to calculate.

Cost with Tag attribute Cost with an associated tag string. For example, to define a 15 minute isochrone you would create an IsoDefinition with a unit of minutes and a cost of 15. The tag is a string value that is returned on the result allowing you to associate the request with the result.

IsoConstraints Iso algorithm constraints.

OverrideAmbientSpeedSet An unordered group of OverrideAmbientSpeed elements.

OverrideAmbientSpeed Overrides the default ambient speed for a specific road type. This property only applies to isochrones, i.e., an iso with a time unit.

OverridePropagationFactor-Set

An unordered group of OverridePropagationFactor elements.

OverridePropagationFactor Overrides the propagation factor to be used in the calculation of the iso for a given road type. Propagation factor applies only to isodistances, i.e. an iso with a distance unit.

PropagationFactor The percentage of the remaining cost for which off network travel is allowed.

BoundaryStyle Holds values for includeHoles and includeIslands.

IsoResponseConstraints Iso response constraints.

IsoResponse RequestConstraintsOverridden attribute has a true value if:� any request constraint was overridden by the server� a constraint was defaulted to a unexpected server setting

IsoResultSet An unordered group of IsoResult elements.

IsoResult with Tag attribute Result of the iso request. The tag matches the tag attribute of the cost element in the request.

IsoServerConstraints The actual constraints used by the server.

Element Description

PersistentUpdatesRequest Request for a Persistent Update and/or Persistent Reset.




MI_XML_Protocol_RoutingMatrixRequestAndResponse_3_0.dtd

The table below provides a description of the elements and attributes defined in MI_XML_Protocol_RoutingMatrixRequestAndResponse_3_0.dtd.

RestoreDefaults Restore the updates to the default state. This means removing the results of any Persistent Updates requests to the server.

PersistentUpdatesRe-sponse

Specifies a successful response to an update/reset.

SuccessMessage If the update/reset is successful, a message is displayed.

Element Description

MatrixRouteRequest Request for a matrix route.

MatrixRoutePoints Points for the matrix. The list can be StartPointList or End-PointList.

StartPointList An ordered list of start points.

EndPointList An ordered list of end points.

MatrixRouteConstraints Algorithm constraints for matrix routes. All unspecified values will assume the server default settings.

MatrixRouteResponseCon-straints

Response constraints for matrix routes. All unspecified values will assume the server default settings.

MatrixRouteResponse Response to a successful matrix route request. If no paths are found, must return a fault response with a message.

MatrixRouteList The returned route costs between points on the start point list and points from the end point list. The MatrixRouteList con-tains the RouteCostList with time and distance units.

RouteCost The amount of time or distance used to calculate matrix routes.

RouteCostFault Fault message or fault code.

MatrixRouteCostList An ordered list of route costs. Each RouteCostList contains the route costs for one source to all destinations.

MatrixRouteServerConstraints The actual constraints used by the server.

Element Description




MI_XML_Protocol_RoutingDataRequestAndResponse_2_5.dtd

The table below provides a description of the elements and attributes defined in MI_XML_Protocol_RoutingDataRequestAndResponse_2_5.dtd. The following constraint elements have no default settings on the server.

XML Backwards Compatibility

The 3.0 version of the Routing J Server can accept Routing J Server 2.5 and 2.0 XML requests. If you have validation turned on, the server will automatically accept the correct version request. If you want to validate a 2.5 request you must submit the request with a MI_XMLProtocolVersion of 2.5 (see page 82 for more information). The server must be set up to accept old requests. This is done in the web.xml. In the RoutingServlet, set the <param-name>acceptOldRequests</param-name> to true. Be aware that with a request from an old version (2.5) to the server (3.0) there may be a performance penalty.

In MI_XML_Protocol_MultiRequestAndResponse_2_5.dtd the type "MultiPointRouteSection?" in MultiPointResponse should read "MultiPointRouteSection*" or all 2.5 multipoint responses will fail validation.

Element Description

RoutingDataRequest Routing data request. The order of the streets/segments returned in a RoutingDataRequest is not guaranteed. For instance, when making a request for data at a given lat/long over and over again, the same data will always come back, but it may not be in the same order.

RoutingData Contains one of the following elements:Point - to request the closest segments to a given point.Routing Segment ID - to request the segment for a given seg-ment id.

RoutingDataResponseCon-straints

Response constraints.

RoutingDataResponse Contains a SegmentSet and possibly RoutingDataServerCon-straints.RequestConstraintsOverridden attribute has a true value if:� any request constraint was overridden by the server� a constraint was defaulted to a unexpected server setting

RoutingDataServerConstraints The actual constraints used by the server.




Supported Road Types

The following tables lists supported road types for Routing J Server 3.0.

Name XML NameSupported in U.S. Version

LIMITED_ACCESS_DENSE_URBAN limited access dense urban

No

PRIMARY_HIGHWAY_DENSE_URBAN primary highway dense urban

Yes

SECONDARY_HIGHWAY_DENSE_URBAN secondary highway dense urban

Yes

MAJOR_ROAD_DENSE_URBAN major road dense urban Yes

NORMAL_ROAD_DENSE_URBAN normal road dense urban Yes

MAJOR_LOCAL_ROAD_DENSE_URBAN major local road dense urban

No

LOCAL_ROAD_DENSE_URBAN local road dense urban No

MINOR_LOCAL_ROAD_DENSE_URBAN minor local road dense urban

No

RAMP_DENSE_URBAN ramp dense urban Yes

LIMITED_ACCESS_URBAN limited access urban No

PRIMARY_HIGHWAY_URBAN primary highway urban Yes

SECONDARY_HIGHWAY_URBAN secondary highway urban Yes

MAJOR_ROAD_URBAN major road urban Yes

NORMAL_ROAD_URBAN normal road urban Yes

MAJOR_LOCAL_ROAD_URBAN major local road urban No

LOCAL_ROAD_URBAN local road urban No

MINOR_LOCAL_ROAD_URBAN minor local road urban No

RAMP URBAN ramp urban Yes

LIMITED_ACCESS_SUBURBAN limited access suburban No

PRIMARY_HIGHWAY_SUBURBAN primary highway suburban Yes

SECONDARY_HIGHWAY_SUBURBAN secondary highway subur-ban

Yes

MAJOR_ROAD_SUBURBAN major road suburban Yes

NORMAL_ROAD_SUBURBAN normal road suburban Yes

MAJOR_LOCAL_ROAD_SUBURBAN major local road suburban No

LOCAL_ROAD_SUBURBAN local road suburban No




MINOR_LOCAL_ROAD_SUBURBAN minor local road suburban No

RAMP SUBURBAN ramp suburban Yes

LIMITED_ACCESS_RURAL limited access rural No

PRIMARY_HIGHWAY_RURAL primary highway rural Yes

SECONDARY_HIGHWAY_RURAL secondary highway rural Yes

MAJOR_ROAD_RURAL major road rural Yes

NORMAL_ROAD_RURAL normal road rural Yes

MAJOR_LOCAL_ROAD_RURAL major local road rural No

LOCAL_ROAD_RURAL local road rural No

MINOR_LOCAL_ROAD_RURAL minor local road rural No

RAMP RURAL ramp rural Yes

RAMP_LIMITED_ACCESS ramp limited access No

RAMP_MAJOR_ROAD ramp major road No

RAMP_PRIMARY_HIGHWAY ramp primary highway No

RAMP_SECONDARY_HIGHWAY ramp secondary highway No

FOOTPATH footpath Yes

FERRY ferry Yes

BACK_ROAD back road No

ACCESS_WAY access way Yes

CONNECTOR connector Yes

Name XML NameSupported in U.S. Version



10
Working with Routing Samples
MapInfo Routing J Server provides a variety of samples to demonstrate the types of applications that you can build. These samples located in the \RoutingJServer-3.0\examples-usa\ directory of the path where you installed the MapInfo Routing J Server.

In this chapter:

! Diagnostic Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99! RoutingClientGUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99! TestXML Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100! Servlet Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102! Classic Routing Servlet Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103! Isochrone Servlet Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106! MultiPoint Servlet Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109! Sample Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110! Include/Exclude Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111! Point and Click Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113! Directions Sample. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115! Classpaths for Routing Samples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115! Localization of Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Developer Guide Chapter 10: Working with Routing Samples

Diagnostic Samples

Mapinfo Routing J Server provides diagnostic samples that enable you to verify that everything has been installed and setup correctly. The diagnostic samples are:

� RoutingClientGUI� TestXML

RoutingClientGUI

This sample client program is a diagnostic tool that demonstrates the use of many of the public properties and methods. Refer to this application as an example for how to create a routing client, attach to the server, calculate routes, and retrieve your results. You should also refer to the online documentation (\RoutingJServer-30\docs\index.html), which explains the MapInfo Routing J Server classes with their properties and methods. The server must be running to use this application. An application file for invoking the RoutingClientGUI sample, called RoutingClientGUI, is provided in the \RoutingJServer-3.0\examples_usa\diagnostics\RoutingClientGUI directory. You can also make modifications by editing the RoutingClientGUI.lax file.

To create a route, enter the longitude and latitude for Starting Coordinates and Ending Coordinates. From the Tools menu, select Route to display your route information. You can also choose a unit of measurement or time and switch between shortest distance and shortest time through options available in the Preferences menu.



TestXML Sample

The TestXML sample allows you to read requests from the files, send them to the server, and output an XML response to a screen or a file. This allows you to verify that the XML document is valid and to get the results of the request. Run the run.bat or run.sh (depending on your operating system). This file can be found in the \RoutingJServer-3.0\examples_usa\diagnostics\TestXML directory.

Route RequestThis is a sample of the route request XML file. Look in \RoutingJServer-3.0\examples_usa\diagnostics\TestXML for other XML sample requests. To make modifications to this file, or if you are writing your own XML client, review the information about valid elements beginning on page 79.

<RoutingRequestEnvelope Locale="en_US"><RouteRequest>

<RoutePointList>

<StartPoint><Point>

<coord><X>-77.033295</X><Y>38.898712</Y>

</coord></Point>

</StartPoint><EndPoint>

<Point><coord>

<X>-77.000622</X><Y>38.9158939</Y>

</coord></Point>

</EndPoint></RoutePointList><RouteConstraints>

<ShortestTime/><UsePersistentUpdates>false</UsePersistentUpdates><MustIncludeList>

<Point><coord>

<X>-77.0219001</X><Y>38.905579</Y>

</coord></Point>

</MustIncludeList><TimeConstraints>

<StartDateTime><dateTime> 2003-03-01T09:00:00-05:00</dateTime>

</StartDateTime></TimeConstraints><UpdateList>

<Update>

<RoadTypeUpdate><RoadType>major road urban</RoadType><SpeedUpdate>

<Velocity><VelocityUnit>

<LinearUnit><NameSet>

<name>miles</name></NameSet><unitsPerMetre>6.21371E-4</unitsPerMetre>

</LinearUnit><TimeUnit>

<NameSet><name>hours</name>

</NameSet><secondsPerUnit>3600</secondsPerUnit>

</TimeUnit></VelocityUnit><VelocityValue>20</VelocityValue>

</Velocity></SpeedUpdate>

</RoadTypeUpdate></Update>

</UpdateList></RouteConstraints><RouteResponseConstraints>

<TimeUnit>

<NameSet><name>minutes</name>

</NameSet><unitsPerSecond>0.0166667</unitsPerSecond>

</TimeUnit><LinearUnit>

<NameSet><name>miles</name>

</NameSet><unitsPerMetre>6.21371E-4</unitsPerMetre>

</LinearUnit><ReturnSegmentGeometry>end</ReturnSegmentGeometry><DirectionConstraints>



<DirectionsGeneratorName>SampleDirectionsGenerator</DirectionsGeneratorName>

</DirectionConstraints><SuccessResponse IncludeActualConstraints="true"/>

</RouteResponseConstraints></RouteRequest></RoutingRequestEnvelope>


Persistent UpdatesBy default, PersistentUpdates are disabled. For the persistent updates sample XML in the TestXML sample to work, the following initialization parameters need to be changed.

For RoutingServlet, the handlesPersistentUpdates init param must be set to true.

<init-param><param-name>handlesPersistentUpdatesRequests</param-name><param-value>true</param-value></init-param>

Servlet Samples

Mapinfo Routing J Server provides servlet samples that demonstrate the functionality available to you. The servlet samples are:

� Classic Routing Servlet� Isochrone Servlet� MultiPoint Servlet

SetupBefore using any of the servlet samples be certain that the following requirements are met:

� Routing J Server, MapMarker J Server, and MapXtreme Java have been installed and are running properly.

� The preferences in the RoutingSamples.properties file have the correct configuration. RoutingSamples.properties is located in the \RoutingJServer-3.0\examples_usa\servlets\WEB-INF\classes directory. This file contains information such as server name and port number for the Routing J Server, MapMarker J Server, and MapXtreme.

� The TrueType font sets that are provided with MapXtreme Java are registered with your operating system. See the section, MapXtreme Java Font Sets on page 103 for more information.

� The sample display data provided is for a limited geography. You must load data for other geographies to display maps outside of the sample data set. Otherwise, if your route goes out of the sample data set, it will display with no map behind it.

Sample Display DataFor the samples that display a map to work (all samples that are not diagnostics), if MapXtreme Java is on a remote machine from Routing J Server, the sample display data must be copied to the machine where MapXtreme Java resides. The path to the .tab files in the .mdf file should indicate the path to the data on the machine where MapXtreme Java resides.

For example, if the data is copied to c:\mapinfo\mapxtremejava\maps on the machine where MapXtreme Java resides, the paths in the .mdf file should be changed to that path.

<Url>tab:c:\mapinfo\mapxtremejava\maps?remote=http://machine:port/mapxtreme45/mapxtreme</Url>

The installer will set the remote portion of the above path.




MapXtreme Java Font SetsMapXtreme Java provides 10 TrueType font sets. These fonts are installed and automatically registered on Windows. They are located in the server\fonts directory.

On platforms other than Windows, the installer copies the fonts into the /server/fonts directory. After installation, you will need to register the fonts with your operating system in order to use them. If you do not register these fonts, incorrect symbols display on the map. For detailed instructions, refer to the MapXtreme Java Edition documentation.

Classic Routing Servlet Sample

The Classic Routing Servlet Sample was designed using a Model View Controller architecture. A typical single machine deployment will have Routing J Server and MapXtreme Java running in the servlet runner (e.g., Tomcat) with MapMarker J Server running as a stand-alone application. MapMarker J Server will use ports 4141 and 4242 by default. Tomcat will use port 8080 by default. The ports can be changed, but an exception will occur if they conflict.

The classic routing servlet sample enables you to geocode two addresses and create a route between them, and display points of interest along the route. This sample also serves as an example of how Routing J Server can be integrated with other MapInfo products.

The files for this sample are installed in the \RoutingJServer-3.0\examples_usa\servlets\Classic directory. To run this sample, open a Web browser and go to http://localhost:8090/rjssamples30usa/Classic. Localhost is the name or IP address of the machine running the Web server.

Displaying a RouteTo display a route:

1. Enter the start address in the supplied fields.2. Enter the destination address in the supplied fields.3. Choose between a route with the shortest distance or the shortest time.4. Select the language in which the directions will display.5. Click FIND.




6. Verify the addresses. If either the starting or ending address is incorrect, click BACK to enter a different address. If more than one address appears in either list, select the most appropriate one.

7. Click ROUTE to generate the route.




8. To generate a return route click GET RETURN DIRECTIONS.

Points of Interest (POI)The classic sample includes the ability to add points of interest to your text directions. This features assumes an understanding of .tab files. For more information on .tab files, refer to the MapInfo Professional documentation set. For instance, "Turn left onto main street...passing a McDonald's." This is accomplished by specifying a lookup table or a list of lookup tables. To do this, specify the following variables in the RoutingSamples.properties:

� SHOW_POINTS_OF_INTEREST: whether or not to show the points of interest. Acceptable values are yes/no.

� POI_TABLE_NAME: a comma delimited list of MapInfo .tab files.� POI_TABLE_PATH: the path to the above .tab files.� POI_TABLE_COLUMN: the column in the .tab files to display. This is the name of

column.� POI_DISPLAY_NUMBER: the number of points to display. If you assign two points, but

your table has more than two points, the first two points will display.

Here is an example of how the parameters can be set:

� SHOW_POINTS_OF_INTEREST=yes� POI_TABLE_NAME=NY_ret.TAB, NY_ret1.TAB� POI_TABLE_PATH=d:/data/Acxiom/NY_RET/� POI_TABLE_COLUMN=Business� POI_DISPLAY_NUMBER=2




The above parameters assume that all of the tables are in the same directory and the specified column is the same for each table.

Isochrone Servlet Sample

The isochrone servlet sample integrates Routing J Server with other MapInfo products. This sample enables you to generate an isochrone based on an address and cost.

The files for this sample are installed in the \RoutingJServer-3.0\examples_usa\servlets\Isochrones directory. To run this sample, open a Web browser and go to http://localhost:8090/rjssamples30usa/Isochrones. Localhost is the name or IP address of the machine running the Web server.

Generating an IsochroneTo generate an isochrone:

1. Enter an address in the supplied fields. Select three iso costs (i.e,. 3, 5, and 7) and specify a cost unit. Click the FIND button.




2. Verify the address. If it is incorrect, click the BACK button to enter a different address. If more than one address appears in the list, select the most appropriate one. Set any of the basic options on this screen.

3. Advanced users can click the ADVANCED OPTIONS button to make further changes.

4. Click the CREATE ISO button to generate the isochrone.




The iso displays.

OptionsEach of the options on the Verify Address screen is explained below:

Response Type

� Geometry: Shows the isochrone as a region.� Start Nodes: Shows the location specified by the entered address.� Accessible Nodes: Shows all of the possible locations that can be reached.

Use Only Major Roads

� Yes: Generate the isochrone based on major roads only.� No: Allow minor roads to be included in the isochrone generation.

Return Holes

� Yes: Allow holes to be present in the returned polygons.� No: No holes should be present in the returned polygons.

Return Islands

� Yes: Allow islands to be present in the returned polygons.� No: No islands should be present in the returned polygons.




Advanced OptionsEach of the Advanced Options is explained below:

� Maximum Off-Network Distance: Set the maximum distance the isochrone engine can travel off the network.

� Simplification Factor: A percentage to determine how much to simplify the polygon returned by the engine. The higher the value (closer to 100), the more points that will be returned.

� Default Ambient Speed: A default speed for the off-network roads.� Default Propagation Factor: A value between 0 and 1 that determines the range of

propagation off the network.� Ambient Speed Overrides Road Type: Set a new default speed for a selected road

type.� Propagation Factor Overrides Road Type: Set a new propagation factor for a selected

road type.

MultiPoint Servlet Sample

The multiPoint servlet sample enables you to generate intermediate points between the start and end points of your route.

The files for this sample are installed in the \RoutingJServer-3.0\examples_usa\servlets\MultiPoint directory. To run this sample, open a Web browser and go to http://localhost:8090/rjssamples30usa/MultiPoint. Localhost is the name or IP address of the machine running the Web server.

Generating a MultiPoint Route1. Enter an address:

Click the ADD AN ADDRESS button and fill in the appropriate information. Click the FIND button.

2. Verify the address: If this address is incorrect, click the BACK button to enter a different address. If more than one address appears in the list, select the most appropriate one and click the SELECT button.

3. Repeat Steps 1 and 2, until you have at least three addresses. The minimum number of addresses in a multiPoint route is three; the maximum is limited by the capabilities of your machine.

4. Click the ROUTE button on the lower right hand side of the screen to generate the multiPoint route.




5. Browse the driving directions. For individual directions, select the route section under Route Information that you would like to see directions for and click SECTION DIRECTIONS. For all directions, click the ALL DIRECTIONS button.

Sample Applications

Mapinfo Routing J Server provides sample application that demonstrate the functionality available to you. The sample applications are:

� Include/Exclude� Point and Click




SetupBefore using the sample applications, be sure that:

� Routing J Server, MapMarker J Server, and MapXtreme Java have been installed and are running properly.

� The preferences in the RoutingSample.properties file have the correct configuration. RoutingSample.properties is located in the \RoutingJServer-3.0\examples_usa\servlets\applications\IncludeExclude directory. This file contains information such as server name and port number for the Routing J Server, MapMarker J Server, and MapXtreme.

� The TrueType font sets that are provided with MapXtreme Java are registered with your operating system.

� The sample display data provided is for a limited geography. You must load data for other geographies to display maps outside of the sample data set. Otherwise, if your route goes out of the sample data set, it will display with no map behind it.

Include/Exclude Sample Application

The include/exclude sample application enables you to specify geographies to include or exclude from your route, as well as specify the shortest distance or shortest time.

The files for this sample are installed in the \RoutingJServer-3.0\examples_usa\servlets\applications\IncludeExclude directory. You can use this sample by running the application file, IncludeExclude, in the above directory. You can also make modifications by editing the IncludeExclude.lax file.

FeaturesThis sample application allows you to generate a route, specify shortest distance or shortest time, include points, and exclude points.

When using include, these options are available:

� Select a point to include in the route. � Specify the point by clicking on the map or by entering a long/lat.� Label each included point.� Reorder the included points.� Set the speed for a road by specifying a point.

When using exclude, these options are available:

� Select a point to exclude from the route.� Specify the point by clicking on the map or by entering a long/lat.� Select multiple points to exclude from the route.� Label each excluded point. � Set the speed for a road by specifying a point.

Additional Notes� If more than one point is included in the route, the points can be re-ordered using the

up and down buttons to the right of the field in which the included points are shown.




This is very important because the route will cover the points in the order they are listed on the screen.

� Includes and excludes may be deleted using the buttons located between the list of includes and the list of excludes.

� When including, the route will intersect, but not necessarily contain, the closest included segment. When you include a point, it finds the closest point (not the closest segment) and includes that. The sample, however, highlights the closest segment.

� When excluding a major road (that may or may not be divided), be sure to click closest to the side of the road that you want to exclude. Depending on the display data that you are using, a road may look excluded in both directions on the display map, when it is really excluded in one direction. This could make the road you excluded appear not to be excluded when the route is displayed.

� For information about general mapping functionality, see the section, Manipulating Layers with Map Tools in the latest version of the MapInfo MapXtreme Java Edition Developer�s Guide.

Creating a Route with Included/Excluded Geographies1. Enter a starting address and an ending address in the appropriate fields.2. Select whether to route by the Shortest Distance or Shortest Time.3. Click the ROUTE button to generate the route. The map displays the route and driving

directions are supplied. 4. Click the INCLUDE/EXCLUDE tool (the arrow on the far right of the toolbar). To include a

geography go to step 5. To exclude a geography go to step 6.5. Make sure INCLUDE is selected from the radio buttons below the map. Click on the map

to select a segment closest to the desired point. A dialog displays. You can change the longitude or latitude of this point as well as enter an identifying label for the point. Click the INCLUDE button on the dialog box to confirm your choice and close the dialog. Shortly, the segment will be highlighted on the map. Select additional segments if desired. Click the ROUTE button to generate the new route.




6. Click the EXCLUDE option under the map. Click on the map to exclude the closest segment to that point. A dialog displays. You can change the longitude or latitude of this point as well as enter an identifying label for the point. Click the EXCLUDE button on the dialog box to confirm your choice and close the dialog. Shortly, the segment will be highlighted on the map. Select additional segments if desired. Click the ROUTE button to generate the new route.

.

Point and Click Sample Application

The Point and Click application uses Routing J Server to find routes and the MapXtreme Java client to display routes on map. You can click on the map to specify start and end points and to route between them.

Features� basic map manipulation (pan and zoom)� point to point route and optimal multi-point route� route optimization by time or by distance� time and distance units setting used for driving directions

For information on basic map manipulation and how to use pan and zoom buttons refer to the MapXtreme Java Developer Guide.




Generating a Route1. Set routing preferences (shortest time/shortest distance, time units, distance units)

through the Routing Preferences menu.2. Click the POINT SELECT TOOL button.3. Click on the map to point to a start location.4. Click on the map again to point to an end location.5. Click the ROUTING TOOL to create the route.6. Wait for the route to appear on the map. The route start point will be marked by a green

pin and the end point by a red pin. Driving directions will be shown in the scroll pane below.

Generating a MultiPoint Route1. Set routing preferences (shortest time/shortest distance, time units, distance units)

through the Routing Preferences menu.2. Click the POINT SELECT TOOL button.3. Click on the map to point to a start location.4. Click on the map again to point to intermediate location(s).5. Cick on the map to point to an end location.6. Click the ROUTING TOOL to create the route.7. Wait for the route to appear on the map. The route start point will be marked by green

pin, intermediate points by yellow pins, and the end point by a red pin. Driving directions will be shown in the scroll pane below.




Directions Sample

A sample directions generator is provided in RoutingJServer-3.0/examples-usa/direction directory. It demonstrates how to perform server-side customization of directions. For demonstration purposes each direction string generated by this generator starts with the word "sample".

The SampleDirectionsGenerator can be added to the Routing J Server as follows:

1. Place com/mapinfo/routing/direction/SampleDirectionsGenerator.class in the server classpath (copy "com" folder from RoutingJServer-3.0/examples-usa/direction to RoutingJServer-3.0/Tomcat-4.1/webapps/routing30/WEB-INF/classes).

2. Place direction-registry.xml found under RoutingJServer-3.0/examples-usa/direction in the server classpath (copy direction-registry.xml to RoutingJServer-3.0/Tomcat-4.1/webapps/routing30/WEB-INF/classes).

Additional Notes� To use the SampleDirectionsGenerator to generate directions for a route, specify its

name in the request. � The route_request.xml file in RoutingJServer-3.0/examples-usa/diagnostics/TestXML/

demonstrates how to set the generator name via XML. To set the generator name please uncomment the DirectionsGeneratorName element.

� Run TestXML application with this request file to test the sample generator. For more information, see the section, TestXML Sample on page 100.

� To specify the generator name using Java API, call DirectionsPreferences.setDirections GeneratorName("SampleDirectionsGenerator").

� The source code for the sample directions generator is provided under RoutingJServer-3.0/examples-usa/direction/src. To compile the SampleDirectionsGenerator, put the rjsserver.jar, micsys.jar, and commons-lang.jar on the classpath. These jar files can be found under the routing tomcat, WEB-INF/lib.

Classpaths for Routing Samples

Before recompiling any of the routing samples, make sure that the classpath has the correct information. The information for each sample is located in this section. The installer creates a lib directory with the files broken out into server, client, and common subdirectories. The jar files needed are in these directories.

Note: In any of the samples where the miutil.jar is used, the file, encoding-map.xml must be on the classpath. This file is installed in <INSTALL_DIR>\RoutingJServer-3.0\bin.

The paths used in the following examples are:

set RJS_BIN=<RJS_DIR>\RoutingJServer-3.0\binset RJS_COMMON=<RJS_DIR>\RoutingJServer-3.0\lib\commonset RJS_CLIENT=<RJS_DIR\RoutingJServer-3.0\lib\clientset MMJ=<MMJ_DIR>set MXJ=<MXTJ_DIR>\MapXtreme-4.5.0\lib\client

IncludeExcludeset CLASSPATH=.set CLASSPATH=%CLASSPATH%;%RJS_BIN%\RoutingJServer-3.0\bin




set CLASSPATH=%CLASSPATH%;%RJS_COMMON%\miutil.jarset CLASSPATH=%CLASSPATH%;%RJS_COMMON%\micsys.jarset CLASSPATH=%CLASSPATH%;%RJS_COMMON%\jdom.jarset CLASSPATH=%CLASSPATH%;%RJS_CLIENT%\rjsclient.jarset CLASSPATH=%CLASSPATH%;%MXJ%\mxjclient.jarset CLASSPATH=%CLASSPATH%;%MXJ%\mxjbeans.jarset CLASSPATH=%CLASSPATH%;%MMJ%\MapMarkerJServerClient.jar

RoutingAdmin and RoutingClientGUIset CLASSPATH=.set CLASSPATH=%CLASSPATH%;%RJS_BIN%\RoutingJServer-3.0\binset CLASSPATH=%CLASSPATH%;%RJS_COMMON%\micsys.jarset CLASSPATH=%CLASSPATH%;%RJS_CLIENT%\rjsclient.jar

TestXMLset CLASSPATH=.set CLASSPATH=%CLASSPATH%;%RJS_BIN%\RoutingJServer-3.0\binset CLASSPATH=%CLASSPATH%;%RJS_COMMON%\micsys.jarset CLASSPATH=%CLASSPATH%;%RJS_CLIENT%\rjsclient.jarset CLASSPATH=%CLASSPATH%;%RJS_COMMON%\jdom.jarset CLASSPATH=%CLASSPATH%;%RJS_COMMON%\xmlParserApis.jar

Servlet SamplesFor common classes used by all the servlet samples:

set COMMON_CLASSES=../common/classes

For the encoding-map.xml file:

set RJS_BIN=<RJS_DIR>\RoutingJServer-3.0\bin

set CLASSPATH=.set CLASSPATH=%CLASSPATH%;%RJS_CLIENT%\rjsclient.jarset CLASSPATH=%CLASSPATH%;%RJS_BIN%\RoutingJServer-3.0\binset CLASSPATH=%CLASSPATH%;%RJS_COMMON%\miutil.jar;set CLASSPATH=%CLASSPATH%;%RJS_COMMON%\jdom.jarset CLASSPATH=%CLASSPATH%;%RJS_COMMON%\micsys.jarset CLASSPATH=%CLASSPATH%;%RJS_COMMON%\servlet.jarset CLASSPATH=%CLASSPATH%;%MXJ%\mxjclient.jarset CLASSPATH=%CLASSPATH%;%MXJ%\mxjbeans.jarset CLASSPATH=%CLASSPATH%;%MMJ%\MapMarkerJServerClient.jarset CLASSPATH=%CLASSPATH%;%COMMON_CLASSES%

Localization of Samples

The Point And Click sample application is fully localizable. While other samples included with Routing J Server 3.0 are not localized, there are ways to configure them to appear customized for a locale. Use the information following the PointandClick section to guide your customization.




PointAndClickThis application ships with preset the language and country used for driving directions and text in the graphical user interface. These can be specified in the RoutingSamples.properties file located in the samples directory. Change the following values in RoutingSamples.properties to specify the default language and country:

LANGUAGE

COUNTRY

In addition, a localized version of PointAndClickStrings.properies file should be provided and included into the rjssamplesusa.jar.jar in the com.mapinfo.routing.sampleapp.pointandclick package. For example, provide a PointAndClickStrings_fr_FR.properies file with strings in French.

This application contains preset display data that is used for generating the map. The path to the Map Definition File can also be specified in the RoutingSamples.properties. To change the .mdf file to be used for display, modify the following value:

MAP_DEFINITION_FILE

RoutingClientGuiThis application ships with preset latitudes and longitudes. These can be specified in the RoutingSamples.properties file located in the samples directory. Change the following values in RoutingSamples.properties to specify the default latitudes and longitudes:

DEFAULT_LONGITUDE_1

DEFAULT_LATITUDE_1

DEFAULT_LONGITUDE_2

DEFAULT_LATITUDE_2

IncludeExcludeThis application ships with preset addresses. These can be specified in the RoutingSamples.properties file located in the samples directory. Change the following values in RoutingSamples.properties to specify the default addresses:

DEFAULT_STREET_1

DEFAULT_CITY_1

DEFAULT_COUNTRY_SUBDIVISION_1

DEFAULT_POSTAL_CODE_1

DEFAULT_STREET_2

DEFAULT_CITY_2



This application ships with preset tab file used to geocode a city and country subdivision pair. This can be specified in the RoutingSamples.properties. To change the tab file, modify the following values:




CITY_TAB_FILE

CITY_COLUMN

COUNTRYSUBDIVISION_COLUMN

This application contains preset display data that is used for generating the map. The path to the Map Definition File (.mdf) can also be specified in the RoutingSample.properties file. To change the .mdf file to be used for display, modify the following value:

MAP_DEFINITION_FILE

For any further localization (changing/formatting GUI text and specified units), modifying the source and recompiling is necessary.

Classic, MultiPoint, and Iso ServletsThese servlets ship with preset addresses. These can be specified in the RoutingSamples.properties file located in the WEB-INF\classes directory wherever the servlets have been deployed. Change the following values in RoutingSamples.properties to specify the default addresses:

DEFAULT_STREET_1

DEFAULT_CITY_1



DEFAULT_STREET_2

DEFAULT_CITY_2



These servlets ship with preset .tab files used to geocode a city and country subdivision pair. This can be specified in the RoutingSamples.properties. To change the .tab file, modify the following values:

CITY_TAB_FILE

CITY_COLUMN

COUNTRYSUBDIVISION_COLUMN

These servlets also contain preset display data that is used for generating the map. The path to the Map Definition File can also be specified in the RoutingSamples.properties. To change the .mdf file to be used for display, modify the following value:

MAP_DEFINITION_FILE

The JSPs used by these servlets can also be modified for added localization. Text on the JSPs can be translated and the data values (distance, time, etc) can be formatted using Java's NumberFormat class.

For any further localization (specifying units), modifying the source and recompiling is necessary.



11
Troubleshooting
This chapter contains important information to help determine why your routing application may not function properly. MapInfo Technical Support also publishes a full knowledge base on all MapInfo products to the Support section of the Web site. For more information, go to http://testdrive.mapinfo.com/kbase_by_product.

In this chapter:

! MapInfo Routing J Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120! Testing the Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121! Web Server Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121! Tomcat Installation on Windows 2000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121



Developer Guide Chapter 11: Troubleshooting

MapInfo Routing J Server

Use the following section to help resolve general problems with the Routing J Server.

Issue What are common steps I can take to make sure the Routing J Server is working correctly?

Resolution� Test the connection by opening an browser and going to

http://<HOSTNAME>:<PORT_NUMBER>/routing30/servlet/routing?debug=true.� Test it with the RoutingClientGUI sample application. � Check the settings and preferences specified in the web.xml file. � Make sure that your environment variables are set properly. On your server, make sure

that rjsserver.jar is in the classpath for your routing30 context. For your application, make sure that rjsclient.jar is in the classpath.

� Check that the paths specified in the configuration text file or on the command line contain the path of your routing data directory.

� Case is significant in Java. Make sure that you specify the class names exactly as documented on the command line as well as in your application program. For example, use RoutingServlet not routingservlet.

� Refer to the section, Performance Tuning on page 5 for performance information.� Set the log4j.properties configuration file to debug. This shows trace information that

can help prove that something is working as it should, or help decipher a problem. For more information, see the section, Logging on page 27.

IssueThe server hangs when using jdk 1.4.1.

ResolutionMake sure that you use the -server option.

IssueThe Routing J Server does not complete routes in certain geographies.

ResolutionMake sure that you have installed all of the datasets for any area that your routes may traverse.

IssuePersistent updates do not work properly.

ResolutionPersistent updates for a particular dataset will only work if that dataset is loaded. For example, if you are working with United Stated data and the NorthEast dataset contains updates but you only load the Central dataset, the updates will not be available.



Developer Guide Chapter 11: Troubleshooting

Testing the Connection

Use the following section to test the connection with the Routing J Server.

IssueI want to check my connection.

ResolutionTest the connection by opening an browser and going tohttp://<HOSTNAME>:<PORT_NUMBER>/routing30/servlet/routing?debug=true.

You can also use the RoutingClientGUI sample program that comes with MapInfo Routing J Server to check the HTTP connection. Check the connection with your custom client application as well. Verify that you can create a route.

Web Server Connection

Use the following section to help resolve problems with your Web server connection.

IssueI receive the following exception: java.security.AccessControlException.

ResolutionMake sure that your routing update file path has read, write, and delete access.

Tomcat Installation on Windows 2000

Use the following section to help resolve problems with Tomcat.

IssueTomcat does not start on Windows 2000.

ResolutionCheck the value of the %OS% environment variable. The startup scripts require the value of %OS% set to "Windows_NT". If the %OS% does not have this value, modify the environment variable value or modify the startup scripts for the current value of %OS%.



A
Web.xml
This appendix contains a sample web.xml file. Use this file as a guideline if you need to re-create or modify your file.

Sample web.xml File

The following is a sample web.xml file.

- <web-app>- <servlet>

<servlet-name>routing</servlet-name> <servlet-class>

com.mapinfo.routing.RoutingServlet </servlet-class> -  - <init-param>

<param-name>datasetList</param-name> <param-value>@datalist@</param-value>

</init-param>- <init-param>

<param-name>routingUpdateFilePath</param-name> <param-value>@filepath.update@</param-value>

</init-param>-  - <init-param>

<param-name>shortProcessThreads</param-name> <param-value>@shortProcessThreads@</param-value>


<param-name>longProcessThreads</param-name> <param-value>@longProcessThreads@</param-value>

</init-param>-  - <init-param>

<param-name>handlesRouteRequests</param-name> <param-value>true</param-value>


<param-name>handlesIsoRequests</param-name> <param-value>true</param-value>


<param-name>handlesMultiPointRequests</param-name> <param-value>true</param-value>


<param-name>handlesRoutingDataRequests</param-name> <param-value>true</param-value>

</init-param>

Developer Guide Appendix A: Web.xml

- <init-param> <param-name>handlesPersistentUpdatesRequests</param-name> <param-value>false</param-value>


<param-name>handlesMatrixRouteRequests</param-name> <param-value>true</param-value>


<param-name>acceptOldRequests</param-name> <param-value>true</param-value>


<param-name>validate</param-name> <param-value>false</param-value>

</init-param>-  - <init-param>

<param-name>distUnit</param-name> <param-value>@distUnit@</param-value>


<param-name>timeUnit</param-name> <param-value>minute</param-value>


<param-name>speedUnit</param-name> <param-value>@speedUnit@</param-value>

</init-param>-  - <init-param>

<param-name>routeTimeout</param-name> <param-value>500000</param-value>


<param-name>multiPointTimeout</param-name> <param-value>600000</param-value>


<param-name>isoTimeout</param-name> <param-value>600000000</param-value>


<param-name>matrixRouteTimeout</param-name> <param-value>1200000</param-value>

</init-param>-  - <init-param>

<param-name>allowFallback</param-name> <param-value>true</param-value>


<param-name>returnPoints</param-name> <param-value>all</param-value>


<param-name>returnDirections</param-name> <param-value>true</param-value>


<param-name>returnSegmentData</param-name> <param-value>false</param-value>

</init-param>

Developer Guide Appendix A: Web.xml

-  - <init-param>

<param-name>optimizeBy</param-name> <param-value>shortestTime</param-value>

</init-param>-  - <init-param>

<param-name>multiPointStopThreshold</param-name> <param-value>0.01</param-value>

</init-param>-  - <init-param>

<param-name>isoMajorRoadsOnly</param-name> <param-value>false</param-value>


<param-name>isoSimplificationFactor</param-name> <param-value>0.05</param-value>


<param-name>isoDefaultPropagationFactor</param-name> <param-value>0.16</param-value>


<param-name>isoDefaultAmbientSpeedUnit</param-name> <param-value>mph</param-value>


<param-name>isoDefaultAmbientSpeed</param-name> <param-value>15</param-value>

</init-param> <load-on-startup>1</load-on-startup>

</servlet>- <servlet-mapping>

<servlet-name>routing</servlet-name> <url-pattern>/servlet/routing</url-pattern>

</servlet-mapping> </web-app>

B
Initialization Parameters
This appendix lists the parameters in the web.xml file.

RoutingServlet Parameters

The parameters in the following table can be set in the web.xml file. The parameters and paths are case-sensitive. The table below identifies the init parameters for RoutingServlet that you can control.

OPTION VALUE DEFAULT DESCRIPTION

datasetList string The default is the path to the directory where the Routing J Server is installed.

A semi-colon separated list of the direc-tories that contain the datasets to be used by the Routing J Server. For example:d:\mapinfo\v30data\usa\North-East;d:\mapinfo\v30data\usa\South;

routingUpdateFilePath string The default is the path to the directory where the Routing J Server is installed.

Full pathname only (no filename) of the file specifying the default road speeds for all road classes in the system. Sup-ported road classes (or types) are listed in RoadType javadoc. For persistent updates, current road speeds for seg-ments and road types are written into .rcs and .as files in the same directory. Therefore this path should point to a writable directory.

shortProcessThreads integer Number of cpus on the machine.

The number of threads to be used for point to point route requests and rout-ing data requests. Note that there is always one thread for PersistentUp-dates. If this parameter is left com-mented out in the web.xml, it will be set to the number of CPUs.

longProcessThreads integer Number of cpus on the machine.

The number of threads to be used for isochrone, matrix route and multipoint route requests. If this parameter is left commented out in the web.xml, it will be set to the number of CPUs.

handlesRouteRequests true/false true If true, the servlet handles the route requests.

Developer Guide Appendix B: Initialization Parameters

handlesIsoRequests true/false true If true, the servlet handles the iso requests.

handlesMultiPointRe-quests

true/false true If true, the servlet handles the multi-Point requests.

handlesRoutingData Requests

true/false true If true, the servlet handles the routing data requests.

handlesPersistentUp-dates Requests

true/false true If true, the servlet handles real-time traffic updates.

handlesMatrixRoute Requests

true/false true If true, the servlet handles the matrix route requests.

acceptOldRequests true/false true If true, requests from previous versions (2.0 and 2.5) can be used.

validate true/false false If true, the server will validate every XML route request against the DTD. This parameter is only necessary if the client is generating its own XML.

distUnit foot/yard/mile/meter/kilometer

mile Distance unit to use.

timeUnit second/minute/hour

minute Time unit to use.

speedUnit mph/kph/mtps mph Speed unit to use.

routeTimeout milliseconds 500,000 The amount of processing time before stopping if processing is not complete.

multiPointTimeout milliseconds 600,000 The amount of processing time before stopping if processing is not complete.

isoTimeout milliseconds 600,000,000 The amount of processing time before stopping if processing is not complete.

matrixTimeout milliseconds 1,200,000 The amount of processing time before stopping if processing is not complete.

allowFallback true/false true If true, the engine will use major roads when other roads cannot be used.

returnPoints none/all/end all Type of path points to return.

returnDirections true/false true Returns driving directions.

returnSegmentData true/false false Return segment data.

optimizeBy shortest time/shortest dis-tance

shortest time Finds the shortest distance or finds the shortest time. This setting has to do with route results as opposed to iso results.




Developer Guide Appendix B: Initialization Parameters

simplificationFactor double 0.05 A value between 0 and 1 that repre-sents the percentage of points to return for a polygon. For instance, a value of 0.05 means the polygons will be returned with only 5% of their original points. Reducing this value improves transfer speed.

isoDefaultPropagation-Factor

double 0.16 The default propagation factor for iso-distances.

isoDefaultAmbientSpeed Unit

string mph The default unit for the ambient speed setting. Available strings are mph and kph.

isoDefaultAmbientSpeed double 15 The default ambient speed for isoch-rones.




C
Deprecated API
The routing API has undergone a number of changes. The following sections list deprecated classes, fields, methods, and constructors.

Deprecated Classes

As of Version 3.0, RoutingAdminClient has been deprecated.

Deprecated Fields

The following is a complete list of deprecated fields:

� RoutingPreferences.DIRECTIONS_STYLE_NORMAL � As of Version 3.0, use DirectionsPreferences.STYLE_NORMAL

� RoutingPreferences.DIRECTIONS_STYLE_TERSE � As of Version 3.0, use DirectionsPreferences.STYLE_TERSE

� RoutingPreferences.FOCUS_END � As of Version 3.0, use DirectionsPreferences.FOCUS_END

� RoutingPreferences.FOCUS_NONE � As of Version 3.0, use DirectionsPreferences.FOCUS_NONE

� RoutingPreferences.FOCUS_START � As of Version 3.0, use DirectionsPreferences.FOCUS_START

� RouteSegment.MAX_ALTERNATE_NAMES � As of Version 3.0, use RouteSegment.getAltNames().length instead.

� LinearUnit.pica � Not a valid "distance" unit. � LinearUnit.point � Not a valid "distance" unit. � LinearUnit.twip � Not a valid "distance" unit.

Developer Guide Appendix C: Deprecated API

Deprecated Methods

The following is a complete list of deprecated methods:

� RoutingPreferences.addExclude(RoutePoint) � As of Version 3.0, use RoutingPreferences.addUpdate(TransientUpdate)

� MatrixRoutePreferences.addExclude(RoutePoint) � As of Version 3.0, use MatrixRoutePreferences.addUpdate(TransientUpdate)

� RoutingPreferences.addExclude(String) � As of Version 3.0, use RoutingPreferences.addUpdate(TransientUpdate)

� MatrixRoutePreferences.addExclude(String) � As of Version 3.0, use MatrixRoutePreferences.addUpdate(TransientUpdate)

� RoutingPreferences.addInclude(String) � As of Version 3.0, this does nothing. � RoutingPreferences.addRoadSpeeds(RoadType, Velocity) � As of Version 3.0, use

RoutingPreferences.addUpdate(TransientUpdate) � MatrixRoutePreferences.addRoadSpeeds(RoadType, Velocity) � As of Version 3.0,

use MatrixRoutePreferences.addUpdate(TransientUpdate) � RoutingPreferences.addRoadSpeeds(RoutePoint, Velocity) � As of Version 3.0, use

RoutingPreferences.addUpdate(TransientUpdate) � MatrixRoutePreferences.addRoadSpeeds(RoutePoint, Velocity) � As of Version 3.0,

use MatrixRoutePreferences.addUpdate(TransientUpdate) � RoutingPreferences.addRoadSpeeds(String, Velocity) � As of Version 3.0, use

RoutingPreferences.addUpdate(TransientUpdate) � MatrixRoutePreferences.addRoadSpeeds(String, Velocity) � As of Version 3.0, use

MatrixRoutePreferences.addUpdate(TransientUpdate) � RoutingPreferences.addSegmentRoadType(String, RoadType) � As of Version 3.0,

use RoutingPreferences.addUpdate(TransientUpdate) � RoutingPreferences.clearRoadSpeeds() � As of Version 3.0, use

RoutingPreferences.addUpdate(TransientUpdate) � MatrixRoutePreferences.clearRoadSpeeds() � As of Version 3.0, use

MatrixRoutePreferences.addUpdate(TransientUpdate) � RoutingPreferences.clearSegmentRoadTypes() � As of Version 3.0, use

RoutingPreferences.addUpdate(TransientUpdate) � MatrixRoutePreferences.clearSegmentRoadTypes() � As of Version 3.0, use

MatrixRoutePreferences.addUpdate(TransientUpdate) � Unit.convert(double[], int, double[], int, int, Unit) � Unit.convert(double[], int, int, Unit) � LinearUnit.convert(double, AngularUnit) � Use UnitUtil.convert method instead. � AngularUnit.convert(double, LinearUnit) � Use UnitUtil.convert method instead. � Unit.convert(DoublePoint, DoublePoint, Unit) � LinearUnit.convert(double, Unit) � AngularUnit.convert(double, Unit) � Use unit specific versions instead. � Unit.convert(double, Unit) � RoutingClient.findRoute(double, double, double, double) � As of Version 2.5, use

RoutingClient.findRoute(RoutePoint,RoutePoint) � MultiPointClient.findRoute(double, double, double, double, RoutePoint[]) � As of

Version 2.5, use MultiPointClient.findRoute(RoutePoint,RoutePoint,IntermediatePoint[])

� MultiPointClient.findRoute(RoutePoint, RoutePoint, RoutePoint[]) � As of Version 2.5, use MultiPointClient.findRoute(RoutePoint,RoutePoint,IntermediatePoint[])




� RouteSegment.getAltNames(int) � As of Version 3.0, use RouteSegment.getAltNames()

� RouteStreet.getCompassString(RoutingPreferences) � As of Version 3.0, use RouteStreet.getCompassString() instead.

� RoutingPreferences.getDirectionBreakTurnAngle() � As of Version 3.0, use DirectionsPreferences.getDirectionBreakTurnAngle()

� MultiPointResult.getDirections(int) � As of Version 2.5, use MultiPointResult.getDirections() for each RouteSection instead.

� RouteSection.getDirectionsList() � As of Version 2.5, use RouteResult.getStreetDirections() instead. Note: getStreetDirections() does not return route summary in the first array element.

� MultiPointResult.getDirectionsList() � As of Version 2.5, use MultiPointResult.getStreetDirections() instead. Note: getStreetDirections() does not return route summary in the first array element.

� RouteResult.getDirectionsList() � As of Version 2.5, use RouteResult.getStreetDirections() instead. Note: RouteResult.getStreetDirections() does not return route summary in the first array element.

� MultiPointResult.getDirectionsList(int) � As of Version 2.5, use MultiPointResult.getStreetDirections() for each RouteSection instead. Note: getStreetDirections() does not return route summary in the first array element.

� RoutingPreferences.getDirectionsString(String) � As of Version 3.0, this will be ignored.

� RoutingPreferences.getDirectionsStyle() � As of Version 3.0, use DirectionsPreferences.getDirectionsStyle()

� RouteSegment.getDistance() � As of Version 2.5, use RouteSegment.getSegmentDistance() instead.

� RouteStreet.getDistance() � As of Version 2.5, use RouteStreet.getStreetDistance() instead.

� RouteSection.getDistances() � As of Version 2.5, use RouteSection.getStreetDistances() instead.

� MultiPointResult.getDistances() � As of Version 2.5, use MultiPointResult.getStreetDistances() instead.

� RouteResult.getDistances() � As of Version 2.5, use RouteResult.getStreetDistances() instead.

� MultiPointResult.getDistances(int) � As of Version 2.5, use RouteSection.getStreetDistances() for each RouteSection instead.

� RouteStreet.getDistanceString(RoutingPreferences) � As of Version 3.0, use UnitFormat.format(Distance) instead.

� RoutingPreferences.getExclude() � As of Version 3.0, use RoutingPreferences.getUpdates()

� MatrixRoutePreferences.getExclude() � As of Version 3.0, use MatrixRoutePreferences.getUpdates()

� RoutingPreferences.getExcludedPoints() � As of Version 3.0, use RoutingPreferences.getUpdates()

� MatrixRoutePreferences.getExcludedPoints() � As of Version 3.0, use MatrixRoutePreferences.getUpdates()

� RoutingPreferences.getExcludedSegmentIds() � As of Version 3.0, use RoutingPreferences.getUpdates()

� MatrixRoutePreferences.getExcludedSegmentIds() � As of Version 3.0, use MatrixRoutePreferences.getUpdates()

� RoutingPreferences.getFindShortestDistance() � As of Version 2.5, use RoutingPreferences.getOptimizeBy()




� MatrixRoutePreferences.getFindShortestDistance() � As of Version 2.5, use MatrixRoutePreferences.getOptimizeBy()

� RoutingPreferences.getFocus() � As of Version 3.0, use DirectionsPreferences.getFocus()

� RoutingPreferences.getInclude() � As of Version 3.0, use RoutingPreferences.getIncludedPoints().

� RoutingPreferences.getIncludedSegmentIds() � As of Version 3.0, this returns an empty array.

� MultiPointResult.getIntermediateDistances() � As of Version 2.5, use MultiPointResult.getRouteSectionDistances() instead.

� MultiPointResult.getIntermediatePoint(int) � As of Version 2.5, use MultiPointResult.getIntermediatePoints() instead.

� MultiPointResult.getIntermediatePointCount() � As of Version 2.5, use MultiPointResult.getIntermediatePoints().length instead.

� MultiPointResult.getIntermediateTimes() � As of Version 2.5, use MultiPointResult.getRouteSectionTimes() instead.

� MultiPointResult.getIntersections(int) � As of Version 2.5, use MultiPointResult.getRouteSections() followed by RouteSection.getIntersections() instead.

� MultiPointPreferences.getMajorRoadsOnly() � As of version 2.5, this method is deprecated and always returns false.

� RoutingAdminClient.getMaxThreadsCount() � As of Version 3.0. � RoutingAdminClient.getMaxThreadSeconds() � As of Version 3.0. � RoutingAdminClient.getMeanThreadSeconds() � As of Version 3.0. � DataNotAvailableException.getMessage(ResourceBundle) � As of Version 3.0, use

DataNotAvailableException.getMessage() � RouteSegment.getPoint(int) � As of Version 2.5, use RouteSegment.getRoutePoints()

instead. � RouteSection.getPointCount() � As of Version 2.5, use

RouteSection.getRoutePoints().length instead. � MultiPointResult.getPointCount() � As of Version 2.5, use

MultiPointResult.getRoutePoints().length instead. � RouteSegment.getPointCount() � As of Version 2.5, use

RouteSegment.getRoutePoints().length instead. � RouteResult.getPointCount() � As of Version 2.5, use

RouteResult.getRoutePoints().length instead. � RouteStreet.getPointCount() � As of Version 2.5, use RouteStreet.getPoints().length

instead. � MultiPointResult.getPointCount(int) � As of Version 2.5, use

MultiPointResult.getRouteSections() followed by RouteSection.getRoutePoints() instead.

� RouteSection.getPoints() � As of Version 2.5, use RouteSection.getRoutePoints() instead.

� MultiPointResult.getPoints() � As of Version 2.5, use MultiPointResult.getRoutePoints() instead.

� RouteResult.getPoints() � As of Version 2.5, use RouteResult.getRoutePoints() instead.

� RouteStreet.getPoints() � As of Version 2.5, use RouteStreet.getRoutePoints() instead. � MultiPointResult.getPoints(int) � As of Version 2.5, use

MultiPointResult.getRouteSections() followed by RouteSection.getRoutePoints() instead.




� RoutingPreferences.getPrimaryNameOnly() � As of Version 3.0, use DirectionsPreferences.getShowPrimaryNameOnly()

� RoutingPreferences.getReturnDirections() � As of Version 3.0, use DirectionsPreferences.getReturnDirections()

� RoutingPreferences.getRoadTypeOverriddenSegmentIds() � As of Version 3.0, use RoutingPreferences.addUpdate(TransientUpdate)

� MatrixRoutePreferences.getRoadTypeOverriddenSegmentIds() � As of Version 3.0, use MatrixRoutePreferences.addUpdate(TransientUpdate)

� RoutingPreferences.getRoadTypeOverrideValue(String) � As of Version 3.0, use RoutingPreferences.addUpdate(TransientUpdate)

� MatrixRoutePreferences.getRoadTypeOverrideValue(String) � As of Version 3.0, use MatrixRoutePreferences.addUpdate(TransientUpdate)

� RouteSection.getRouteDistance() � As of Version 2.5, use RouteSection.getDistance() instead.

� RoutingResult.getRouteDistance() � As of Version 2.5, use RoutingResult.getDistance() instead.

� RouteSection.getRouteDistanceString() � As of Version 2.5, use RouteSection.getDirectionsSummaryString() instead.

� MultiPointResult.getRouteSection() � As of Version 2.5, use MultiPointResult.getRouteSections() instead.

� MultiPointResult.getRouteSection(int) � As of Version 2.5, use MultiPointResult.getRouteSections() instead.

� MultiPointResult.getRouteSectionCount() � As of Version 2.5, use MultiPointResult.getRouteSections() instead.

� RouteSection.getRouteStreet(int) � As of Version 2.5, use RouteSection.getRouteStreets() instead.

� RouteResult.getRouteStreet(int) � As of Version 2.5, use RouteResult.getRouteStreets() instead.

� RouteSection.getRouteTime() � As of Version 2.5, use RouteSection.getTime() instead.

� RoutingResult.getRouteTime() � As of Version 2.5, use RoutingResult.getTime() instead.

� RouteSection.getRouteTimeString() � As of Version 2.5, use RouteSection.getDirectionsSummaryString() instead.

� RoutingResult.getRouteTimeString() � As of Version 2.5, use RoutingResult.getDirectionsSummaryString() instead.

� RoutingAdminClient.getRoutingCount() � As of Version 3.0. � RoutingAdminClient.getRoutingPreferences() � As of Version 3.0. � RouteStreet.getSegment(int) � As of Version 2.5, use

RouteStreet.getRouteSegments() instead. � RouteSection.getSegmentCount() � As of Version 2.5, use

RouteSection.getRouteStreets() followed by RouteStreet.getRouteSegments() instead. � RouteResult.getSegmentCount() � As of Version 2.5, use

RouteResult.getRouteStreets() followed by RouteStreet.getRouteSegments() instead. � RouteStreet.getSegmentCount() � As of Version 2.5, use

RouteStreet.getRouteSegments().length instead. � RoutingAdminClient.getServletInformation() � As of Version 3.0. � RoutingAdminClient.getServletStartDate() � As of Version 3.0. � RouteSegment.getSpeed() � As of Version 2.5, use

RouteSegment.getSegmentVelocity() instead.




� RoutingPreferences.getSpeedOverriddenPoints() � As of Version 3.0, use RoutingPreferences.addUpdate(TransientUpdate)

� MatrixRoutePreferences.getSpeedOverriddenPoints() � As of Version 3.0, use MatrixRoutePreferences.addUpdate(TransientUpdate)

� RoutingPreferences.getSpeedOverriddenRoadTypes() � As of Version 3.0, use RoutingPreferences.addUpdate(TransientUpdate)

� MatrixRoutePreferences.getSpeedOverriddenRoadTypes() � As of Version 3.0, use MatrixRoutePreferences.addUpdate(TransientUpdate)

� RoutingPreferences.getSpeedOverriddenSegmentIds() � As of Version 3.0, use RoutingPreferences.addUpdate(TransientUpdate)

� MatrixRoutePreferences.getSpeedOverriddenSegmentIds() � As of Version 3.0, use MatrixRoutePreferences.addUpdate(TransientUpdate)

� RoutingPreferences.getSpeedOverrideValue(RoadType) � As of Version 3.0, use RoutingPreferences.addUpdate(TransientUpdate)

� MatrixRoutePreferences.getSpeedOverrideValue(RoadType) � As of Version 3.0, use MatrixRoutePreferences.addUpdate(TransientUpdate)

� RoutingPreferences.getSpeedOverrideValue(RoutePoint) � As of Version 3.0, use RoutingPreferences.addUpdate(TransientUpdate)

� MatrixRoutePreferences.getSpeedOverrideValue(RoutePoint) � As of Version 3.0, use MatrixRoutePreferences.addUpdate(TransientUpdate)

� RoutingPreferences.getSpeedOverrideValue(String) � As of Version 3.0, use RoutingPreferences.addUpdate(TransientUpdate)

� MatrixRoutePreferences.getSpeedOverrideValue(String) � As of Version 3.0, use MatrixRoutePreferences.addUpdate(TransientUpdate)

� MultiPointPreferences.getStopThreshold() � As of version 3.0, this method continues to have the same functionality, but will be removed in the future.

� RouteSection.getStreetCount() � As of Version 2.5, use RouteSection.getRouteStreets().length instead.

� MultiPointResult.getStreetCount() � As of Version 2.5, use MultiPointResult.getRouteStreets() to get the streets.

� RouteResult.getStreetCount() � As of Version 2.5, use RouteResult.getRouteStreets() to get the streets.

� MultiPointResult.getStreetCount(int) � As of Version 2.5, use MultiPointResult.getRouteSections() followed by RouteSection.getRouteStreets().length instead.

� RouteSegment.getTime() � As of Version 2.5, use RouteSegment.getSegmentTime() instead.

� RouteStreet.getTime() � As of Version 2.5, use RouteStreet.getStreetTime() instead. � RoutingAdminClient.getTimeoutCount() � As of Version 3.0. � RouteSection.getTimes() � As of Version 2.5, use RouteSection.getStreetTimes()

instead. � MultiPointResult.getTimes() � As of Version 2.5, use MultiPointResult.getStreetTimes()

instead. � RouteResult.getTimes() � As of Version 2.5, use RouteResult.getStreetTimes()

instead. � MultiPointResult.getTimes(int) � As of Version 2.5, use

MultiPointResult.getStreetTimes() for each RouteSection instead. � RouteStreet.getTimeString(RoutingPreferences) � As of Version 3.0, use

UnitFormat.format(Time) instead. � RouteSegment.getTurnAngle() � As of Version 2.5, use

RouteSegment.getSegmentTurnAngle() instead. � LinearUnit.getWellKnownText()




� AngularUnit.getWellKnownText() � RoutingPreferences.setDirectionBreakTurnAngle(int) � As of Version 3.0, use

DirectionsPreferences.setDirectionBreakTurnAngle(Angle) � RoutingPreferences.setDirectionsString(String, String) � As of Version 3.0, this will be

ignored. � RoutingPreferences.setDirectionsStyle(short) � As of Version 3.0, use

DirectionsPreferences.setDirectionsStyle(byte) � RoutingPreferences.setDistanceUnit(String) � As of Version 2.5, use

RoutingPreferences.setDistanceUnit(LinearUnit) � RoutingPreferences.setFindShortestDistance(boolean) � As of Version 2.5, use

RoutingPreferences.setOptimizeBy(short) � MatrixRoutePreferences.setFindShortestDistance(boolean) � As of Version 2.5, use

MatrixRoutePreferences.setOptimizeBy(short) � RoutingPreferences.setFocus(short) � As of Version 3.0, use

DirectionsPreferences.setFocus(byte) � MultiPointPreferences.setMajorRoadsOnly(boolean) � As of version 2.5, this method is

deprecated and will be ignored. � RoutingPreferences.setPrimaryNameOnly(boolean) � As of Version 3.0, use

DirectionsPreferences.setShowPrimaryNameOnly(boolean) � RoutingPreferences.setReturnDirections(boolean) � As of Version 3.0, use

DirectionsPreferences.setReturnDirections(boolean) � RoutingPreferences.setReturnSegmentGeometry(String) � As of Version 2.5, use

RoutingPreferences.setReturnSegmentGeometry(short) � RoutingAdminClient.setRoutingPreferences(RoutingPreferences) � As of Version 3.0. � MultiPointPreferences.setStopThreshold(double) � As of version 3.0, this method

continues to have the same functionality, but will be removed in the future. � RoutingPreferences.setTimeUnit(String) � As of Version 2.5, use

RoutingPreferences.setTimeUnit(TimeUnit) � RoutingDataPreferences.setTimeUnit(String) � As of Version 2.5, use

RoutingDataPreferences.setTimeUnit(TimeUnit)




Deprecated Constructors

The following is a complete list of deprecated constructors:

� AngularUnit(String, double) � Use 3 parameter version instead. � LinearUnit(String, double) � Use 3 parameter version instead. � MultiPointClient(String, boolean) � As of Version 3.0, use log4j.properties to switch

request tracing on. � MultiPointClient(URL, boolean) � As of Version 3.0, use log4j.properties to switch

request tracing on. � RoutePoint() � As of Version 2.5, use RoutePoint.RoutePoint(double,double,long) or

RoutePoint.RoutePoint(RoutePoint). � RoutingAdminClient(String) � As of Version 3.0. � RoutingAdminClient(URL) � As of Version 3.0. � RoutingClient(String, boolean) � As of Version 3.0, use log4j.properties to switch

request tracing on. � RoutingClient(URL, boolean) � As of Version 3.0, use log4j.properties to switch

request tracing on. � RoutingDataClient(String, boolean) � As of Version 3.0, use log4j.properties to switch

request tracing on. � RoutingDataClient(URL, boolean) � As of Version 3.0, use log4j.properties to switch

request tracing on.



D
Glossary
Ambient speedThe speed to travel a certain distance off identified roads to find the boundary when determining the isochrone. Roads not identified in the network can be driveways or access roads, among others. The ambient speed can be set for all road types or overridden for specific road types. For example, it may be set to 0 for major highways.

Banding style The types of multiple isochrone or distance bands that can be displayed. Multiple isochrone or isodistance bands may be requested by specifying multiple cost factors, such as asking for the isochrone 5 minutes away and 15 minutes away from the same starting point. These end up as concentric bands, more or less. The requestor may choose to show both complete sets of data (encompassing style, which shows everything) or just the band between the two (donut style), everything between 5 and 15 minutes away.

CostThe amount of time or distance to use in calculating the isos. For example, an iso that displays polygons that represent the distance of 10 miles from the starting point and 20 miles from the starting point has costs of 10 and 20.

Data areasAreas of the XML communication that are not expected to be sent directly to the users. This would currently include everything except directions.

Delta update A percentage change of the speed value, as opposed to an explicit value that represents the speed. For instance, increasing the speed by 40% or decreasing it by 30 miles per hour is a delta update. Setting the speed to 20 miles per hour is not a delta update.

Direction areasThe StreetDirections and DirectionsSummary elements of the XML.

Directions generatorAny class or set of classes that implements the DirectionsGenerator interface for creating directions. You may choose to create one or more generators to provide custom directions. The generators are configured with Routing J Server at startup and chosen based on name and locale.

Developer Guide Appendix D: Glossary

Directions localeThe locale in which the driving directions are written. In the Java API, it is specified through the user locale in the routing preferences. In XML, it is specified by the user locale XML element. If the user locale element is missing, the server falls back to using data locale for directions. If the data locale element is missing too, the server falls back to the request locale specified on the request envelope.

Directions styleA grouping of strings used to generate directions.

Directions templateStrings in DirectionStrings.properties that are used in creating the strings for directions. Routing J Server reads these strings from the DirectionStrings.properties file and replaces the first occurrence of the {0}, {4}, {5}, and {1} tokens with the turn angle, distance, time, and street name strings respectively.

End pointThe first or last point in a RouteSegment.

Focus on endRoute that directs the user from the last major highway in the route (including that highway) to the destination.

Focus on startRoute that directs the user from their origin to (and including) the first major highway.

HoleAreas within the larger boundary that cannot be reached within the desired time or distance, based on the road network. These pockets of territory are often neighborhoods of local roads that are cumbersome to traverse.

InternationalizationFor this product, internationalization means generating a response that is specific to a locale. This includes providing information in formats commonly used in that locale (such as date, time, and currency formats) as well as in the language of that locale such as driving directions in the German language.

IsochroneA polygon or set of points representing an area that can be traversed in a network from a starting point in a given amount of time.

IsodistanceA perimeter or set or points representing the area that is within a given physical distance from the starting point.

Island Small areas outside the main boundary that can be reached within the desired time or distance. These areas are frequently located off exit ramps of major highways.




LocaleA locale is the specification of a language and country for internationalized information. The XML specification for locale is a string consisting of the two-digit language code, followed by an underscore and a two-digit country code, for example "en_US". The proper two-digit language codes can be found at http://www.unicode.org/unicode/onlinedat/languages.html. The proper two-digit country codes can be found at http://www.unicode.org/unicode/onlinedat/countries.html.

Local time-of-dayThe time-of-day relative to the route points.

Local time zoneThe time zone relative to the route points.

Major roadA main road or highway. Typically a major road is in the RAM maps that are always loaded on startup.

Matrix route request A request that allows you to calculate a matrix of routes, where element i,j of the matrix is a route from start point number i to destination number j.

Maximum Off Road Distance The maximum amount of distance to come off the road network when using either ambient speed or the propagation factor.

Minor road A local road. Typically a minor road is in a map file that is loaded on an as-needed basis.

NodeThe point of intersection where two paths cross. A node can also be a point along a path.

Percentage A positive, integer value representing a percentage change from the original value. For example, if the original value is 100 and you want to increase it by 50, the value for percentage would be 50.

Persistent update An update in which the speed changes and the change remains with the server even after the server has been restarted.

Point A location defined by latitude, longitude, and level coordinates.



http://www.unicode.org/unicode/onlinedat/languages.html

http://www.unicode.org/unicode/onlinedat/countries.html

http://www.unicode.org/unicode/onlinedat/countries.html


Propagation factor A percentage of the cost used to calculate the distance between the starting point and the isodistance. Propagation factor serves the same purpose for isodistances as ambient speed does for isochrones. For instance, if you are at a point with 5 minutes left on an isochrone, boundary points would be put at a distance based on the ambient speed and the time left. So, if the ambient speed in this case was 15 miles per hour, boundary points would be put at a distance of 1.25 miles. Similarly, if you were at a point with 5 miles left to go on an isodistance, boundary points would be put at a distance based on the propagation factor and the time left. So, if the propagation factor was 0.16, boundary points would be put at a distance of 0.8 miles.

Request localeThe locale attribute on the request envelope. This attribute indicates the locale that the request is formatted in. All numbers will be read in that locale.

Response localeThe locale the response is written in. This locale indicates what the "data areas" of the XML are formatted in. The response locale is determined either by the original request locale or an option response locale specification in the response constraints.

Segment A part of a street.

Segment ID Identifier for a RouteSegment that can be obtained using RouteSegment.getId()

Simplification factor Indicates what percentage of the original points should be returned or that the resulting polygon should be based on. The polygon or set of points may contain many, many points. The simplification factor is a decimal number between 0 and 1.0 (inclusive). Lower numbers mean lower storage and lower transmission times.

Shape point A point in a RouteSegment that defines a curve in the road.

Supported LocaleA locale that is supported by the server. It must fit two criteria.

� A number format appropriate to the supplied locale must exist on the server. The number format is installed with the VM, not our product.

� A direction string property file must exist on the server, and client, that matches the locale on at least language. So if fr_CA is requested and only fr is available that will be returned. However, if fr_CA is requested and even fr is not available then an error will be returned.

Threshold value A percentage identifying the acceptable amount of difference between the absolute best path and the returned path. As the value decreases, the likelihood of finding the absolute shortest path increases. As the value increases, the response time speeds up.




Time intervalA duration of time consisting of a numeric value and time unit, e.g. 3 hours.

Time-of-day An absolute time consisting of the 24 hour clock time, date and time zone information.

Time intervalA duration of time consisting of a numeric value and time unit, e.g. 3 hours.

Time zoneA time zone is defined as an area through out which time-of-day is the same.

Time zone specificationThe data that identifies a time zone: UTC offset, time zone name and abbreviation.

Transient UpdateAn update made on with a request that only applies to the particular request. This may be an exclude or a speed change for a road type, segment, or point.

TransitionDefinition of the interaction between two streets in a route. Some examples of transitions include: going from a street to another street, going from a street to a highway, and going from a street to a roundabout.

Turn angle Specifies how much a RouteSegment turns relative to the previous RouteSegment in a route. A negative turn angle implies a right turn. A positive turn angle is a left turn.

User localeA response constraint that indicates what XML user areas are formatted/translated. User areas are currently limited to directions, but may be expanded in the future to include other areas that are expected to be directly displayed to the user.

UTC offsetThe total offset from Coordinated Universal Time considering both GMT offset and DST offset. See ISO 8601 standard for the complete definition.

Waypoints An intermediate point between any two other points.



Index

AAmbient speed 69API deprecations

classes 128constructors 135fields 128methods 129

BBacwards compatibility 95Banding suggestions 73

CClassic routing sample 103Classpaths for samples 115Client applications

MatrixRouteClient 38�40MultiPointClient 37�38RoutingClient 35�36

Code samplesIsochrones/Isodistance 73obtaining segment data 76route request XML 100time zones 65time-based routing 62

Common elements 86�90Costs 38, 69

DData

modifying 77returning with preferences 58segment information 76

Data installationfull 7partial 7

Datasets 31Delta updates 78Deployment options 20Deprecations

classes 128constructors 135fields 128methods 129

Diagnostic samplesRoutingClientGUI 99TestXML 100

Directionscustom 46default 42DirectionsPreferences 43

generators 46roundabout support 55token definitions 53

Directions generator sample 115Directions Strings

routing directions 51turn angle 52

Documentation resources 4, 32Donut style banding 73DTDs 81

HHardware requirements 4HTTP connections 32HTTP headers 82

IInclude/exclude sample 111Individual request modifications 60Information resources 4Initialization parameters

RoutingServlet 125Installation

console 17full data 7no graphics card 17partial data 7server 8�17testing 19

Installed componentsjar files 19samples 20

Internationalization 66Isochrone sample 106IsoClient

ambient speed 69donut style banding 73isochrones/isodistance 73isoDefinition 69isoPreferences 69propogation factor 70

IsoDefinition 69IsoPreferences 69

JJar files 19

LLocalization of samples 116logging 27

Developer Guide Index

MManual installation 17MatrixRouteClient applications 38�40Modifying data 77MultiPoint sample 109MultiPointClient applications 37�38MultiPointPreferences 67

NNew features 2

PPerformance

MatrixRoute tuning 40server tuning 5

Persistent updatesmodifying data 77

Point and Click sample 113Preferences

include 60internationalization 66MultiPoint 67per request updates 60returning data 58time zones 63time-based routing 62travel 61

Propagation factor 70

RRequirements

hardware 4software 5Sun Solaris 5Windows 5

Road typespreferences 61supported 96

Route costs 38Route interface 37Routing requests 85Routing responses 85RoutingClient applications 35�36RoutingClientGUI 99RoutingPreferences

include 60internationalization 66per request updates 60returning data 58time zones 63time-based routing 62travel 61

RoutingServlet initialization parameters 125

SSample applications

Include/exclude 111Point and Click 113

SamplesClassic routing servlet 103classpaths 115

Directions generator 115Include/exclude 111Isochrone servlet 106localization 116MulitPointservlet 109Point and Click 113RoutingClientGUI 99TestXML 100

Server installation 8�17Servlet samples

Classic routing 103display data 102Isochrone 106MultiPoint 109setup 102

Software requirements 5Sun Solaris requirements 5Support resources 32System logging 27

TTestXML sample 100Time zones

end time 64start time 64

Time-based routes 62Transient Updates

modifying data 77Travel preferences 61Troubleshooting

connection testing 121Persistent updates 120server considerations 120Web server connections 121

Turn Angle Strings 52

UUpdates 77

WWarFile Generator utility 20�27Web server environments 20Web.xml

sample file 122Windows requirements 5

XXML

backwards compatibility 95common elements 86�90DTDs 81iso request and response 92matrix request and response 94multi request and response 90naming and usage 84persistent updates request and response 93route request and response 90routing requests 85routing responses 85



v3.0 Developer Guide - Pitney Bowes...Ł API documentation for the MapInfo Routing J Server is...

Documents

Transcript of v3.0 Developer Guide - Pitney Bowes...Ł API documentation for the MapInfo Routing J Server is...