msim.model

Class Path

java.lang.Object

msim.model.Path

public class Path
extends java.lang.Object

A tree path in the MSim model.

Paths do not directly reference objects in the tree, but rather contain a sequence of names or identifiers that can later be used to resolve the path in any particular tree. Paths are immutable.

In general, a path has the form [linkages][nodes]([widget[geometry]]|[subframe]), where linkages is a sequence of zero or more Linkages separated by periods, nodes is a sequence of zero or more LinkageNode names separated by periods, widget is the name of a Widget within a particular LinkageNode, geometry is the integer index of a Geometry within a particular Widget, and subframe is the name of a subframe within the last-referenced node.

A path can be resolved either in the context of an entire Linkage (resolve(Linkage)), or in the context of a specific LinkageNode (resolve(LinkageNode)) or Widget (resolve(Widget)).

Copyright (C) 2008 Marsette A. Vona, III

Author:

Marsette A. Vona, III

Field Summary

Fields

Modifier and Type	Field and Description
private static java.lang.String	cvsid
protected java.lang.String[]	elt path elements
static java.lang.String	SEPARATOR the path separator string
static java.lang.String	SEPARATOR_REGEX regex string matching SEPARATOR

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Path(java.lang.String... elements) make a Path from a list of elements, by copy

Method Summary

Methods

Modifier and Type	Method and Description
void	dump() dump(PrintStream) to System.out
void	dump(java.io.PrintStream s) similar to toString()
static void	dumpPathOf(javax.media.j3d.Geometry geometry) dumpPathOf(Geometry, PrintStream) to System.out
static void	dumpPathOf(javax.media.j3d.Geometry geometry, java.io.PrintStream s) Like pathOf(Geometry) then dump(PrintStream), but with less thrashing.
static void	dumpPathOf(Linkage linkage) dumpPathOf(Linkage, PrintStream) to System.out
static void	dumpPathOf(LinkageNode.SubFrame subframe) dumpPathOf(msim.model.LinkageNode.SubFrame, PrintStream) to System.out
static void	dumpPathOf(LinkageNode.SubFrame subframe, java.io.PrintStream s) Like pathOf(msim.model.LinkageNode.SubFrame) then dump(PrintStream), but with less thrashing.
static void	dumpPathOf(LinkageNode node) dumpPathOf(LinkageNode, PrintStream) to System.out
static void	dumpPathOf(LinkageNode node, java.io.PrintStream s) Like pathOf(LinkageNode) then dump(PrintStream), but with less thrashing.
static void	dumpPathOf(LinkageNode node, java.lang.String subframe) covers dumpPathOf(msim.model.LinkageNode.SubFrame)
static void	dumpPathOf(LinkageNode node, java.lang.String subframe, java.io.PrintStream s) Covers dumpPathOf(msim.model.LinkageNode.SubFrame, PrintStream).
static void	dumpPathOf(Linkage linkage, java.io.PrintStream s) Like pathOf(Linkage) then dump(PrintStream), but with less thrashing.
static void	dumpPathOf(vona.j3d.Widget widget) dumpPathOf(Widget, PrintStream) to System.out
static void	dumpPathOf(vona.j3d.Widget widget, java.io.PrintStream s) Like pathOf(Widget) then dump(PrintStream), but with less thrashing.
java.lang.String	getElement(int i) return a String version of path element i
int	length() get the length of this path
static Path	parse(java.lang.String path) Split a single path string at all instances of SEPARATOR, and then make a new Path from the resulting sequence.
static Path	pathOf(javax.media.j3d.Geometry geometry) Extract the path leading to geometry.
static Path	pathOf(Linkage linkage) Extract the path leading to linkage.
static Path	pathOf(LinkageNode.SubFrame subframe) Extract the path leading to subframe.
static Path	pathOf(LinkageNode node) Extract the path leading to node.
static Path	pathOf(LinkageNode node, java.lang.String subframe) covers pathOf(msim.model.LinkageNode.SubFrame)
static Path	pathOf(vona.j3d.Widget widget) Extract the path leading to widget.
protected static Path	pathOfOrDump(javax.media.j3d.Geometry geometry, java.io.PrintStream s) Common impl of pathOf(Geometry) and dumpPathOf(Geometry, PrintStream).
protected static Path	pathOfOrDump(LinkageNode.SubFrame subframe, java.io.PrintStream s) Common impl of pathOf(msim.model.LinkageNode.SubFrame) and dumpPathOf(msim.model.LinkageNode.SubFrame, PrintStream).
protected static Path	pathOfOrDump(LinkageNode node, java.io.PrintStream s) Covers pathOfOrDump(LinkageNode, PrintStream, int), no extra suffix elements.
protected static Path	pathOfOrDump(LinkageNode node, java.io.PrintStream s, int extraSuffixElements) Common impl of pathOf(LinkageNode) and dumpPathOf(LinkageNode, PrintStream).
protected static Path	pathOfOrDump(Linkage linkage, java.io.PrintStream s) Covers pathOfOrDump(Linkage, PrintStream, int), no extra suffix elements.
protected static Path	pathOfOrDump(Linkage linkage, java.io.PrintStream s, int extraSuffixElements) Common impl of pathOf(Linkage) and dumpPathOf(Linkage, PrintStream).
protected static Path	pathOfOrDump(vona.j3d.Widget widget, java.io.PrintStream s) Covers pathOfOrDump(Widget, PrintStream, int), no extra suffix elements.
protected static Path	pathOfOrDump(vona.j3d.Widget widget, java.io.PrintStream s, int extraSuffixElements) Common impl of pathOf(Widget) and dumpPathOf(Widget, PrintStream).
java.lang.Object	resolve() resolve(Linkage) in the top-level Linkage
java.lang.Object	resolve(int fromElement) resolve(LinkageNode, int), from the ultimate ground
java.lang.Object	resolve(Linkage linkage) Resolve this Path in linkage.
java.lang.Object	resolve(LinkageNode fromNode) resolve(LinkageNode, int), starts at name 0
java.lang.Object	resolve(LinkageNode fromNode, int fromElement) Resolve this Path starting at a particular name under a particular LinkageNode.
java.lang.Object	resolve(vona.j3d.Widget fromWidget) covers resolve(Widget, int), starts at name 0
java.lang.Object	resolve(vona.j3d.Widget fromWidget, int fromElement) Resolve this Path starting at a particular name under a particular Widget.
java.lang.String	toString() Get the entire path as a flat string, with each element separated by SEPARATOR.
java.lang.String	toString(int upToElement) Get the path up to and including upToElement as a flat string, with each element separated by SEPARATOR.

Methods inherited from class java.lang.Object

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

Field Detail

cvsid

private static final java.lang.String cvsid

See Also:

Constant Field Values

SEPARATOR

public static final java.lang.String SEPARATOR

the path separator string

See Also:

Constant Field Values

SEPARATOR_REGEX

public static final java.lang.String SEPARATOR_REGEX

regex string matching SEPARATOR

See Also:

Constant Field Values

elt

protected final java.lang.String[] elt

path elements

Constructor Detail

Path

protected Path(java.lang.String... elements)

make a Path from a list of elements, by copy

Method Detail

parse

public static Path parse(java.lang.String path)

Split a single path string at all instances of SEPARATOR, and then make a new Path from the resulting sequence.

pathOf

public static Path pathOf(Linkage linkage)

Extract the path leading to linkage.

If linkage is the top-level linkage, then a length-one path with its name is returned. Else the path is the sequence of linkage names up to but not including the top-level linkage.

dumpPathOf

public static void dumpPathOf(Linkage linkage,
              java.io.PrintStream s)

Like pathOf(Linkage) then dump(PrintStream), but with less thrashing.

dumpPathOf

public static void dumpPathOf(Linkage linkage)

dumpPathOf(Linkage, PrintStream) to System.out

pathOfOrDump

protected static Path pathOfOrDump(Linkage linkage,
                java.io.PrintStream s,
                int extraSuffixElements)

Common impl of pathOf(Linkage) and dumpPathOf(Linkage, PrintStream).

Parameters:

s - if non-null then the path is dumped here, and null is returned

extraSuffixElements - this many extra trailing un-initialized path elements will be included in the returned Path

Returns:

if s is null, the Path is returned, else return is null

pathOfOrDump

protected static Path pathOfOrDump(Linkage linkage,
                java.io.PrintStream s)

Covers pathOfOrDump(Linkage, PrintStream, int), no extra suffix elements.

pathOf

public static Path pathOf(LinkageNode node)

Extract the path leading to node.

This begins with the sequence of containing Linkages, iff more than one. Normally, the path will continue with the ancestor root Link (a Link whose parent is a RootJoint), or the first ancestor LinkageNode with a null parent. Passing a RootJoint or ground Link as node are special cases: in those cases the returned path will contain only node.

dumpPathOf

public static void dumpPathOf(LinkageNode node,
              java.io.PrintStream s)

Like pathOf(LinkageNode) then dump(PrintStream), but with less thrashing.

dumpPathOf

public static void dumpPathOf(LinkageNode node)

dumpPathOf(LinkageNode, PrintStream) to System.out

pathOfOrDump

protected static Path pathOfOrDump(LinkageNode node,
                java.io.PrintStream s,
                int extraSuffixElements)

Common impl of pathOf(LinkageNode) and dumpPathOf(LinkageNode, PrintStream).

Parameters:

s - if non-null then the path is dumped here, and null is returned

extraSuffixElements - this many extra trailing un-initialized path elements will be included in the returned Path

Returns:

if s is null, the Path is returned, else return is null

pathOfOrDump

protected static Path pathOfOrDump(LinkageNode node,
                java.io.PrintStream s)

Covers pathOfOrDump(LinkageNode, PrintStream, int), no extra suffix elements.

pathOf

public static Path pathOf(vona.j3d.Widget widget)

Extract the path leading to widget.

The path will end at a root Link (a Link whose parent is a RootJoint), or the first LinkageNode with a null parent.

dumpPathOf

public static void dumpPathOf(vona.j3d.Widget widget,
              java.io.PrintStream s)

Like pathOf(Widget) then dump(PrintStream), but with less thrashing.

dumpPathOf

public static void dumpPathOf(vona.j3d.Widget widget)

dumpPathOf(Widget, PrintStream) to System.out

pathOfOrDump

protected static Path pathOfOrDump(vona.j3d.Widget widget,
                java.io.PrintStream s,
                int extraSuffixElements)

Common impl of pathOf(Widget) and dumpPathOf(Widget, PrintStream).

Parameters:

s - if non-null then the path is dumped here, and null is returned

extraSuffixElements - this many extra trailing un-initialized path elements will be included in the returned Path

Returns:

if s is null, the Path is returned, else return is null

pathOfOrDump

protected static Path pathOfOrDump(vona.j3d.Widget widget,
                java.io.PrintStream s)

Covers pathOfOrDump(Widget, PrintStream, int), no extra suffix elements.

pathOf

public static Path pathOf(javax.media.j3d.Geometry geometry)

Extract the path leading to geometry.

The path will end at a root Link (a Link whose parent is a RootJoint), or the first LinkageNode or Widget with a null parent.

dumpPathOf

public static void dumpPathOf(javax.media.j3d.Geometry geometry,
              java.io.PrintStream s)

Like pathOf(Geometry) then dump(PrintStream), but with less thrashing.

dumpPathOf

public static void dumpPathOf(javax.media.j3d.Geometry geometry)

dumpPathOf(Geometry, PrintStream) to System.out

pathOfOrDump

protected static Path pathOfOrDump(javax.media.j3d.Geometry geometry,
                java.io.PrintStream s)

Common impl of pathOf(Geometry) and dumpPathOf(Geometry, PrintStream).

Parameters:

s - if non-null then the path is dumped here, and null is returned

Returns:

if s is null, the Path is returned, else return is null

pathOf

public static Path pathOf(LinkageNode.SubFrame subframe)

Extract the path leading to subframe.

The path will end at a root Link (a Link whose parent is a RootJoint), or the first LinkageNode or Widget with a null parent.

pathOf

public static Path pathOf(LinkageNode node,
          java.lang.String subframe)

covers pathOf(msim.model.LinkageNode.SubFrame)

dumpPathOf

public static void dumpPathOf(LinkageNode.SubFrame subframe,
              java.io.PrintStream s)

Like pathOf(msim.model.LinkageNode.SubFrame) then dump(PrintStream), but with less thrashing.

dumpPathOf

public static void dumpPathOf(LinkageNode node,
              java.lang.String subframe,
              java.io.PrintStream s)

Covers dumpPathOf(msim.model.LinkageNode.SubFrame, PrintStream).

dumpPathOf

public static void dumpPathOf(LinkageNode.SubFrame subframe)

dumpPathOf(msim.model.LinkageNode.SubFrame, PrintStream) to System.out

dumpPathOf

public static void dumpPathOf(LinkageNode node,
              java.lang.String subframe)

covers dumpPathOf(msim.model.LinkageNode.SubFrame)

pathOfOrDump

protected static Path pathOfOrDump(LinkageNode.SubFrame subframe,
                java.io.PrintStream s)

Common impl of pathOf(msim.model.LinkageNode.SubFrame) and dumpPathOf(msim.model.LinkageNode.SubFrame, PrintStream).

Parameters:

s - if non-null then the path is dumped here, and null is returned

Returns:

if s is null, the Path is returned, else return is null

toString

public java.lang.String toString()

Get the entire path as a flat string, with each element separated by SEPARATOR.

Overrides:

toString in class java.lang.Object

toString

public java.lang.String toString(int upToElement)

Get the path up to and including upToElement as a flat string, with each element separated by SEPARATOR.

dump

public void dump(java.io.PrintStream s)

similar to toString()

dump

public void dump()

dump(PrintStream) to System.out

getElement

public java.lang.String getElement(int i)

return a String version of path element i

length

public int length()

get the length of this path

resolve

public java.lang.Object resolve(Linkage linkage)

Resolve this Path in linkage.

Returns the Linkage.groundLink iff this Path is zero-length or if it contains only the name of the ground link.

First, any Linkage name sequence prefix is consumed, possibly modifying the context linkage. Then, if the next element of this Path matches a child of the Linkage.groundLink, resolution continues there. Otherwise, if the next element of this Path matches a root Link (i.e. a Link attached to the Linkage.groundLink through its Link.rootJoint), the Path is resolved continuing at that root Link. Finally, if the next element of this Path matches a the name of a Widget of the ground link, the Path is resolved continuing at that Widget.

Parameters:

linkage - the linkage in which to resolve, if null then use the top-level Linkage returned from MSim.getLinkage()

Returns:

the resolved LinkageNode, Widget, or Geometry, LinkageNode.SubFrame, or null if not found

resolve

public java.lang.Object resolve()

resolve(Linkage) in the top-level Linkage

resolve

public java.lang.Object resolve(LinkageNode fromNode,
                       int fromElement)

Resolve this Path starting at a particular name under a particular LinkageNode.

Parameters:

fromNode - the first name is resolved as a child of this node, if null then use the ultimate ground Link returned from MSim.getUltimateGroundLink()

fromElement - the index of the first path element to resolve, if geq the total number of elements in this path then fromNode is returned directly

Returns:

the resolved LinkageNode, Widget, or Geometry, LinkageNode.SubFrame, or null if not found

resolve

public java.lang.Object resolve(LinkageNode fromNode)

resolve(LinkageNode, int), starts at name 0

resolve

public java.lang.Object resolve(int fromElement)

resolve(LinkageNode, int), from the ultimate ground

resolve

public java.lang.Object resolve(vona.j3d.Widget fromWidget,
                       int fromElement)

Resolve this Path starting at a particular name under a particular Widget.

Parameters:

fromWidget - the first name is resolved as a child of this Widget

fromElement - the index of the first path element to resolve, if geq the total number of elements in this path then fromWidget is returned directly

Returns:

the resolved Widget or Geometry, or null if not found

resolve

public java.lang.Object resolve(vona.j3d.Widget fromWidget)

covers resolve(Widget, int), starts at name 0