com.kuka.roboticsAPI
Class RoboticsAPIContext

java.lang.Object
  com.kuka.roboticsAPI.RoboticsAPIContext

All Implemented Interfaces:

IFinalizableObject

Direct Known Subclasses:

RoboticsAPILazyDeviceContext

public class RoboticsAPIContext
extends Object
implements IFinalizableObject

Main entry point for the RoboticsAPI. Provides access to Controllers and engines.

A context is created through a configuration URL which contains information about the configured controller and engines. Only if the defaultContext is chosen, the configuration URL is not set and therefore the 'getConfigurationFile' method will return null.

Context creation is an expensive operation. Your application should need in most cases only one context during it's life-cycle. If a context pointing to the same configuration URL is created twice, the other context will get disposed.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

Field Summary

protected Map<String,Controller>	_controllers The list of controllers.
static String	DEFAULT_FILE_NAME Default name of the robotics api configuration file.

Constructor Summary

protected

RoboticsAPIContext(Class<?> applicationContext, URL configFile) Creates a new context instance.

Method Summary

static void	addContextListener(IContextListener listener) Registers a listener for context events.
boolean	containsController(String name) Checks if a controller is contained in the context.
<T extends IEngine> boolean	containsEngine(Class<T> clazz) Determines if an engine type is loaded in this context.
static RoboticsAPIContext	create() Creates a new RoboticsAPIContext out of the config file which is located on the default package scope.
static RoboticsAPIContext	create(Class<?> applicationContext) Creates a new RoboticsAPIContext out of the config file which is located on the default package scope.
protected Controller	createController(com.kuka.common.ParameterSet description) Creates a controller instance.
static RoboticsAPIContext	createDefaultContext() Creates a default context with the default engines and the MockController inside.
static RoboticsAPIContext	createFromFile(Class<?> applicationContext, File configFile) Creates a new RoboticsAPIContext out of the given config file.
static RoboticsAPIContext	createFromFile(File configFile) Creates a new RoboticsAPIContext out of the given config file.
static RoboticsAPIContext	createFromResource(Class<?> applicationContext, String resourceName) Creates a new RoboticsAPIContext out of the given configuration file.
static RoboticsAPIContext	createFromResource(String resourceName) Creates a new RoboticsAPIContext out of the given configuration file.
static RoboticsAPIContext	createFromURL(Class<?> applicationContext, URL configURL) Creates a new RoboticsAPIContext out of the given config URL.
Object	createInstance(String fqcn, Class<?>[] types, Object... parameters) Creates an instance of the given class.
void	dispose() Disposes this context and all included resources.
void	dumpDevices() Debug Routine for displaying the installed devices from all controllers.
void	finalizeObject() Do finalization (cleanup) actions here.
Class<?>	getApplicationClass() Returns the application context from which the context was created.
URL	getConfigurationFile() Returns the configuration file to which this context is bound.
Controller	getController(String controllerName) Gets the controller with the specified name.
IControllerInitializeBehaviour	getControllerInitializeBehavior() Gets the initialization behavior of the controller.
Collection<Controller>	getControllers() Returns the controllers loaded in this context.
Controller	getDefaultController() Returns the first available controller or throws an exception if none is found.
IDeviceFactory	getDeviceFactory() Gets the device factory of this context.
Device	getDeviceFromName(String deviceName) Gets the device with the given name from the default controller.
Device	getDeviceFromName(String controllerName, String deviceName) Gets the device with the given name on the given controller.
<T extends Device> T	getDeviceFromType(Class<T> deviceClass) Gets the first device with the given type from the default controller.
<T extends IEngine> T	getEngine(Class<T> clazz) Gets the engine of the given type, if available.
Map<String,com.kuka.common.ParameterSet>	getInvalidControllers() Gets the controllers which are invalid due to an initialization error.
Iterable<com.kuka.common.ParameterSet>	getInvalidEngines() Gets the engines which are invalid due to an initialization error.
ISyncManager	getSyncManager() Gets the sync manager of this context.
void	initialize() Initializes this RoboticsAPIContext.
boolean	isInitialized() Indicates if this context is initialized.
Class<?>	loadClass(String className) Loads a class through a given context.
protected Controller	loadControllers(Iterable<com.kuka.common.ParameterSet> descriptions, Map<String,Controller> controllers, Map<String,com.kuka.common.ParameterSet> invalidControllers) Loads all controllers from the parameter set descriptions.
void	registerEngine(IEngine engine) Registers engine programmatically.
static void	removeContextListener(IContextListener listener) Unregisters a listener from context events.
URL	resolve(String resourceName) Resolves a resource within the system.
protected void	setFirstController(Controller controller) sets the first controller.
String	toString()
<T extends IEngine> T	tryGetEngine(Class<T> clazz) Gets the engine of the given type.
URL	tryResolve(String resourceName) Resolves a resource within the system.
static void	useGracefulInitialization(boolean value) If set to true, this flag indicates if the context initialization will continue even if a engine or controller was not created.
static boolean	usingGracefulInitialization() Gets the flag which indicates if graceful initialization is activated.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_FILE_NAME

public static final String DEFAULT_FILE_NAME

Default name of the robotics api configuration file.

See Also:

Constant Field Values

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

_controllers

protected final Map<String,Controller> _controllers

The list of controllers.

Constructor Detail

RoboticsAPIContext

protected RoboticsAPIContext(Class<?> applicationContext,
                             URL configFile)

Creates a new context instance.

Parameters:

applicationContext - The application context. Can be null.

configFile - The configuration file. Can be null.

Method Detail

useGracefulInitialization

public static void useGracefulInitialization(boolean value)

If set to true, this flag indicates if the context initialization will continue even if a engine or controller was not created.

Parameters:

value - The flag for the graceful initialization.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

usingGracefulInitialization

public static boolean usingGracefulInitialization()

Gets the flag which indicates if graceful initialization is activated.

Returns:

True if graceful initialization is activated.

See Also:

useGracefulInitialization(boolean)

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

addContextListener

public static void addContextListener(IContextListener listener)

Registers a listener for context events.

Parameters:

listener - The listener.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

removeContextListener

public static void removeContextListener(IContextListener listener)

Unregisters a listener from context events.

Parameters:

listener - The listener.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

setFirstController

protected void setFirstController(Controller controller)

sets the first controller.

Parameters:

controller - the first controller to set.

loadControllers

protected Controller loadControllers(Iterable<com.kuka.common.ParameterSet> descriptions,
                                     Map<String,Controller> controllers,
                                     Map<String,com.kuka.common.ParameterSet> invalidControllers)

Loads all controllers from the parameter set descriptions.

Parameters:

descriptions - The set of descriptions. The "Class"-Attribute describes the type of the controller, the "Name" attribute the name.

controllers - The map in which the created controllers should get added.

invalidControllers - The map in which invalid controllers should get added (if graceful initialization is on).

Returns:

The first created controller which will be the default controller for the context.

createController

protected final Controller createController(com.kuka.common.ParameterSet description)

Creates a controller instance.

Parameters:

description - The controller description. The "Class"-Attribute describes the type of the controller, the "Name" attribute the name.

Returns:

the controller instance.

registerEngine

public void registerEngine(IEngine engine)

Registers engine programmatically.

If engine with the same type is already registered it will be replaced with the specified engine.

Parameters:

engine - engine to register.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

getConfigurationFile

public URL getConfigurationFile()

Returns the configuration file to which this context is bound. If this is the default context, null is returned by this method.

Returns:

The configuration file to which this context is bound. If this is the default context, null is returned by this method.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

toString

public String toString()

Overrides:

toString in class Object

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

getDeviceFromName

public Device getDeviceFromName(String controllerName,
                                String deviceName)

Gets the device with the given name on the given controller. If no such controller or device is found, this method throws an exception.

Parameters:

controllerName - The controller name.

deviceName - The name of the device.

Returns:

The device with the given name on the specified controller.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

getDeviceFromName

public Device getDeviceFromName(String deviceName)

Gets the device with the given name from the default controller. If no device is found, all other controllers are checked and if no device is known afterwards, this method throws an exception.

Devices with the same name on different controllers are not handled by this method. This method just returns the first found device with the given name.

This method is a convenience method for the call deviceFromType(null, deviceName).

Parameters:

deviceName - The name of the device.

Returns:

The device with the given name.

Throws:

RequestedResourceNotAvailable - if device with the specified name does not exists.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

getDeviceFromType

public <T extends Device> T getDeviceFromType(Class<T> deviceClass)

Gets the first device with the given type from the default controller. If no device is found, all other controllers are checked and if no device is known afterwards, this method throws an exception.

Devices with the same type on different controllers are not handled by this method. This method just returns the first found device with the given type.

Type Parameters:

T - The type of the device.

Parameters:

deviceClass - The device class.

Returns:

The first found device with the given type on the default controller.

Throws:

IllegalArgumentException - if device of the specified type does not exists.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

getControllers

public Collection<Controller> getControllers()

Returns the controllers loaded in this context.

Returns:

The controllers loaded in this context.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

getController

public Controller getController(String controllerName)

Gets the controller with the specified name. Throws an exception if controller is not found.

Parameters:

controllerName - The name of the controller

Returns:

The controller with the specified name.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

containsController

public boolean containsController(String name)

Checks if a controller is contained in the context.

Parameters:

name - The name of the controller.

Returns:

True if the controller is contained in the context.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

getDefaultController

public Controller getDefaultController()

Returns the first available controller or throws an exception if none is found.

Returns:

The first available controller.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

getApplicationClass

public Class<?> getApplicationClass()

Returns the application context from which the context was created. This is the optional parameter which is passed to the context during creation. If no class was given, the RoboticsAPIContext class itself will be returned by this method.

Returns:

The application context class. May be null, depending on how the context was created.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

getInvalidControllers

public Map<String,com.kuka.common.ParameterSet> getInvalidControllers()

Gets the controllers which are invalid due to an initialization error. The read-only map contains the controller names and their attributes, including the error message (available under the key 'ErrorMessage').

Returns:

The controllers which are invalid.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

getInvalidEngines

public Iterable<com.kuka.common.ParameterSet> getInvalidEngines()

Gets the engines which are invalid due to an initialization error. The read-only list contains the engine attributes, including the error message (available under the key 'ErrorMessage').

Returns:

The engines which are invalid.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

getSyncManager

public ISyncManager getSyncManager()

Gets the sync manager of this context.

Returns:

The sync manager of this context.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

getDeviceFactory

public IDeviceFactory getDeviceFactory()

Gets the device factory of this context.

Returns:

The device factory of this context.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

containsEngine

public <T extends IEngine> boolean containsEngine(Class<T> clazz)

Determines if an engine type is loaded in this context.

Type Parameters:

T - The type of the engine.

Parameters:

clazz - The type of the engine.

Returns:

True if the engine is loaded.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

getEngine

public <T extends IEngine> T getEngine(Class<T> clazz)

Gets the engine of the given type, if available.

Type Parameters:

T - The type of the engine.

Parameters:

clazz - The type of the engine.

Returns:

The engine known under the current type. Not null.

Throws:

IllegalArgumentException - if clazz is null, or engine of the requested type not found

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

tryGetEngine

public <T extends IEngine> T tryGetEngine(Class<T> clazz)

Gets the engine of the given type.

Type Parameters:

T - The type of the engine.

Parameters:

clazz - The type of the engine.

Returns:

The engine known under the current type, or null if no such engine could be found.

Throws:

IllegalArgumentException - if clazz is null

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

isInitialized

public boolean isInitialized()

Indicates if this context is initialized.

Returns:

True if this context is initialized.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

initialize

public void initialize()

Initializes this RoboticsAPIContext. Dispose will be automatically called before a new initialize will occur.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

loadClass

public Class<?> loadClass(String className)

Loads a class through a given context. Fails if class was not loaded.

Parameters:

className - The name of the class.

Returns:

The loaded class.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

createInstance

public Object createInstance(String fqcn,
                             Class<?>[] types,
                             Object... parameters)

Creates an instance of the given class.

Parameters:

fqcn - The full qualified class name.

types - The classes the are needed by the constructor.

parameters - The parameters for the constructor.

Returns:

The created instance of the class.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

resolve

public URL resolve(String resourceName)

Resolves a resource within the system. Fails if resource is not found.

Parameters:

resourceName - The name of the resource.

Returns:

The URL for the resource.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

tryResolve

public URL tryResolve(String resourceName)

Resolves a resource within the system. Returns null if resource is not found.

Parameters:

resourceName - The name of the resource.

Returns:

The URL for the resource or null if resource was not found.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

finalizeObject

public void finalizeObject()

Description copied from interface: IFinalizableObject

Do finalization (cleanup) actions here.

Specified by:

finalizeObject in interface IFinalizableObject

dispose

public void dispose()

Disposes this context and all included resources.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

createDefaultContext

public static RoboticsAPIContext createDefaultContext()

Creates a default context with the default engines and the MockController inside.

Returns:

A new default context.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

create

public static RoboticsAPIContext create()

Creates a new RoboticsAPIContext out of the config file which is located on the default package scope. The config file must have the name 'RoboticsAPI.config.xml'.

Returns:

The RoboticsAPIContext instance.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

create

public static RoboticsAPIContext create(Class<?> applicationContext)

Creates a new RoboticsAPIContext out of the config file which is located on the default package scope. The config file must have the name 'RoboticsAPI.config.xml'.

Parameters:

applicationContext - The application context.

Returns:

The RoboticsAPIContext instance.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

createFromResource

public static RoboticsAPIContext createFromResource(String resourceName)

Creates a new RoboticsAPIContext out of the given configuration file. This file has to be locatable by the Utilities.resolve method. If a configuration was already loaded for this config file, this instance will be disposed first.

Parameters:

resourceName - The resource file. null is not allowed.

Returns:

The RoboticsAPIContext instance.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

createFromResource

public static RoboticsAPIContext createFromResource(Class<?> applicationContext,
                                                    String resourceName)

Creates a new RoboticsAPIContext out of the given configuration file. This file has to be locatable by the Utilities.resolve method. If a configuration was already loaded for this config file, this instance will be disposed first.

Parameters:

applicationContext - The application context.

resourceName - The resource file. null is not allowed.

Returns:

The RoboticsAPIContext instance.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

createFromFile

public static RoboticsAPIContext createFromFile(File configFile)

Creates a new RoboticsAPIContext out of the given config file. The URL of the file will be used to load the context.

Parameters:

configFile - The config file. null is not allowed.

Returns:

The RoboticsAPIContext instance.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

createFromFile

public static RoboticsAPIContext createFromFile(Class<?> applicationContext,
                                                File configFile)

Creates a new RoboticsAPIContext out of the given config file. The URL of the file will be used to load the context.

Parameters:

applicationContext - The application context.

configFile - The config file. null is not allowed.

Returns:

The RoboticsAPIContext instance.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

createFromURL

public static RoboticsAPIContext createFromURL(Class<?> applicationContext,
                                               URL configURL)

Creates a new RoboticsAPIContext out of the given config URL.

Parameters:

applicationContext - The application context.

configURL - The URL to the config file. null is not allowed.

Returns:

The RoboticsAPIContext instance.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

getControllerInitializeBehavior

public IControllerInitializeBehaviour getControllerInitializeBehavior()

Gets the initialization behavior of the controller. The default RoboticsAPIContext does not define a initialization behavior.

Returns:

the initialization behavior of the controller.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.

dumpDevices

public void dumpDevices()

Debug Routine for displaying the installed devices from all controllers.

This element is an undocumented internal feature. It is not intended to be used by applications as it might change or be removed in future versions.