com.kuka.geometry
Class QueryConnectionChain

java.lang.Object
  com.kuka.geometry.QueryConnectionChain

public final class QueryConnectionChain
extends Object

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

This class provides the transformation of a connection chain no matter what kind of connections are part of the chain. Its instances usually are very short lived: Typically, you create an instance of this class for an immediate call to one or more of the public (getter) methods and then let the garbage collector collect the instance.

If multiple connections along the chain are of type IQueryConnection and their respective ITrafoQueryProcessors are equal, the transformations for these connections are queried with exactly one call to ITrafoQueryProcessor.processQuery(Collection, List, Object).

If multiple connections along the chain are of type IQueryConnection with differing ITrafoQueryProcessors, this class implements a parallel transformation query mechanism spawning new threads using Executors.newCachedThreadPool().

Constructor Summary

QueryConnectionChain(ConnectionChain chain)
Creates a new query connection instance from a ConnectionChain.

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

Method Summary

Transformation	getTransformation() This method calculates the transformation from source frame to target frame.
Transformation	getTransformation(QueryType queryType) This method calculates the transformation from source frame to target frame using the following methods: For each ITransformationConnection, ITransformationConnection.getTransformationFromParent() will be used in the calculation.
Map<QueryType,Transformation>	getTransformations(Collection<? extends QueryType> queryTypes, Object queryContext) This method calculates the transformation from source frame to target frame for each of the given QueryTypes, using the following methods: For each ITransformationConnection, ITransformationConnection.getTransformationFromParent() will be used in the calculation.
boolean	isStatic()

Methods inherited from class java.lang.Object

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

Constructor Detail

QueryConnectionChain

public QueryConnectionChain(Frame source,
                            Frame target)

Creates a new query connection instance from a source frame to a target frame. If the frames are not connected, the query methods other than isStatic() 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 transformation. If the frame tree is modified in the meantime, the calculated transformations like contain invalid (outdated) values.

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 Frame s 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. If null, the top-level parent frame will be used as source.

target - the target of the connection. If null, the top-level parent frame will be used as target.

Throws:

IllegalArgumentException - if both arguments are null

IllegalStateException - if an unknown IFrameConnection is found

QueryConnectionChain

public QueryConnectionChain(ConnectionChain chain)

Creates a new query connection instance from a ConnectionChain. If the chain are not connected, the query methods other than isStatic() 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 transformation. If the frame tree is modified in the meantime, the calculated transformations like contain invalid (outdated) values.

Parameters:

chain - the connection chain.

Throws:

IllegalArgumentException - if the arguments is null

IllegalStateException - if an unknown IFrameConnection is found

Method Detail

isStatic

public boolean isStatic()

Returns:

true, source frame and target frame are connected exclusively by StaticConnections.

getTransformation

public Transformation getTransformation()
                                 throws TrafoQueryException

This method calculates the transformation from source frame to target frame. This is the spatial location of the target frame in the source frame's coordinate system.

This method calls getTransformation(QueryType) with the argument value null.

Returns:

the transformation of the given type, expressed in the coordinate system of the source frame, as given to this class' constructor.

Throws:

ThreadInterruptedException - if the thread was interrupted during execution. The thread interrupt flag will be set if the thread was interrupted (that is, Thread.isInterrupted() will return true)

TrafoQueryException - if a frame connection could not be queried for the current transformation

See Also:

getTransformation(QueryType)

getTransformation

public Transformation getTransformation(QueryType queryType)
                                 throws TrafoQueryException

This method calculates the transformation from source frame to target frame using the following methods:

• For each ITransformationConnection, ITransformationConnection.getTransformationFromParent() will be used in the calculation.
• For each IQueryConnection, the corresponding ITrafoQueryProcessor will be queried in the way described in the class description for the connection's current transformation of the given QueryType.
• Other connection types are not recognized and result in an exception.

Parameters:

queryType - the type of transformation to query from the sensors. The query type must be a value that all query processors support, possibly including the null value.

Returns:

the transformation of the given type, expressed in the coordinate system of the source frame, as given to this class' constructor.

Throws:

ThreadInterruptedException - if the thread was interrupted during execution. The thread interrupt flag will be set if the thread was interrupted (that is, Thread.isInterrupted() will return true)

TrafoQueryException - if querying a connection's transformation failed (the first occurrence will be found in the Throwable.getCause())

IllegalStateException - if an unknown IFrameConnection is found

getTransformations

public Map<QueryType,Transformation> getTransformations(Collection<? extends QueryType> queryTypes,
                                                        Object queryContext)
                                                 throws TrafoQueryException

This method calculates the transformation from source frame to target frame for each of the given QueryTypes, using the following methods:

• For each ITransformationConnection, ITransformationConnection.getTransformationFromParent() will be used in the calculation.
• For each IQueryConnection, the corresponding ITrafoQueryProcessor.processQuery(Collection, List, Object) method will be called.
• Other connection types are not recognized and result in an exception.

Parameters:

queryTypes - a collection of QueryTypes that will be passed to the ITrafoQueryProcessors, if any IQueryConnections are present in the connection chain. The collection may only contain values that all query processors support, possibly including the null value.

queryContext - an arbitrary object that will be passed to the ITrafoQueryProcessor.processQuery(Collection, List, Object) method of each query processor present in the connection chain. May be null.

Returns:

a map containing an ITransformation for each distinct value of the given query types. The transformations are expressed in the coordinate system of the source frame, as given to this class' constructor.

Throws:

ThreadInterruptedException - if the thread was interrupted during execution. The thread interrupt flag will be set if the thread was interrupted (that is, Thread.isInterrupted() will return true)

TrafoQueryException - if querying a connection's transformation failed (the first occurrence will be found in the Throwable.getCause())

IllegalStateException - if an unknown IFrameConnection is found, or if the frames given in the constructor have no connection