Routing J Server - Pitney Bowes...Routing J Server 4.0 is fully backward compatible with Routing J...

Routing J Server®

v4.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 Pitney Bowes Software Inc., One Global View, Troy, New York 12180-8399.© 2011 Pitney Bowes Software Inc. All rights reserved. Pitney Bowes Business Insight, MapInfo, Group 1 Software and Routing J Server are trademarks of Pitney Bowes Business Insight, a division of Pitney Bowes Software and/or its affiliates. Americas:Phone: (518) 285-6000Fax: (518) 285-6070Sales: (800) 327-8627Government Sales: (800) 619-2333Technical Support: (518) 285-7283Technical Support Fax: (518) 285-6080www.pbinsight.comUK and EMEA:Phone: 44 1753 848200Fax: 44 1753 621140 Technical Support: 44 1753 848229 www.pbinsight.co.ukAsia Pacific:Phone: 61. 2.9437.6255Fax: 61.2.9439. 1773Technical Support: 1800 648 899www.pbinsight.com.auContact information for all Pitney Bowes Software Inc. offices is located at:: http://www.pbinsight.com/contactusProducts 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.February 2011

http://www.pbinsight.com

http://www.pbinsight.co.uk

http://www.pbinsight.com.au

http://www.pbinsight.com/contactus

Table of Contents

Chapter 1: Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11New in Version 4.0. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12

Commercial Vehicle Restrictions (CVR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12Migrating Routing J Server Applications to 4.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12

Incalculable Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12Client Side Directions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12Include by Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12Time Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12Recompiling Code Developed With Previous Versions . . . . . . . . . . . . . . . . . . . . . . . . .13

MapInfo Routing J Server Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13System Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

Hardware Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

Supported Platforms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14Performance Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14

Chapter 2: Installation and Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Installation Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16Installing Routing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

Data Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16Installing the MapInfo Routing J Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16Installing on UNIX without a Graphics Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22

X-windows Installation Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22Silent or Console Installation Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23

Testing the Routing J Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24Installed Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25

Jar Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25Uninstalling the MapInfo Routing J Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26Deployment Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26

Developer Guide iii

Table of Contents

Routing J Server in Other Web Server Environments . . . . . . . . . . . . . . . . . . . . . . . . . .26Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

Chapter 3: Understanding Routing Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Planning Your Routing Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30Functionality Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30Client Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30

RoutingClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30MultiPointClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30MatrixRouteClient. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31IsoClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31RoutingDataClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31

Preference Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31Routing Data Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31

Datasets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31Connection via HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32Reference Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32MapInfo Support and Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32

Chapter 4: Working with Routing Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . 33Routing Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34Route Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34Routing J Server Routing Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35Using the RoutingClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

Create a RoutingClient Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35Create RoutePoint Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36Create a VehicleAttributes Instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36Find the Route . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36Obtain the Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36Sample Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37RoutingClient Flexibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37

Using the MultiPointClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37Generating a MultiPoint Route . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37

Using the MatrixRouteClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38Creating a Matrix Route . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38Successful Matrix Route Request Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39Matrix Route Fault Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40Performance Information for Matrix Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40

Commercial Vehicle Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40Restricted and Preferred Segments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40Vehicle and Segment Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41How Routing J Server Uses VehicleAttributes and Commercial Vehicle Restrictions . .41

Developer Guide iv

Table of Contents

Chapter 5: Modifying Routing Directions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Routing Directions Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44Requesting Default Directions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44DirectionsPreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45

Directions Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45Focus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45DirectionsTurnBreakAngle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45ReturnDirections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46ShowTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46ShowDistance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46ShowPrimaryNamesOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46DirectionsGeneratorName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46

Using DirectionsPreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47Custom Directions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48Using Directions Generators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48

How to Create a Directions Generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49Creating a DirectionsGenerator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49

Extension of an Existing Generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49Implementation of the DirectionsGenerator Interface . . . . . . . . . . . . . . . . . . . . . . . . . .50

Directions Generators and DirectionsPreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . .51Configuring the Server for Generator Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52Using the Generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52

User Specified Generator (By Name) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52By Locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52By Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53Default Generator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53

Routing Directions Strings Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53When to Edit the Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53How the Direction Strings files Are Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53

Turn Angle Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55Routing Directions Token Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56Creating Custom Directions on the Client Side . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57Additional Routing Directions Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58

Removing Parentheses from Directions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58Roundabout Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58Directions Strings that Contain Apostrophes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58

Chapter 6: Customizing Routing with Preferences . . . . . . . . . . . . . . . . . . . . . . . 59RoutingPreferences Class Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60Algorithm Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60

optimizeBy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60

Developer Guide v

Table of Contents

Returning Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60returnActualPreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60optimizeBy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60returnAllPoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61returnEndPoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61returnSegmentData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61returnSegmentGeometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61returnSegmentGeometryString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61

Using Per Request Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62addUpdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62

Working with Includes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62Using Include . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62Include . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63

Setting the Timeout Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63Setting Travel Preferences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63

Using a Travel Preference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64Working with Time-based Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64

Usage Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64Using Time Zones in Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65

Start Time. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66End Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66Specifying the Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66Obtaining the Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67Time zones on streets and sections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69

Routing J Server Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69Setting Up a Locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69User Locale Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70International Java Virtual Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70

MultiPointPreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70OptimizeIntermediatePoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70

Chapter 7: Working with the IsoClient. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71IsoDefinition Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72Using IsoPreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72

Default ambient speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72Ambient speed overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72Default propagation factor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73Propagation factor overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73Major roads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73Maximum off-road distance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74Holes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74Islands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74

Developer Guide vi

Table of Contents

Simplification factor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75Result type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75Banding style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75

Expected Isochrone/Isodistance Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76Isos near the water. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76

Donut Style Banding Suggestions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76Obtaining Isochrones/Isodistances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77

Chapter 8: Using the RoutingDataClient and Data Updates . . . . . . . . . . . . . . . . 79Accessing Routing Data Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80

Obtaining Segment Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80Usage Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80

Modifying Data with Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81Persistent Updates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81Transient Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81Update Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81Update Delta . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81

Chapter 9: MapInfo Enterprise XML Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Working with the XML API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84

When to use the XML API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84Required Skill Sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84Requests/Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84Tips for Using the XML API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85

Document Type Definitions (DTD) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85HTTP Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87XML Elements Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88

XML Naming and Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88OGC Elements Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88Common Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89Routing Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89

MI_XML_Protocol_RoutingRequestAndResponseEnvelope_4.0.dtd. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90MI_XML_Protocol_RoutingCommonElements_4_0.dtd . . . . . . . . . . . . . . . . . . . . . . . .91

Constraint Elements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91Other Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93

MI_XML_Protocol_RoutingRouteRequestAndResponse_4_0.dtd . . . . . . . . . . . . . . . .96MI_XML_Protocol_RoutingMultiRequestAndResponse_4_0.dtd . . . . . . . . . . . . . . . . .97MI_XML_Protocol_RoutingIsoRequestAndResponse_4_0.dtd . . . . . . . . . . . . . . . . .100MI_XML_Protocol_RoutingPersistentUpdatesRequestAndResponse_4_0.dtd. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102MI_XML_Protocol_RoutingMatrixRequestAndResponse_4_0.dtd . . . . . . . . . . . . . . .103

Developer Guide vii

Table of Contents

MI_XML_Protocol_RoutingDataRequestAndResponse_2_5.dtd . . . . . . . . . . . . . . . .104XML Backward Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104Supported Road Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105

Chapter 10: Working with Routing Samples. . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Diagnostic Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108RoutingClientGUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108TestXML Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109

Route Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109Persistent Updates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111

Directions Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111Additional Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111

Classpaths for Routing Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112RoutingAdmin and RoutingClientGUI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112TestXML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112

Localization of Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113RoutingClientGui . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113

Chapter 11: Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Testing the Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116

Issue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116Resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116

Web Server Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116Issue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116Resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116Issue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116Resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116

Other Issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117Issue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117Resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117Issue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117Resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117

Developer Guide viii

Table of Contents

Appendix A: Web.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Sample web.xml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120

Appendix B: Initialization Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123RoutingServlet Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124

Appendix C: Deprecated API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Deprecated Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128Deprecated Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128Deprecated Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128Deprecated Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134

Appendix D: Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Appendix E: Open Source Attributions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

Developer Guide ix

Table of Contents

x Routing J Server v3.4

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 4.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12MapInfo Routing J Server Documentation. . . . . . . . . . . . . . . . . . .13System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13Supported Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14Performance Tuning. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14

New in Version 4.0

New in Version 4.0

Commercial Vehicle Restrictions (CVR)Version 4.0 introduces the concept of Commercial Vehicle Restrictions (CVR). Additional attribution is now available on a per-segment basis such that when given attributes about a vehicle, Routing J Server will not route a vehicle over a restricted segment.

For more information see Commercial Vehicle Restrictions on page 40.

Migrating Routing J Server Applications to 4.0When upgrading an existing application to 4.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 48.

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.

12 Routing J Server v 4.0

Chapter 1: Introduction

Recompiling Code Developed With Previous VersionsRouting J Server 4.0 is fully backward compatible with Routing J Server 3.x.

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.

MapInfo Routing J Server Documentation Use the following documentation pieces to assist you with developing custom routing applications.

• MapInfo Routing J Server Developer 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-4.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 disks, go to http://www.pbinsight.com/support/product-documentation/details/routing-j-server.

• A readme file is also included at the root level of your product disk. 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 disk.

System Requirements

Hardware RequirementsThe minimum system requirements are a 600 MHz CPU with 512 MB memory, 9 GB hard drive, and Pentium III or equivalent. 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 Requirements vary based on the size of data that you use.

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.5 (included). • JDOM beta9. Installed with the full installation and the server installation when performing a

custom installation.

Developer Guide 13

http://www.pbinsight.com/support/product-documentation/details/routing-j-server

http://www.pbinsight.com/support/product-documentation/details/routing-j-server

Supported Platforms

• Xerces 2.2.1. Installed with the full installation and the server 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. Jakarta Tomcat 5.5.9 is installed when you choose the Full installation option.

Supported Platforms Routing J Server supports the following platforms:

• Windows Server 2008• Windows Vista • Windows 7 (32 bit and 64 bit)• Windows Server 2003 • Windows XP Professional • Solaris 8 & 9 10 • Red Hat Linux 8 • HP-UX 11 • SUSE Linux 10 • Linux RedHat Advanced Server for x86 4, 5 • IBM AIX 5.3, 6.1 • HP-UX 11i V3

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.5. 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.5.

• 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/

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

In this chapter:

Installation Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16Installing Routing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16Installing the MapInfo Routing J Server. . . . . . . . . . . . . . . . . . . . .16Installing on UNIX without a Graphics Card . . . . . . . . . . . . . . . . .22Testing the Routing J Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24Installed Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25Uninstalling the MapInfo Routing J Server . . . . . . . . . . . . . . . . . .26Deployment Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26Routing J Server in Other Web Server Environments . . . . . . . . .26Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

Installation Overview

Installation OverviewFollow 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 DataRefer to the following sections for full or partial data installation instructions.

Data InstallationFor a full data installation copy the contents of the data disks and preserve the directory structure on the disks. The datasets cannot be copied into one directory; each dataset must be kept in its own directory. To enhance performance, we recommend installing data on a separate, stand-alone hard drive. Go to our website for a list of the contents and organization of the US data and Canada data disks.

Partial Data Instllation

For a partial data installation, review the data documentation to determine datasets you want to install. To install your routing data, copy the desired dataset(s) from the appropriate disks. For example, for the Northeast region of the United States, copy the NorthEast directory.

Installing the MapInfo Routing J ServerTo install the MapInfo Routing J Server:

1. Place the MapInfo Routing J Server software disk in your disk drive.2. Run install.htm from the disk root. Select the link for your platform: Windows, Solaris, Linux, or

HP-UX. Alternatively, for the appropriate platform:• WindowsAt the disk root, go to \InstData\Windows and run install.exe. • SolarisAt the disk root, go to /InstData/Solaris and run install.bin.• LinuxAt the disk root, go to /InstData/Linux and run install.bin.• HP-UXAt the disk root, go to /InstData/Solaris and run install.bin.


http://reference.mapinfo.com/software/routing_j_server/english/3_3/RoutingJServer_USData.pdf

http://reference.mapinfo.com/software/routing_j_server/english/3_3/RoutingJServer_CanData.pdf

http://reference.mapinfo.com/software/routing_j_server/english/3_3/RoutingJServer_CanData.pdf

Chapter 2: Installation and Setup

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 4.0 and click NEXT.

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

Developer Guide 17

Installing the MapInfo Routing J Server

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 5.5.9.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-4.0. On Solaris, Linux, and HP-UX, the default location is /opt/mapinfo/RoutingJServer-4.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.

Developer Guide 19

Installing the MapInfo Routing J Server

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.5 or higher. Click NEXT.

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

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

Developer Guide 21

Installing on UNIX without a Graphics Card

15. The Installing Routing J Server dialog launches.

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

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

Installing on UNIX without a Graphics CardWhile 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 16.

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-4.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-4.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:

Location Files Tags Replaced With

\Tomcat-Routing\webapps\routing40\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.

Developer Guide 23

Testing the Routing J Server

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-4.0/updates</param-value>

</init-param>

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



Installed ComponentsThe 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-io.jar - used for handling IO operations• 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.

Samples

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

Developer Guide 25

Uninstalling the MapInfo Routing J Server

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 4.0 or run the uninstall.exe from the directory <INSTALL_DIR>\Uninstall RoutingJServer-4.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-4.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 5.5.9 with the Routing J Server as part of the product installation.

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

Routing J Server in Other Web Server EnvironmentsAs part of the installation process, web archive (war) files are created and placed in the <INSTALL_DIR>\RoutingJServer-4.0\wars directory. The war files are:

• routing40.war – the main routing context• rjssamplesusa.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.



LoggingRouting 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/unusable 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 fulfilling the user's request. Program execution can continue.

Wrong request HTTP header.

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

A route or a multi-point route normal 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

Developer Guide 27

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

Logging


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 . . . . . . . . . . . . . . . . . . . . . . . .30Functionality Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30Client Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30Preference Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31Routing Data Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31Connection via HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32Reference Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32MapInfo Support and Resources . . . . . . . . . . . . . . . . . . . . . . . . . .32

Planning Your Routing Application

Planning Your Routing ApplicationAs 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 OverviewThe 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 OverviewThe 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 33.

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 33.


Chapter 3: Understanding Routing Basics

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 33.

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 71.

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 79.

Preference OverviewThe 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 59.

Routing Data OverviewThere 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 4.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 disk, 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:

Developer Guide 31

Connection via HTTP

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

d:\mapinfo\RJS40data\usa\NorthEast;d:\mapinfo\RJS40data\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/routing40/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 InformationThere are a number of places to obtain information while working on your routing application. For a complete listing of all Routing J Server product documentation, see the section, MapInfo Routing J Server Documentation on page 13.

If you are developing applications with the Java API, refer to the HTML documentation located in <Install_Dir>\RoutingJServer-4.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 ResourcesThe website at Pitney Bowes Business Insight provides a wealth of information and resources to help you with your Routing applications, including a Knowledgebase, consulting services, technical support and training.


http://www.pbinsight.com/products/location-intelligence/developer-tools/desktop-mobile-and-internet-offering/routing-j/

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

In this chapter:

Routing Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34Route Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34Using the RoutingClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35Using the MultiPointClient. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37Using the MatrixRouteClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38Commercial Vehicle Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . .40

Routing Overview

Routing OverviewThe 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 is 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, roundabout indicator and, beginning with version 4.0, Commercial Vehicle Restrictions.

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]; }


Chapter 4: Working with Routing Functionality

// 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();}

Routing J Server Routing ClientsRouting J Server consists of three routing clients. Each performs different types of routing:

• RoutingClient - for general purpose routing applications from point A to point B.• MultiPointClient - factors intermediate points into the route.• MatrixRouteClient - finds the shortest paths given pairs of start and end points and returns the

costs of each route.

Each client is discussed below.

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. Optionally create a RoutingPreferences object to specify user preferences. 3. Create RoutePoint objects for the start and destination of the route.

4. Optionally, create a VehicleAttributes1 instance, set its properties, and set it on the RoutingClient.5. Find the route.6. 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/routing40/servlet/routing");

RoutingPreferences preferences = new RoutingPreferences();

1. For an explanation of VehicleAttributes, see Commercial Vehicle Restrictions on page 40.

Developer Guide 35

Using the RoutingClient

client.setRoutingPreferences(preferences);

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);

Create a VehicleAttributes InstanceThis optional section of code incorporates vehicle attributes, such as the type, length, width, height, and weight of a vehicle.

VehicleAttributes vehicleAttributes = new VehicleAttributes();

vehicleAttributes.setVehicleType(VehicleType.ALL);

vehicleAttributes.setLength(new Distance(46, LinearUnit.foot));

// Length restriction of 45 feet exists on all trucks for one seg-ment in the path between the given source and destination points (which is a straightforward west movement). For trucks with length greter than 45 feet they have to take a longer route.

client.setVehicleAttributes(vehicleAttributes);

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 59.

Using the MultiPointClientMultiPoint 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. Optionally, create a VehicleAttributes1 instance, set its properties, and set it on the MultiPointClient.

4. 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.

1. For an explanation of VehicleAttributes, see Commercial Vehicle Restrictions on page 40.

Developer Guide 37

Using the MatrixRouteClient

5. 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 MatrixRouteClientUsing 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 unavailable constraints are include by point and include by time.

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. Sample code is provided below.

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. Optionally, create a VehicleAttributes1 instance, set its properties, and set it on the MatrixRouteRequest.

5. 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.

1. For an explanation of VehicleAttributes, see Commercial Vehicle Restrictions on page 40..



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.

Developer Guide 39

Commercial Vehicle Restrictions

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 Information for Matrix RoutesSimilar 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.

Commercial Vehicle RestrictionsVersion 4.0 introduces the concept of Commercial Vehicle Restrictions (CVR). Additional attribution is now available on a per-segment basis such that when given attributes about a vehicle, Routing J Server will not route a vehicle over a restricted segment. The restrictions and other CVR concepts are defined below.

Restricted and Preferred Segments

Hard Restriction

A segment has a Hard Restriction when a commercial vehicle is prohibited from traversing that segment due to local ordinance or a physical limit of the segment (for example, bridge weight).

Soft Restriction

A segment has a Soft Restriction when a commercial vehicle is allowed on the segment but only when it must (for example, last mile access, local delivery, etc.).

Preferred Segment

A segment can be Preferred for commercial vehicle access (e.g. interstate highways).



Vehicle and Segment Information

VehicleAttributes

The RoutingClient, MultiPointClient and MatrixClient classes each contain a property that holds an instance of a VehicleAttributes. When this property is set to non-null, Routing J Server will use the Commercial Vehicle Restrictions when calculating a route. The VehicleAttributes is composed of the following properties: vehicle type, length, width, height and weight.

Vehicle Type

Commercial vehicles are divided into different types ranging from short trailers to long triples. The Commercial Vehicle Restrictions attribution is organized on a per-vehicle type basis. This means it is entirely possible for a segment to be Preferred for one vehicle type and the same segment have a Hard Restriction for another type of vehicle. Because the segment attribution is organized on a per-vehicle type basis, the vehicle type is mandatory.

Vehicle and Segment Attribution

Vehicles and segments can have the following additional attribution: length, width, height or weight. These are optional on both the segment and vehicle (for example, a segment can have a weight restriction but not a height restriction).

How Routing J Server Uses VehicleAttributes and Commercial Vehicle Restrictions

Routing J Server is not a logistics engine. However, it can still adjust the cost of a route segment by factoring in VehicleAttributes and Commercial Vehicle Restrictions, if provided. The cost can go to infinity to indicate that the segment is non-traversable, or can go up slightly, go down slightly or remain the same. Here is how Routing J Server works:

If the request does not include an instance of the VehicleAttributes then Routing J Server behaves normally.

If the request does contains an instance of VehicleAttributes, then:

• If the segment contains a Hard Restriction, either from a local ordinance or physical limitation, then set the cost of the segment to infinity. This has the effect of removing the segment from the network.

• If the segment contains a preferred restriction, adjust the base cost of the segment downward. If the segment is restricted then adjust the base cost of the segment upward. This has the effect of allowing Routing J Server to choose a Preferred segment over Soft Restricted segment given the same road type.

Developer Guide 41

Commercial Vehicle Restrictions


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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44Requesting Default Directions . . . . . . . . . . . . . . . . . . . . . . . . . . . .44DirectionsPreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45Using DirectionsPreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47Custom Directions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48Using Directions Generators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48Creating a DirectionsGenerator . . . . . . . . . . . . . . . . . . . . . . . . . . .49Directions Generators and DirectionsPreferences . . . . . . . . . . . .51Configuring the Server for Generator Use. . . . . . . . . . . . . . . . . . .52Using the Generator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52Routing Directions Strings Files. . . . . . . . . . . . . . . . . . . . . . . . . . .53Turn Angle Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55Routing Directions Token Definitions . . . . . . . . . . . . . . . . . . . . . .56Creating Custom Directions on the Client Side . . . . . . . . . . . . . .57Additional Routing Directions Information . . . . . . . . . . . . . . . . . .58

Routing Directions Overview

Routing Directions OverviewRouting 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 DirectionsBy 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/routing40/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();}


Chapter 5: Modifying Routing Directions

DirectionsPreferencesDirectionsPreferences 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 4.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 48 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.

Developer Guide 45

DirectionsPreferences

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 4.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 4.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 DirectionsPreferencesTo 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.

Developer Guide 47

Custom Directions

// setDirectionsPreferences(dirPrefs) for a multipoint route// request.return dirPrefs;

}

Custom DirectionsThere 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 GeneratorsRouting J Server provides the ability for an advanced user to perform server-side customization of directions via a 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 DirectionsGeneratorWhen creating a DirectionsGenerator, you can use the extension of an existing generator or implement the DirectionsGenerator interface.

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") };

}

Developer Guide 49

Creating a DirectionsGenerator

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 that 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-4.0/examples-usa/direction directory.

Directions Generators and DirectionsPreferencesRegardless 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

Developer Guide 51

Configuring the Server for Generator Use

Configuring the Server for Generator UseThe 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 GeneratorRouting 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 FilesDirectionsStrings_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.

Developer Guide 53

Routing Directions Strings Files

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=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=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 right

Developer Guide 55

Routing Directions Token Definitions

ANGLE_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 DefinitionsThe following table lists the replacement paramter tokens for versions 2.0 and above. old to new conversions.

.

Version 2.0 and above token Definition

{0} turn angle

{1} street name

{2} toll road indicator

{3} compass direction

{4} distance

{5} time

{6} next street name

{7} roundabout exit count



Creating Custom Directions on the Client Side With the addition of server side DirectionsGenerators in Routing J Server 4.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();

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();

Developer Guide 57

Additional Routing Directions Information

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 4.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 . . . . . . . . . . . . . . . . . . . . . . .60Returning Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60Using Per Request Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62Working with Includes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62Setting the Timeout Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63Setting Travel Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63Working with Time-based Routing . . . . . . . . . . . . . . . . . . . . . . . . .64Routing J Server Internationalization. . . . . . . . . . . . . . . . . . . . . . .69MultiPointPreferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70

RoutingPreferences Class Overview

RoutingPreferences Class OverviewThe 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 PreferencesThe 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 DataThe 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


Chapter 6: Customizing Routing with Preferences

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.

Developer Guide 61

Using Per Request Updates

Using Per Request UpdatesPer 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 81.

Working with IncludesInclude 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 ValueThe 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 PreferencesThis 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 preference levels:

• 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

Developer Guide 63

Working with Time-based Routing

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 RoutingRouting 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 RoutesMaking 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.

Developer Guide 65

Using Time Zones in Routes

• 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);

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



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.

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 zone

Developer Guide 67

Using Time Zones in Routes

RoutingPreference 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 InternationalizationFor 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.

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:

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.• 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 a DirectionsStrings and TerseDirectionsStrings file for each 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.

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 PM Eastern time

Developer Guide 69

MultiPointPreferences

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.

International Java Virtual MachineRouting J Server 4.0 now uses a international version of the JVM instead of an English JVM.

MultiPointPreferencesThe 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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72Using IsoPreferences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72Expected Isochrone/Isodistance Behavior . . . . . . . . . . . . . . . . . .76Donut Style Banding Suggestions . . . . . . . . . . . . . . . . . . . . . . . . .76Obtaining Isochrones/Isodistances . . . . . . . . . . . . . . . . . . . . . . . .77

IsoDefinition Overview

IsoDefinition OverviewAn 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 IsoPreferencesThe 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.


Chapter 7: Working with the IsoClient

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 distance 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 server uses side streets and other types of secondary roads when calculating the iso response if majorRoadsOnly set to false.

Developer Guide 73

Using IsoPreferences

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.

Developer Guide 75

Expected Isochrone/Isodistance Behavior

Expected Isochrone/Isodistance BehaviorThis 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 SuggestionsA 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/IsodistancesUse 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/routing40/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();

Developer Guide 77

Obtaining Isochrones/Isodistances

//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 . . . . . . . . . . . . . . . . . . . . . . .80Modifying Data with Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81

Accessing Routing Data Information

Accessing Routing Data InformationRouting 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.

Note RoutingData client does not return Commercial Vehicle Restrictions for segments.

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/routing40/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();


Chapter 8: Using the RoutingDataClient and Data Updates

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 UpdatesData 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. You cannot, however, override commercial vehicle restriction data.

Persistent UpdatesPersistent updates are updates made to the server that apply to all requests. These updates remain intact if the server is restarted. PersistentUpdates is supported only through the XML API (see Chapter 9: MapInfo Enterprise XML Protocol).

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

Developer Guide 81

Modifying Data with Updates

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_4_0.dtd on page 91.


9
MapInfo Enterprise XML Protocol
The MapInfo Enterprise XML 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.

In this chapter:

Working with the XML API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84Document Type Definitions (DTD) . . . . . . . . . . . . . . . . . . . . . . . . .85HTTP Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87XML Elements Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88MI_XML_Protocol_RoutingRequestAndResponse Envelope_4.0.dtd90MI_XML_Protocol_RoutingCommonElements_4_0.dtd . . . . . . . .91MI_XML_Protocol_RoutingRouteRequestAndResponse_4_0.dtd. .96MI_XML_Protocol_RoutingMultiRequestAndResponse_4_0.dtd 97MI_XML_Protocol_RoutingIsoRequestAndResponse_4_0.dtd .100MI_XML_Protocol_RoutingPersistentUpdatesRequestAnd Response_4_0.dtd102MI_XML_Protocol_RoutingMatrixRequestAndResponse_4_0.dtd .103MI_XML_Protocol_RoutingDataRequestAndResponse_2_5.dtd . . .104XML Backward Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . .104Supported Road Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105

Working with the XML API

Working with the XML APIIn 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 PersistentUpdates. PersistentUpdates is supported only through the XML API. All other request types are supported through 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-4.0\lib\server. For more information on DTDs, see Document Type Definitions (DTD) on page 85.

Note MI_XML_Protocol_RoutingRequestAndResponseEnvelope_4_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_4_0.dtd) and OGC DTDs.

Request/Response Type Associated DTD*

Route MI_XML_Protocol_RoutingRouteRequestAndResponse_4_0.dtd

MultiPoint MI_XML_Protocol_RoutingMultiRequestAndResponse_4_0.dtd

Matrix MI_XML_Protocol_RoutingMatrixRequestAndResponse_4_0.dtd

Isochrone MI_XML_Protocol_RoutingIsoRequestAndResponse_4_0.dtd

RoutingData MI_XML_Protocol_RoutingDataRequestAndResponse_2_5.dtd

(unchanged from RJS 2.5)

PersistentUpdate MI_XML_Protocol_RoutingPersistentUpdatesRequestAndResponse_4_0.dtd


Chapter 9: MapInfo Enterprise XML Protocol

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

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 sample

The 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 development

Routing 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 requests

If 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.

Developer Guide 85

Document Type Definitions (DTD)

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 Backward Compatibility on page 104.

* These DTDs are dependent on the MI_XML_Protocol_ OGC DTDs.

DTD Description

MI_XML_Protocol_RoutingRequestAndResponseEnvelope_4_0.dtd *

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

MI_XML_Protocol_RoutingRouteRequestAnd Response_4_0.dtd *

Defines route requests and responses between client and server.

MI_XML_Protocol_RoutingMultiRequestAnd Response_4_0.dtd *

Defines multiPoint requests and responses between client and server.

MI_XML_Protocol_RoutingIsoRequest AndResponse_4_0.dtd *

Defines iso requests and responses between client and server.

MI_XML_Protocol_RoutingPersistent UpdatesRequestAndResponse_4_0.dtd *

Defines persistent updates requests and responses between client and server.

MI_XML_Protocol_RoutingCommon Elements_4_0.dtd *

Defines routing elements common for different types of routing requests such as start and end points, routing algorithm and response constraints, 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_4_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, geocoding, and mapping.

MI_XML_Protocol_OGC_GML_1_0.dtd Defines simple GML (Geographic Markup Language) geometry elements for points, polygons, 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.



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

The following HTTP headers identify the request:

The following HTTP headers identify the response:

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, IsoRequest, MultiPointRequest, PersistentUpdates Request, MatrixRouteRequest

required Identifies the request type.

MI_XMLProtocolVersion 4.0 required XML protocol version.

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

HTTP header ValuesRequired or


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

MI_XMLProtocolResponse RouteResponse, IsoResponse, MultiPointResponse, PersistentUpdates Response, MatrixRoute

required Identifies the response type.

Developer Guide 87

XML Elements Description

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.

XML Elements DescriptionThe 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_XMLProtocolVersion 4.0 required XML protocol version.

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

HTTP header ValuesRequired or




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://http://www.opengeospatial.org/standards/gml. 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.

Routing Requests

Routing 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.

Developer Guide 89

http://www.opengeospatial.org/standards/gml

MI_XML_Protocol_RoutingRequestAndResponse Envelope_4.0.dtd

Routing Responses

Response 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_4.0.dtdThe table below provides a description of the elements defined in MI_XML_Protocol_RoutingRequestAndResponseEnvelope_4.0.dtd.

Element Description

RoutingRequestEnvelope The type of request: RouteRequest, MultiPointRequest, IsoRequest, PersistentUpdatesRequest, RoutingDataRequest, or| MatrixRouteRequest.

Locale The 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.



MI_XML_Protocol_RoutingCommonElements_4_0.dtdThe tables below provide a description of the elements and attributes defined in MI_XML_Protocol_RoutingCommonElements_4_0.dtd.

Constraint Elements

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, IncludeActualConstraints 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 primary name and all alternate names will be used.

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 values between 0 to 180.

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

Developer Guide 91

MI_XML_Protocol_RoutingCommonElements_4_0.dtd

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

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, SegmentUpdate, 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.

RoadTypeReset Contains the road type to be reset.

StartDateTime Specifies the start date.



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_4_0.dtd.

EndDateTime Specifies the end date.

dateTime A string representing the date, time, and time zone. The string pattern does not change with the locale .

ShowDistance If true, the distance displays in the directions.

ShowTime If true, the time displays in the directions.

Element Description

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.

Developer Guide 93

MI_XML_Protocol_RoutingCommonElements_4_0.dtd

DstEndTime The end time for daylight savings.

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

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 measure 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 possibly 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:N, S, E, W, NE, NW, SE, SW

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.

Element Description



DstEndTime The end time for daylight savings.

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

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 measure 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 possibly 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:N, S, E, W, NE, NW, SE, SW

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.

Element Description

Developer Guide 95

MI_XML_Protocol_RoutingRouteRequestAndResponse_4_0.dtd

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

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.)

VehicleAttributes Optional. Includes VehicleType, VehicleLength, VehicleWidth, VehicleHeight, VehicleWeight. If present in the request, then segment restrictions in the data will be considered.

VehicleType Required. The type of the vehicle. The following values are allowed: ALL | STRAIGHT | SEMI_TRAILOR | STANDARD_DOUBLE | INTERMEDIATE_DOUBLE | LONG_DOUBLE | TRIPLE | OTHER_LONG_COMBINATION_VEHICLE

VehicleLength Optional. The length of the vehicle in cm.

VehicleWidth Optional.The width of the vehicle in cm.

VehicleHeight Optional. The height of the vehicle in cm.

VehicleWeight Optional.The weight of the vehicle in kg.

RouteSummary Summary of the time and distance of a route.

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

Element Description

Element Description

RouteRequest Request for a route.

RoutePointList Contains route start and end points.

VehicleAttributes Optional. Includes VehicleType, VehicleLength, VehicleWidth, VehicleHeight, VehicleWeight. If present in the request, then segment restrictions in the data will be considered.

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



MI_XML_Protocol_RoutingMultiRequestAndResponse_4_0.dtdThe table below provides a description of the elements and attributes defined in MI_XML_Protocol_RoutingMultiRequestAndResponse_4_0.dtd.

RouteResponseConstraints 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 RouteResponseConstraints.

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

Element Description

ElementExpected Default Description

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

Developer Guide 97

MI_XML_Protocol_RoutingMultiRequestAndResponse_4_0.dtd


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 numbers. 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 balancing 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 minimal 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.

VehicleAttributes Includes VehicleType, VehicleLength, VehicleWidth, VehicleHeight, VehicleWeight. If present in the request, then segment restrictions in the data will be considered.

IntermediatePointList Intermediate points of a multiPoint request.

MultiPointConstraints MultiPoint preferences.

MultiPointResponse A successful multiPoint response must contain at least a multiPoint summary. RequestConstraintsOverridden attribute has a true value if:



MultiPointSummary Contains total route time, total route distance, directions summary (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.

MultiPointResponseConstraints MultiPoint response constraints. MultiPoint response constraints 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.

Element Description

Developer Guide 99

MI_XML_Protocol_RoutingIsoRequestAndResponse_4_0.dtd

MI_XML_Protocol_RoutingIsoRequestAndResponse_4_0.dtdThe table below provides a description of the elements and attributes defined in MI_XML_Protocol_RoutingIsoRequestAndResponse_4_0.dtd.


DefaultAmbientSpeed 15 MPH The default ambient speed used for the calculation 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 representing 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 significant geometry features.

SimplificationFactor 0.05 The simplification percentage used in the calculation 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.


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.

OverridePropagationFactorSet 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.

Developer Guide 101

MI_XML_Protocol_RoutingPersistentUpdatesRequestAnd Response_4_0.dtd

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

BoundaryStyle Holds values for includeHoles and includeIslands.

IsoResponseConstraints Iso response constraints.

IsoResponse RequestConstraintsOverridden attribute has a true value if:



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

Element Description

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

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

PersistentUpdatesResponse

Specifies a successful response to an update/reset.

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



MI_XML_Protocol_RoutingMatrixRequestAndResponse_4_0.dtdThe table below provides a description of the elements and attributes defined in MI_XML_Protocol_RoutingMatrixRequestAndResponse_4_0.dtd.

Element Description

MatrixRouteRequest Request for a matrix route.

MatrixRoutePoints Points for the matrix. The list can be StartPointList or EndPointList.

VehicleAttributes Includes VehicleType, VehicleLength, VehicleWidth, VehicleHeight, VehicleWeight. If present in the request, then segment restrictions in the data will be considered.

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.

MatrixRouteResponseConstraints

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 contains 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.

Developer Guide 103

MI_XML_Protocol_RoutingDataRequestAndResponse_2_5.dtd

MI_XML_Protocol_RoutingDataRequestAndResponse_2_5.dtdThe 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 Backward CompatibilityThe 4.0 version of Routing J Server can accept Routing J Server 3.0 and 2.5 XML requests. If you have validation turned on, the server will automatically accept the correct version request. If you want to validate a 3.0 request you must submit the request with a MI_XMLProtocolVersion of 3.0. 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 (3.0 or 2.5) to the server (4.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. I assume this is referring to an error in the 2.5 dtd, and still applies to anyone sending a 2.5 request.

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 segment id.

RoutingDataResponseConstraints

Response constraints.

RoutingDataResponse Contains a SegmentSet and possibly RoutingDataServerConstraints.

RequestConstraintsOverridden attribute has a true value if:



RoutingDataServerConstraints The actual constraints used by the server.



Supported Road TypesThe following tables lists supported road types for Routing J Server 4.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

Developer Guide 105

Supported Road Types

SECONDARY_HIGHWAY_SUBURBAN secondary highway suburban

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-4.0\examples-usa\ directory of the path where you installed the MapInfo Routing J Server.

In this chapter:

Diagnostic Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108RoutingClientGUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108TestXML Sample. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109Directions Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Classpaths for Routing Samples . . . . . . . . . . . . . . . . . . . . . . . . .112Localization of Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113

Diagnostic Samples

Diagnostic SamplesMapinfo Routing J Server provides diagnostic samples that enable you to verify that everything has been installed and set up correctly. The diagnostic samples are:

• RoutingClientGUI• TestXML

RoutingClientGUIThis 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-40\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-4.0\examples_usa\diagnostics\RoutingClientGUI directory. You can also make modifications by editing the RoutingClientGUI.lax file (located in the RJS \bin folder).

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.


Chapter 10: Working with Routing Samples

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-4.0\examples_usa\diagnostics\TestXML directory.

Route RequestThis is a sample of the route request XML file. Look in \RoutingJServer-4.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 83.

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

Developer Guide 109

TestXML Sample

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

Directions SampleA sample directions generator is provided in RoutingJServer-4.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-4.0/examples-usa/direction to RoutingJServer-4.0/Tomcat-4.1/webapps/routing40/WEB-INF/classes).

2. Place direction-registry.xml found under RoutingJServer-4.0/examples-usa/direction in the server classpath (copy direction-registry.xml to RoutingJServer-4.0/Tomcat-4.1/webapps/routing40/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-4.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 109.

Developer Guide 111

Classpaths for Routing Samples

• 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-4.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 SamplesBefore 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-4.0\bin.

The paths used in the following examples are:

set RJS_BIN=<RJS_DIR>\RoutingJServer-4.0\binset RJS_COMMON=<RJS_DIR>\RoutingJServer-4.0\lib\commonset RJS_CLIENT=<RJS_DIR\RoutingJServer-4.0\lib\client

RoutingAdmin and RoutingClientGUIset CLASSPATH=.set CLASSPATH=%CLASSPATH%;%RJS_BIN%set CLASSPATH=%CLASSPATH%;%RJS_COMMON%\micsys.jarset CLASSPATH=%CLASSPATH%;%RJS_CLIENT%\rjsclient.jar

TestXMLset CLASSPATH=.set CLASSPATH=%CLASSPATH%;%RJS_BIN%set CLASSPATH=%CLASSPATH%;%RJS_COMMON%\micsys.jarset CLASSPATH=%CLASSPATH%;%RJS_CLIENT%\rjsclient.jarset CLASSPATH=%CLASSPATH%;%RJS_COMMON%\jdom.jarset CLASSPATH=%CLASSPATH%;%RJS_COMMON%\xmlParserApis.jar



Localization of SamplesSamples included with Routing J Server 4.0 are not localized. There are ways to configure them to appear customized for a locale. Use the information below to guide your customization.

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_1DEFAULT_LATITUDE_1

DEFAULT_LONGITUDE_2DEFAULT_LATITUDE_2

Developer Guide 113

Localization of Samples


11
Troubleshooting
This chapter contains important information to help determine why your routing application may not function properly. Pitney Bowes Business Insight Technical Support also publishes a full knowledge base on all MapInfo productsunder the Support section of the Web site.

In this chapter:

Testing the Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116Web Server Connection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116Other Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117

http://testdrive.mapinfo.com/kbase_by_product

Testing the Connection

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>/routing40/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.

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>/routing40/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 routing40 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.


Chapter 11: Troubleshooting

• 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 14 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.

Other Issues

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 117

Other Issues


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.

In this appendix:

Sample web.xml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120

Sample web.xml File

Sample web.xml FileThe 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>


<param-name>handlesPersistentUpdatesRequests</param-name> <param-value>false</param-value>


<param-name>handlesMatrixRouteRequests</param-name> <param-value>true</param-value>

</init-param>


Chapter A: Web.xml

- <init-param> <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>

Developer Guide 121

Sample web.xml File

<param-value>false</param-value> </init-param>-  - <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.

In this appendix:

RoutingServlet Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124

RoutingServlet Parameters

RoutingServlet ParametersThe 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 directories that contain the datasets to be used by the Routing J Server. For example:

d:\mapinfo\v40data\usa\NorthEast;d:\mapinfo\v40data\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. Supported road classes (or types) are listed in RoadType javadoc. For persistent updates, current road speeds for segments 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 routing data requests. Note that there is always one thread for PersistentUpdates. If this parameter is left commented 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.

handlesIsoRequests true/false true If true, the servlet handles the iso requests.


Chapter B: Initialization Parameters

handlesMultiPointRequests true/false true If true, the servlet handles the multiPoint requests.

handlesRoutingData Requests

true/false true If true, the servlet handles the routing data requests.

handlesPersistentUpdates 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.


Developer Guide 125

RoutingServlet Parameters

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 distance

shortest time Finds the shortest distance or finds the shortest time. This setting has to do with route results as opposed to iso results.

simplificationFactor double 0.05 A value between 0 and 1 that represents 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.

isoDefaultPropagationFactor double 0.16 The default propagation factor for isodistances.

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 isochrones.



C
Deprecated API
The routing API has undergone a number of changes. The following sections list deprecated classes, fields, methods, and constructors.

In this appendix:

Deprecated Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128Deprecated Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128Deprecated Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134

Deprecated Classes

Deprecated Classes As of Version 3.0, RoutingAdminClient has been deprecated.

Deprecated FieldsThe 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.

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)


Chapter C: Deprecated API

• 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.

Developer Guide 129

Deprecated Methods

• 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.

Developer Guide 131

Deprecated Methods

• 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)

Developer Guide 133

Deprecated Constructors

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 speed

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.

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.

Commercial Vehicle Restrictions (CVR)

Segment-based attributes for length, width, height, and weight limits. When used in conjunction with vehicle attributes and vehicle types, a route can be generated to avoid restricted segments.

Cost

The 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 areas

Areas 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 areas

The StreetDirections and DirectionsSummary elements of the XML.

Directions generator

Any 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.

Directions locale

The 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 style

A grouping of strings used to generate directions.

Directions template

Strings 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 point

The first or last point in a RouteSegment.

Focus on end

Route that directs the user from the last major highway in the route (including that highway) to the destination.

Focus on start

Route that directs the user from their origin to (and including) the first major highway.

Hard Restriction

A type of road segment restriction that prohibits a vehicle from traversing the segment due to local ordinance or physical limit of the segment, for example bridge weight. See also Commercial Vehicle Restrictions (CVR).


Chapter D: Glossary

Hole

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.

Internationalization

For 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.

Isochrone

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.

Isodistance

A 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.

Locale

A 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". See the official two-digit language codes country codes.

Local time-of-day

The time-of-day relative to the route points.

Local time zone

The time zone relative to the route points.

Major road

A 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.

Developer Guide 137

http://www.unicode.org/unicode/onlinedat/languages.html

http://www.unicode.org/unicode/onlinedat/languages.html

http://www.unicode.org/unicode/onlinedat/countries.html

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.

Node

The 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.

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 locale

The 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 locale

The 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.


Chapter D: Glossary

Segment Attributions

Information attributed to a particular segment of the route. Can include commercial vehicle restrictions, speed limts, type of road and more.

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.

Soft Restriction

A restriction on a segment that allows a commercial vehicle to traverse it only when necessary. For example, if the segment is the last mile access or it is for local delivery. See also Commercial Vehicle Restrictions (CVR).

Supported Locale

A 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 interval

A 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 interval

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

Developer Guide 139

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.

Transient Update

An 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.

Transition

Definition 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 locale

A 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 offset

The total offset from Coordinated Universal Time considering both GMT offset and DST offset. See ISO 8601 standard for the complete definition.

Vehicle Attributes

Values that define a commercial vehicle including type of vehicle and its dimensions (length width and height) and weight.

Waypoints

An intermediate point between any two other points.


E
Open Source Attributions
The following open source software are included in Routing J Server.4.0.

Apache Commons - Collections 2.1

Licensed under the Apache License, Version 1.1. The license can be downloaded from http://www.apache.org/licenses/LICENSE-1.1.html.

The source code for this software is available from http://archive.apache.org/dist/commons/collections/binaries/collections-2.1.zip

Apache Commons - IO


The source code for this software is available from http://archive.apache.org/dist/commons/io/binaries/commons-io-2.0-bin.zip.

Apache Commons - Lang 2.5


The source code for this software is available from http://www.fightrice.com/mirrors/apache//commons/lang/binaries/commons-lang-2.5-bin.zip.

Apache Commons - Logging 1.0.2


The source code for this software is available from http://archive.apache.org/dist/commons/logging/binaries/logging.1.0.1.zip.

http://www.apache.org/licenses/LICENSE-2.0.html




http://archive.apache.org/dist/commons/collections/binaries/collections-2.1.zip

http://archive.apache.org/dist/commons/io/binaries/commons-io-2.0-bin.zip

http://archive.apache.org/dist/commons/io/binaries/commons-io-2.0-bin.zip

http://www.fightrice.com/mirrors/apache//commons/lang/binaries/commons-lang-2.5-bin.zip

http://www.fightrice.com/mirrors/apache//commons/lang/binaries/commons-lang-2.5-bin.zip

http://archive.apache.org/dist/commons/logging/binaries/logging.1.0.1.zip

http://archive.apache.org/dist/commons/logging/binaries/logging.1.0.1.zip

Apache Log4j 1.2.7


The source code for this software is available from http://archive.apache.org/dist/logging/log4j/1.2.7/jakarta-log4j-1.2.7.zip

Apache - Xerces 2.0.1


The source code for this software is available from http://xerces.apache.org/mirrors.cgi.

JDOM 1.0beta9

JDOM is available under an Apache-style open source license, with the acknowledgment clause removed. The license is available at the top of every source file and in LICENSE.txt in the root of the distribution.

The source code for this software is available from http://jdom.org/dist/binary/archive/jdom-b9.zip.



http://archive.apache.org/dist/logging/log4j/1.2.7/jakarta-log4j-1.2.7.zip


http://xerces.apache.org/mirrors.cgi

http://jdom.org/dist/binary/archive/jdom-b9.zip

http://jdom.org/dist/binary/archive/jdom-b9.zip

Index

AAmbient speed 72API deprecations

classes 128constructors 134fields 128methods 128

attributionsopen source 141–142

BBacwards compatibility 104Banding suggestions 76

CClasspaths for samples 112Client applications

MatrixRouteClient 38–40MultiPointClient 37–38RoutingClient 35–37

Code samplesIsochrones/Isodistance 77obtaining segment data 80route request XML 109time zones 67time-based routing 64

Commercial Vehicle Restrictions 40–41Common elements 91–96Costs 38, 72

DData

modifying 81returning with preferences 60segment information 80

Data installationfull 16partial 16

Datasets 31Delta updates 81Deployment options 26Deprecations

classes 128constructors 134fields 128methods 128

Diagnostic samplesRoutingClientGUI 108TestXML 109

Directionscustom 48default 44DirectionsPreferences 45generators 48roundabout support 58token definitions 56

Directions generator sample 111Directions Strings

routing directions 53turn angle 55

Documentation resources 13, 32Donut style banding 76DTDs 85

HHardware requirements 13HTTP connections 32HTTP headers 87

IIndividual request modifications 62Information resources 13Initialization parameters

RoutingServlet 124

Developer Guide 143

Index

Installationconsole 23full data 16no graphics card 22partial data 16server 16–22testing 24

Installed componentsjar files 25samples 25

Internationalization 69IsoClient

ambient speed 72donut style banding 76isochrones/isodistance 77isoDefinition 72isoPreferences 72propogation factor 73

IsoDefinition 72IsoPreferences 72

JJar files 25

LLocalization of samples 113logging 27

MManual installation 23MatrixRouteClient applications 38–40Modifying data 81MultiPointClient applications 37–38MultiPointPreferences 70

NNew features 12

Oopen source attributions 141–142

PPerformance

MatrixRoute tuning 40server tuning 14

Persistent updatesmodifying data 81

platformssupported 14

Preferencesinclude 62internationalization 69MultiPoint 70per request updates 62returning data 60time zones 65time-based routing 64travel 63

Propagation factor 73

RRequirements

hardware 13software 13

restrictionscommercial vehicles 40–41

Road typespreferences 63supported 105

Route costs 38Route interface 34Routing requests 89Routing responses 90RoutingClient applications 35–37RoutingClientGUI 108RoutingPreferences

include 62internationalization 69per request updates 62returning data 60time zones 65time-based routing 64travel 63

RoutingServlet initialization parameters 124

SSamples

classpaths 112Directions generator 111localization 113RoutingClientGUI 108TestXML 109

Server installation 16–22Software requirements 13Support resources 32supported platforms 14System logging 27system requirements 13


Index

TTestXML sample 109Time zones

end time 66start time 66

Time-based routes 64Transient Updates

modifying data 81Travel preferences 63Troubleshooting

connection testing 116Persistent updates 117server considerations 116Web server connections 116

Turn Angle Strings 55

UUpdates 81

Vvehicle attributes

commercial vehicles 41

WWeb server environments 26Web.xml

sample file 119

XXML

backwards compatibility 104common elements 91–96DTDs 85iso request and response 100matrix request and response 103multi request and response 97naming and usage 88persistent updates request and response 102route request and response 96routing requests 89routing responses 90

Developer Guide 145

Date post:	26-Jul-2020
Category:	Documents
Upload:	others
View:	9 times
Download:	0 times

Routing J Server - Pitney Bowes...Routing J Server 4.0 is fully backward compatible with Routing J...

Documents