com.kuka.geometry
Class ConnectionChain

java.lang.Object
  com.kuka.geometry.ConnectionChain

All Implemented Interfaces:

Iterable<IFrameConnection>

public final class ConnectionChain
extends Object
implements Iterable<IFrameConnection>

Represents a directed connection chain between two frames connected through the frame tree.

Nested Class Summary

class

ConnectionChain.ConnectionIterator An iterator over the connections of a ConnectionChain.

Constructor Summary

ConnectionChain(Frame source, Frame target)
Creates a new connection instance from a source frame to a target frame.

Method Summary

Frame	getRoot()
Frame	getSource() Returns the frame that was given to the constructor as source, or the root frame if null was given.
Frame	getTarget() Returns the frame that was given to the constructor as target, or the root frame if null was given.
boolean	isConnected()
ConnectionChain.ConnectionIterator	iterator() Returns an iterator over the frame connections from source (as returned by getSource()) to target (as returned by getTarget()).
int	size()

Methods inherited from class java.lang.Object

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

Constructor Detail

ConnectionChain

public ConnectionChain(Frame source,
                       Frame target)

Creates a new connection instance from a source frame to a target frame. You can check if the frames are connected through the frame tree by using the isConnected() method. If the frames are not connected, the query methods other than getSource() and getTarget() will throw an exception.

Caution: The caller should make sure that the frame tree is not modified between creating an instance of this class and calling the methods that query the connection.

This methods locks both the frame tree of the source frame and the frame tree of the target frame during the creation of the connection chain using the lock returned by Frame.getFrameTreeLock(). If the Frames that are passed in are thread safe (e.g. ObjectFrames), the frame tree traversal is guaranteed to be thread safe. Otherwise, if the implementation is not thread safe (e.g. LocalFrame), thread safety will have to be taken care of by the caller.

Parameters:

source - the source of the connection. Can be queried later by getSource(). If null, the top-level parent frame will be used as source.

target - the target of the connection. Can be queried later by getTarget(). If null, the top-level parent frame will be used as target.

Throws:

IllegalArgumentException - if both arguments are null

Method Detail

isConnected

public boolean isConnected()

Returns:

true if a connection between the frames given in the constructor was found, false otherwise.

getSource

public Frame getSource()

Returns the frame that was given to the constructor as source, or the root frame if null was given.

Returns:

the connection's source frame. Never null.

getTarget

public Frame getTarget()

Returns the frame that was given to the constructor as target, or the root frame if null was given.

Returns:

the connection's target frame. Never null.

getRoot

public Frame getRoot()

Returns:

the first common ancestor frame reachable by the source and the target frame (this might be either the source frame, the target frame or another frame). If no connection was found, null is returned.

See Also:

isConnected()

iterator

public ConnectionChain.ConnectionIterator iterator()

Returns an iterator over the frame connections from source (as returned by getSource()) to target (as returned by getTarget()). If the frames are not connected, the iterator will have no elements.

The iterator will be of type ConnectionChain.ConnectionIterator, which provides the method ConnectionChain.ConnectionIterator.isNextUp(). This method will return true while the iteration is on the path upwards from source to the root frame, and false if on the path from root to target.

Specified by:

iterator in interface Iterable<IFrameConnection>

Returns:

an iterator

size

public int size()

Returns:

the number of connections in the chain. If the chain is not connected (see isConnected()), the number of connection is 0.