faa.tg.nas.route
Class Route

java.lang.Object
  faa.tg.nas.route.Route

All Implemented Interfaces:

TextWritable, HasName, Filterable, Recordable, ManagedObject, java.io.Serializable, java.lang.Cloneable

Direct Known Subclasses:

EramAirway, GroundRoute, JetRoute, OffsetRoute, RouteWEndRadial, VictorRoute

public class Route
extends java.lang.Object
implements java.lang.Cloneable, Recordable, HasName, TextWritable

 Route is a class which defines a path for an aircraft to follow.
 It contains a list of RouteNodes that defines a sequence of fixes
 which define the route.
 

See the source: Route.java

Version:

$Id: Route.java,v 3.44 2008/12/05 22:44:12 danaw Exp $

Author:

David D'Auria

See Also:

RouteNode, Serialized Form

Nested Class Summary

static interface

Route.DescentCapturePredictor

Field Summary

static java.lang.String	CVS_VERSION_ID The CVS Version ID
private java.lang.String	name The name of the route.
static java.text.DecimalFormat	OFFSET Route name suffix format (for suffix output string to provide info on route offset).
private boolean	restricted Whether this route has altitude or speed restrictions.
protected java.util.List<RouteNode>	rnlist The OLD list of Route Nodes: this can be removed when recordings before 2007/05/08 are no longer needed.
protected java.util.List<RouteNode>	routeNodes The list of Route Nodes.
protected java.util.List<RouteSegment>	routeSegments The list of Route Segments.
protected java.util.List<RouteSegment>	rslist The OLD list of Route Segments: this can be removed when recordings before 2007/05/08 are no longer needed.
(package private) static long	serialVersionUID

Constructor Summary

Route()
Construct an unnamed route.

Route(java.lang.String routeName)
Construct a named (Empty) route.

Method Summary

boolean	add(Route rteToAdd) Adds (appends) a route to the end of this route.
void	addRouteNode(Fix center, RouteNode rn) Adds a route node to the route.
boolean	addRouteNode(RouteNode rn) Adds a route node to the route.
RouteSegment	calcMinDistanceToTrailingFix(Position position) Returns the RouteSegment of this Route that has the trailing fix that is closest to the given Position.
Route	clone() Generates a deep copy of the Route.
int	compare(Fix firstFix, Fix secondFix) Returns an integer value that is less than zero if firstFix is before secondFix, a value that is greater than zero if firstFix is after the secondFix, or a value that is zero if firstFix is equal to secondFix.
boolean	contains(Fix theFix) Returns whether this route contains the specified fix.
boolean	containsNode(RouteNode theNode) Returns whether this route contains the specified route node.
void	debug() Sends information about a route to the TgMsg.debug() output
RouteSegment	determineCaptureSegment(Position thePosition) Determines a RouteSegment to capture on this Route object given a position, satisfying the criteria 1 and 2 in the Lateral Guidance System.
RouteSegment	determineCaptureSegmentOrRadial(Position position) Determines a RouteSegment to capture on this Route object given a position, satisfying the criteria 1 and 2 in the Lateral Guidance System.
RouteSegment	detNearestSegment(Position position) Determines the nearest RouteSegment for capture, satisfying criteria 1 and criteria 2 (See the analysis for the Lateral Guidance System for complete details).
RouteSegment	detNearestSegmentOrRadial(Position position) Determines the nearest RouteSegment for capture, satisfying criteria 1 and criteria 2 (See the analysis for the Lateral Guidance System for complete details).
Distance	distanceBetween(Fix startFix, Fix endFix) Returns the distance between the two specified fixes on the route.
Distance	distanceToFix(Position currPos, RouteSegment currSeg, Fix target) Returns the distance along the route from an object with currPos, which is assumed to lie somewhere along currSeg to the target Fix somewhere along the Route.
Fix	getAlternativeFix(RouteNode theNode) Returns the alternative fix for the fix contained in the RouteNode argument.
RouteNode	getFirstNode() Returns the first RouteNode of this Route.
RouteSegment	getFirstSegment() Returns the first RouteSegment in this Route
int	getIndexOfNode(Fix theFix) Searches for the RouteNode that contains the specified fix.
RouteNode	getLastNode() Returns the last RouteNode of this Route.
java.lang.String	getName() Returns the name of the Route.
RouteNode	getNextAltitudeRestriction(Fix fix) Gets the next altitude restricted route node after the specified fix.
RouteNode	getRouteNode(Fix theFix) Gets the RouteNode that contains the specified fix.
RouteNode	getRouteNode(java.lang.String fixName) Returns the route node reference containing the fix with the specified name, or null if a route node containing the fix does not exist.
RouteNode	getRouteNodeAt(int idx) Returns the RouteNode at the specified index.
int	getRouteNodeCount() Returns the number of RouteNodes in this route.
java.util.Iterator<RouteNode>	getRouteNodeIterator() Returns an Iterator over the RouteNodes in the Route.
java.util.Iterator<RouteSegment>	getRouteSegmentIterator() Returns an Iterator over the RouteSegments in the Route.
java.util.List<RouteSegment>	getRouteSegmentList() Returns (a Reference to) the list of RouteSegments contained in this Route
java.lang.String	getRouteWithBracketLogic() Returns the route as a dot string with any actions or restrictions in brackets.
Route	getSubRoute(Fix theStartFix) Returns the portion of this route starting at the start fix and continuing through the fixes including the end of the route; returns null if a fix is not on the route.
Route	getSubRoute(Fix theStartFix, Fix theEndFix) Returns the portion of this route starting at the start fix and continuing through the fixes including the end of the route; returns null if a fix is not on the route; if the end fix precedes the start fix on the original Route, the order of the returned subroute is reversed compared to the original.
Route	getSubRoute(Position position, Fix helperFix) Returns a portion of this route based upon a position and a helper fix; returns null if there is a problem determining the subroute.
boolean	isEmpty() Returns whether this Route is empty (has no route nodes).
boolean	isRestricted()
static void	main(java.lang.String[] args)
private void	readObject(java.io.ObjectInputStream in) If rslist and rnlist are of obsolete type faa.tg.list.TgList, convert to typed Vectors.
void	restrictionCaptureTest(Route.DescentCapturePredictor predictor) Do route validation on altitude restrictions.
Distance	routeFollowingDistance(Fix startFix, Fix endFix, Distance turnRadius) This gets the length of the route as followed by the aircraft: this distance calculation is generally shorter than Route.totalLength() because most turns (on the segment changes) will shorten the path.
int	size() Gets the number of RouteNodes in this route.
java.lang.String	toDotSepString() Returns a representation of this Route with dots (.) between the fixes.
java.lang.String	toDraText() Prints DR&A text information to a String.
java.lang.String	toNasString() Returns the route in nas format Basically fix..fix...
java.lang.String	toSpaceSepString() Returns a representation of this Route with spaces between the fixes.
java.lang.String	toString() Returns a string representation of this Route.
Distance	totalLength() This gets the length of the route: this is not quite the same as the length of the path an aircraft will take while following the route, since aircraft will cut corners to some extent on turns (based on their turn radius).
private boolean	validFix(boolean enforce, Fix fix, AircraftEquipment equip) Returns whether a fix is valid
java.lang.String	validWithNavigationLimits(boolean enforce, AcType type) Returns whether an an aircraft could follow its route if it was forced to obey the limitations of its navigation equipment.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

serialVersionUID

static final long serialVersionUID

See Also:

Constant Field Values

CVS_VERSION_ID

public static final java.lang.String CVS_VERSION_ID

The CVS Version ID

See Also:

Constant Field Values

OFFSET

public static final java.text.DecimalFormat OFFSET

Route name suffix format (for suffix output string to provide info on route offset). Format is expressed by _R (right) or _L (left) followed by the offset distance in tenths of nautical miles (minimum 2 digits), rounded to the nearest whole value: "_R00;_L00". For example, one nautical mile to the left of the route results in a suffix of: "_L10".

name

private java.lang.String name

The name of the route.

rnlist

protected final java.util.List<RouteNode> rnlist

The OLD list of Route Nodes: this can be removed when recordings before 2007/05/08 are no longer needed.

rslist

protected final java.util.List<RouteSegment> rslist

The OLD list of Route Segments: this can be removed when recordings before 2007/05/08 are no longer needed.

restricted

private boolean restricted

Whether this route has altitude or speed restrictions.

routeNodes

protected java.util.List<RouteNode> routeNodes

The list of Route Nodes.

routeSegments

protected java.util.List<RouteSegment> routeSegments

The list of Route Segments.

Constructor Detail

Route

public Route()

Construct an unnamed route.

Route

public Route(java.lang.String routeName)

Construct a named (Empty) route.

Parameters:

routeName - the name of the route.

Method Detail

readObject

private void readObject(java.io.ObjectInputStream in)
                 throws java.io.IOException,
                        java.lang.ClassNotFoundException

If rslist and rnlist are of obsolete type faa.tg.list.TgList, convert to typed Vectors.

Throws:

java.io.IOException

java.lang.ClassNotFoundException

getFirstSegment

public RouteSegment getFirstSegment()

Returns the first RouteSegment in this Route

Returns:

RouteSegment the first RouteSegment in this Route or null if none exists...

getRouteSegmentList

public java.util.List<RouteSegment> getRouteSegmentList()

Returns (a Reference to) the list of RouteSegments contained in this Route

Returns:

RouteSegmentList the list of RouteSegments in this Route

distanceToFix

public Distance distanceToFix(Position currPos,
                              RouteSegment currSeg,
                              Fix target)

Returns the distance along the route from an object with currPos, which is assumed to lie somewhere along currSeg to the target Fix somewhere along the Route. This method assumes that the target fix is beyond or equal to the end node in the current route segment.

Parameters:

currPos - AC position, which is somewhere on given RouteSegment.

currSeg - The current route segment being followed.

target - A Fix along the route, beyond the route segment.

getName

public java.lang.String getName()

Returns the name of the Route.

Specified by:

getName in interface ManagedObject

Returns:

Returns the name of the object.

addRouteNode

public boolean addRouteNode(RouteNode rn)

Adds a route node to the route. Creates a route segment between every 2 nodes.

Parameters:

rn - the route node.

Returns:

Returns whether node was added.

addRouteNode

public void addRouteNode(Fix center,
                         RouteNode rn)

Adds a route node to the route. Creates a route segment between every 2 nodes.

Parameters:

rn - the route node.

getNextAltitudeRestriction

public RouteNode getNextAltitudeRestriction(Fix fix)

Gets the next altitude restricted route node after the specified fix.

Parameters:

fix - The fix after which to look for restrictions (if null, looks at the first fix of the route).

Returns:

RouteNode of the next restriction after the specified fix, or null if no restrictions exist after the fix.

Throws:

java.lang.IllegalArgumentException - If fix is not on route.

getRouteNode

public RouteNode getRouteNode(Fix theFix)

Gets the RouteNode that contains the specified fix.

Parameters:

theFix - the fix to find the route node of.

Returns:

RouteNode containing the specified fix if it exists; else null.

getRouteNode

public RouteNode getRouteNode(java.lang.String fixName)

Returns the route node reference containing the fix with the specified name, or null if a route node containing the fix does not exist.

Parameters:

fixName - The name of the fix to get the RouteNode for.

getSubRoute

public Route getSubRoute(Position position,
                         Fix helperFix)

Returns a portion of this route based upon a position and a helper fix; returns null if there is a problem determining the subroute. A new route is returned from a fix on either end of the determined capture segment to the ending of the route, using the helper fix to determine which end that is.

Parameters:

position - the position in space used to determine which routeSegment would be intercepted.

helperFix - a fix along the route used to determine which direction the subRoute should be constructed in.

Returns:

a Route made up of an end fix along the captured route segment to the end of the route. A null is returned if direction could not be determined or if invalid data is passed to this method.

distanceBetween

public Distance distanceBetween(Fix startFix,
                                Fix endFix)

Returns the distance between the two specified fixes on the route. This is a lot faster than creating a subroute and getting its total length, but the start fix must be before the end fix.

Parameters:

startFix - The first fix to appear in the subroute.

endFix - The last fix to appear in the subroute.

Throws:

java.lang.IllegalArgumentException - A fix is not on the route, or end fix is not after start fix.

getSubRoute

public Route getSubRoute(Fix theStartFix,
                         Fix theEndFix)

Returns the portion of this route starting at the start fix and continuing through the fixes including the end of the route; returns null if a fix is not on the route; if the end fix precedes the start fix on the original Route, the order of the returned subroute is reversed compared to the original. A new Route is allocated but populated with references to existing RouteNodes. Clone the returned Route if you want a deep copy.

Parameters:

theStartFix - the first fix in the new subroute.

theEndFix - the last fix in the new subroute.

getSubRoute

public Route getSubRoute(Fix theStartFix)

Returns the portion of this route starting at the start fix and continuing through the fixes including the end of the route; returns null if a fix is not on the route.

Parameters:

theStartFix - the first fix to appear in the subroute.

add

public boolean add(Route rteToAdd)

Adds (appends) a route to the end of this route.

Parameters:

rteToAdd - the route to be added to the end of this route.

size

public int size()

Gets the number of RouteNodes in this route.

Returns:

the size of the route.

getIndexOfNode

public int getIndexOfNode(Fix theFix)

Searches for the RouteNode that contains the specified fix.

Parameters:

theFix - the fix

Returns:

Index of the route node; returns -1 if RouteNode is not found.

totalLength

public Distance totalLength()

This gets the length of the route: this is not quite the same as the length of the path an aircraft will take while following the route, since aircraft will cut corners to some extent on turns (based on their turn radius).

See Also:

#routeFollowingDistance(Fix, Fix, Distance)

contains

public boolean contains(Fix theFix)

Returns whether this route contains the specified fix.

Parameters:

theFix - the fix.

Returns:

True if this route contains the specified fix; false otherwise.

containsNode

public boolean containsNode(RouteNode theNode)

Returns whether this route contains the specified route node.

Parameters:

theNode - The RouteNode to find in this Route.

getAlternativeFix

public Fix getAlternativeFix(RouteNode theNode)

Returns the alternative fix for the fix contained in the RouteNode argument. Best to use with Route.containsNode.

Parameters:

theNode - the node

Returns:

alternative Fix for the fix in the RouteNode, or null if none.

compare

public int compare(Fix firstFix,
                   Fix secondFix)

Returns an integer value that is less than zero if firstFix is before secondFix, a value that is greater than zero if firstFix is after the secondFix, or a value that is zero if firstFix is equal to secondFix.

Returns:

Integer value indicating fixes' placement compared to each other.

getRouteNodeIterator

public java.util.Iterator<RouteNode> getRouteNodeIterator()

Returns an Iterator over the RouteNodes in the Route.

getRouteSegmentIterator

public java.util.Iterator<RouteSegment> getRouteSegmentIterator()

Returns an Iterator over the RouteSegments in the Route.

getFirstNode

public RouteNode getFirstNode()

Returns the first RouteNode of this Route.

getLastNode

public RouteNode getLastNode()

Returns the last RouteNode of this Route.

getRouteNodeAt

public RouteNode getRouteNodeAt(int idx)

Returns the RouteNode at the specified index.

Parameters:

idx - the index into the route.

getRouteNodeCount

public int getRouteNodeCount()

Returns the number of RouteNodes in this route.

isEmpty

public boolean isEmpty()

Returns whether this Route is empty (has no route nodes).

Returns:

true if this Route has no RouteNodes; false otherwise.

clone

public Route clone()

Generates a deep copy of the Route.

Overrides:

clone in class java.lang.Object

Returns:

Route a deep copy of the Route.

toDotSepString

public java.lang.String toDotSepString()

Returns a representation of this Route with dots (.) between the fixes.

Returns:

A dot-delimited String representation of this Route.

toSpaceSepString

public java.lang.String toSpaceSepString()

Returns a representation of this Route with spaces between the fixes.

Returns:

A space-delimited String representation of this Route.

toNasString

public java.lang.String toNasString()

Returns the route in nas format Basically fix..fix...

getRouteWithBracketLogic

public java.lang.String getRouteWithBracketLogic()

Returns the route as a dot string with any actions or restrictions in brackets.

toDraText

public java.lang.String toDraText()

Prints DR&A text information to a String.

Specified by:

toDraText in interface TextWritable

Returns:

Returns the DR&A information in string format.

toString

public java.lang.String toString()

Returns a string representation of this Route.

Overrides:

toString in class java.lang.Object

debug

public void debug()

Sends information about a route to the TgMsg.debug() output

determineCaptureSegment

public RouteSegment determineCaptureSegment(Position thePosition)

Determines a RouteSegment to capture on this Route object given a position, satisfying the criteria 1 and 2 in the Lateral Guidance System.

 NOTE: this may not always pick the best/shortest capture segment:
       check whether your results are what you looking for. 

Parameters:

thePosition - is the current position of an object.

Returns:

the capture segment.

Throws:

java.lang.NullPointerException - If first segment of route is null.

determineCaptureSegmentOrRadial

public RouteSegment determineCaptureSegmentOrRadial(Position position)

Determines a RouteSegment to capture on this Route object given a position, satisfying the criteria 1 and 2 in the Lateral Guidance System.

 NOTE: this may not always pick the best/shortest capture segment:
       check whether your results are what you looking for. 

Parameters:

position - is the current position of an object.

Returns:

the capture segment.

Throws:

java.lang.NullPointerException - If first segment of route is null.

detNearestSegment

public RouteSegment detNearestSegment(Position position)

Determines the nearest RouteSegment for capture, satisfying criteria 1 and criteria 2 (See the analysis for the Lateral Guidance System for complete details).

Parameters:

position - Position to find the nearest RouteSegment to.

Returns:

Nearest segment to aircraft or null if first segment is null.

detNearestSegmentOrRadial

public RouteSegment detNearestSegmentOrRadial(Position position)

Determines the nearest RouteSegment for capture, satisfying criteria 1 and criteria 2 (See the analysis for the Lateral Guidance System for complete details).

 NOTE: If the Route is a RouteWEndRadial, this will also check the
       end radial segment. Uses next() to iterate through the segments,
       not the routeSegment iterator.  

Parameters:

position - Position to find the nearest RouteSegment to.

Returns:

Nearest segment to aircraft or null if first segment is null.

calcMinDistanceToTrailingFix

public RouteSegment calcMinDistanceToTrailingFix(Position position)

Returns the RouteSegment of this Route that has the trailing fix that is closest to the given Position.

Parameters:

position - the position given.

isRestricted

public boolean isRestricted()

validWithNavigationLimits

public java.lang.String validWithNavigationLimits(boolean enforce,
                                                  AcType type)

Returns whether an an aircraft could follow its route if it was forced to obey the limitations of its navigation equipment.

Parameters:

enforce - - whether to enforce equipment restrictions

type - - the aircraft's type

Returns:

Returns what if any part of the route an aircraft should not be able to follow.

validFix

private boolean validFix(boolean enforce,
                         Fix fix,
                         AircraftEquipment equip)

Returns whether a fix is valid

Parameters:

enforce - - whether to enforce equipment restrictions

fix - - the fix

equip - - the aircraft's equipment

routeFollowingDistance

public Distance routeFollowingDistance(Fix startFix,
                                       Fix endFix,
                                       Distance turnRadius)

This gets the length of the route as followed by the aircraft: this distance calculation is generally shorter than Route.totalLength() because most turns (on the segment changes) will shorten the path.

If the aircraft turn radius changes, the route length will also change.

Parameters:

startFix - The start fix on the route to find the distance for.

endFix - The end fix on the route to find the distance for.

turnRadius - The turn radius of the aircraft following the route.

Returns:

Returns the estimated track distance for the aircraft.

Throws:

java.lang.IllegalArgumentException - Start fix not found in route.

restrictionCaptureTest

public void restrictionCaptureTest(Route.DescentCapturePredictor predictor)
                            throws UnableToComplyException

Do route validation on altitude restrictions.

Throws:

UnableToComplyException

main

public static final void main(java.lang.String[] args)