com.aldebaran.qi.helper.proxies

Class ALMemory

java.lang.Object

com.aldebaran.qi.helper.ALProxy

com.aldebaran.qi.helper.ALMemoryHelper

com.aldebaran.qi.helper.proxies.ALMemory

public class ALMemory
extends ALMemoryHelper

ALMemory provides a centralized memory that can be used to store and retrieve named values. It also acts as a hub for the distribution of event notifications.

See Also:

NAOqi APIs for ALMemory

Field Summary

Fields inherited from class com.aldebaran.qi.helper.ALProxy

name, service

Constructor Summary

Constructors

Constructor and Description
ALMemory(Session session)

Method Summary

Modifier and Type	Method and Description
void	addMapping(java.lang.String service, java.util.Map<java.lang.String,java.lang.String> signalEvent) Add a mapping between signal and event
void	addMapping(java.lang.String service, java.lang.String signal, java.lang.String event) Add a mapping between signal and event
void	clearStats()
void	declareEvent(java.lang.String eventName) Declares an event to allow future subscriptions to the event
void	declareEvent(java.lang.String eventName, java.lang.String extractorName) Declares an event to allow future subscriptions to the event
void	exit() Exits and unregisters the module.
java.lang.String	getBrokerName() Gets the name of the parent broker.
java.lang.Object	getData(java.lang.String key) Gets the value of a key-value pair stored in memory
java.lang.Object	getData(java.lang.String key, java.lang.Integer deprecatedParameter) DEPRECATED - Gets the value of a key-value pair stored in memory.
java.util.List<java.lang.String>	getDataList(java.lang.String filter) Gets a list of all key names that contain a given string
java.util.List<java.lang.String>	getDataListName() Gets the key names for all the key-value pairs in memory
java.lang.Object	getDataOnChange(java.lang.String key, java.lang.Integer deprecatedParameter) DEPRECATED - Blocks the caller until the value of a key changes
java.lang.Object	getDataPtr(java.lang.String key) Gets a pointer to 32 a bit data item.
java.lang.Object	getDescriptionList(java.util.List<java.lang.String> keylist) Descriptions of all given keys
java.lang.Object	getEventHistory(java.lang.String key) Get data value and timestamp
java.util.List<java.lang.String>	getEventList() Gets a list containing the names of all the declared events
java.util.List<java.lang.String>	getExtractorEvent(java.lang.String extractorName) Gets the list of all events generated by a given extractor
java.lang.Object	getListData(java.lang.Object keyList) Gets the values associated with the given list of keys.
java.lang.Object	getMethodHelp(java.lang.String methodName) Retrieves a method's description.
java.util.List<java.lang.String>	getMethodList() Retrieves the module's method list.
java.util.List<java.lang.String>	getMicroEventList() Gets a list containing the names of all the declared micro events
java.lang.Object	getModuleHelp() Retrieves the module's description.
java.util.List<java.lang.String>	getSubscribers(java.lang.String name) Gets a list containing the names of subscribers to an event.
java.lang.Object	getTimestamp(java.lang.String key) Get data value and timestamp
java.lang.String	getType(java.lang.String key) Gets the storage class of the stored data.
java.lang.String	getUsage(java.lang.String name) Gets the method usage string.
void	insertData(java.lang.String key, java.lang.Float value) Inserts a key-value pair into memory, where value is a float
void	insertData(java.lang.String key, java.lang.Integer value) Inserts a key-value pair into memory, where value is an int
void	insertData(java.lang.String key, java.lang.Object data) Inserts a key-value pair into memory, where value is an ALValue
void	insertData(java.lang.String key, java.lang.String value) Inserts a key-value pair into memory, where value is a string
void	insertListData(java.lang.Object list) Inserts a list of key-value pairs into memory.
java.lang.Boolean	isRunning(java.lang.Integer id) Returns true if the method is currently running.
java.lang.Boolean	isStatsEnabled()
java.lang.Boolean	isTraceEnabled()
java.lang.Boolean	ping() Just a ping.
void	raiseEvent(java.lang.String name, java.lang.Object value) Publishes the given data to all subscribers.
void	raiseMicroEvent(java.lang.String name, java.lang.Object value) Publishes the given data to all subscribers.
void	removeData(java.lang.String key) Removes a key-value pair from memory
void	removeEvent(java.lang.String name) Removes a event from memory and unsubscribes any exiting subscribers.
void	removeMicroEvent(java.lang.String name) Removes a micro event from memory and unsubscribes any exiting subscribers.
void	setDescription(java.lang.String name, java.lang.String description) Describe a key
void	stop(java.lang.Integer id) returns true if the method is currently running
AnyObject	subscriber(java.lang.String eventName) Get an object wrapping a signal bound to the given ALMemory event.
void	subscribeToEvent(java.lang.String name, java.lang.String callbackModule, java.lang.String callbackMethod) Subscribes to an event and automaticaly launches the module that declared itself as the generator of the event if required.
void	subscribeToEvent(java.lang.String name, java.lang.String callbackModule, java.lang.String callbackMessage, java.lang.String callbacMethod) DEPRECATED Subscribes to event and automaticaly launches the module capable of generating the event if it is not already running.
void	subscribeToMicroEvent(java.lang.String name, java.lang.String callbackModule, java.lang.String callbackMessage, java.lang.String callbackMethod) Subscribes to a microEvent.
void	unregisterModuleReference(java.lang.String moduleName) Informs ALMemory that a module doesn't exist anymore.
void	unsubscribeToEvent(java.lang.String name, java.lang.String callbackModule) Unsubscribes a module from the given event.
void	unsubscribeToMicroEvent(java.lang.String name, java.lang.String callbackModule) Unsubscribes from the given event.
java.lang.String	version() Returns the version of the module.
java.lang.Boolean	wait(java.lang.Integer id, java.lang.Integer timeoutPeriod) Wait for the end of a long running method that was called using 'post'

Methods inherited from class com.aldebaran.qi.helper.ALMemoryHelper

subscribeToEvent, subscribeToEvent, unsubscribeAllEvents, unsubscribeToEvent

Methods inherited from class com.aldebaran.qi.helper.ALProxy

call, connect, connect, disconnect, getNaoqiType, getService, isProxyReady, setService

Methods inherited from class java.lang.Object

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

Constructor Detail

ALMemory

public ALMemory(Session session)
         throws java.lang.Exception

Throws:

java.lang.Exception

Method Detail

insertData

public void insertData(java.lang.String key,
                       java.lang.String value)
                throws CallError,
                       java.lang.InterruptedException

Inserts a key-value pair into memory, where value is a string

Parameters:

key - Name of the value to be inserted.

value - The string to be inserted

Throws:

CallError

java.lang.InterruptedException

removeData

public void removeData(java.lang.String key)
                throws CallError,
                       java.lang.InterruptedException

Removes a key-value pair from memory

Parameters:

key - Name of the data to be removed.

Throws:

CallError

java.lang.InterruptedException

getSubscribers

public java.util.List<java.lang.String> getSubscribers(java.lang.String name)
                                                throws CallError,
                                                       java.lang.InterruptedException

Gets a list containing the names of subscribers to an event.

Parameters:

name - Name of the event or micro-event

Returns:

List of subscriber names

Throws:

CallError

java.lang.InterruptedException

removeMicroEvent

public void removeMicroEvent(java.lang.String name)
                      throws CallError,
                             java.lang.InterruptedException

Removes a micro event from memory and unsubscribes any exiting subscribers.

Parameters:

name - Name of the event to remove.

Throws:

CallError

java.lang.InterruptedException

subscribeToEvent

public void subscribeToEvent(java.lang.String name,
                             java.lang.String callbackModule,
                             java.lang.String callbackMethod)
                      throws CallError,
                             java.lang.InterruptedException

Subscribes to an event and automaticaly launches the module that declared itself as the generator of the event if required.

Parameters:

name - The name of the event to subscribe to

callbackModule - Name of the module to call with notifications

callbackMethod - Name of the module's method to call when a data is changed

Throws:

CallError

java.lang.InterruptedException

insertData

public void insertData(java.lang.String key,
                       java.lang.Integer value)
                throws CallError,
                       java.lang.InterruptedException

Inserts a key-value pair into memory, where value is an int

Parameters:

key - Name of the value to be inserted.

value - The int to be inserted

Throws:

CallError

java.lang.InterruptedException

subscribeToMicroEvent

public void subscribeToMicroEvent(java.lang.String name,
                                  java.lang.String callbackModule,
                                  java.lang.String callbackMessage,
                                  java.lang.String callbackMethod)
                           throws CallError,
                                  java.lang.InterruptedException

Subscribes to a microEvent. Subscribed modules are notified on theircallback method whenever the data is updated, even if the new value is the same as the old value.

Parameters:

name - Name of the data.

callbackModule - Name of the module to call with notifications

callbackMessage - Message included in the notification. This can be used to disambiguate multiple subscriptions.

callbackMethod - Name of the module's method to call when a data is changed

Throws:

CallError

java.lang.InterruptedException

unregisterModuleReference

public void unregisterModuleReference(java.lang.String moduleName)
                               throws CallError,
                                      java.lang.InterruptedException

Informs ALMemory that a module doesn't exist anymore.

Parameters:

moduleName - Name of the departing module.

Throws:

CallError

java.lang.InterruptedException

unsubscribeToEvent

public void unsubscribeToEvent(java.lang.String name,
                               java.lang.String callbackModule)
                        throws CallError,
                               java.lang.InterruptedException

Unsubscribes a module from the given event. No further notifications will be received.

Parameters:

name - The name of the event

callbackModule - The name of the module that was given when subscribing.

Throws:

CallError

java.lang.InterruptedException

unsubscribeToMicroEvent

public void unsubscribeToMicroEvent(java.lang.String name,
                                    java.lang.String callbackModule)
                             throws CallError,
                                    java.lang.InterruptedException

Unsubscribes from the given event. No further notifications will be received.

Parameters:

name - Name of the event.

callbackModule - The name of the module that was given when subscribing.

Throws:

CallError

java.lang.InterruptedException

insertData

public void insertData(java.lang.String key,
                       java.lang.Float value)
                throws CallError,
                       java.lang.InterruptedException

Inserts a key-value pair into memory, where value is a float

Parameters:

key - Name of the value to be inserted.

value - The float to be inserted

Throws:

CallError

java.lang.InterruptedException

setDescription

public void setDescription(java.lang.String name,
                           java.lang.String description)
                    throws CallError,
                           java.lang.InterruptedException

Describe a key

Parameters:

name - Name of the key.

description - The description of the event (text format).

Throws:

CallError

java.lang.InterruptedException

getDescriptionList

public java.lang.Object getDescriptionList(java.util.List<java.lang.String> keylist)
                                    throws CallError,
                                           java.lang.InterruptedException

Descriptions of all given keys

Parameters:

keylist - List of keys. (empty to get all descriptions)

Returns:

an array of tuple (name, type, description) describing all keys.

Throws:

CallError

java.lang.InterruptedException

addMapping

public void addMapping(java.lang.String service,
                       java.lang.String signal,
                       java.lang.String event)
                throws CallError,
                       java.lang.InterruptedException

Add a mapping between signal and event

Parameters:

service - Name of the service

signal - Name of the signal

event - Name of the event

Throws:

CallError

java.lang.InterruptedException

addMapping

public void addMapping(java.lang.String service,
                       java.util.Map<java.lang.String,java.lang.String> signalEvent)
                throws CallError,
                       java.lang.InterruptedException

Add a mapping between signal and event

Parameters:

service - Name of the service

signalEvent - A map of signal corresponding to event

Throws:

CallError

java.lang.InterruptedException

insertData

public void insertData(java.lang.String key,
                       java.lang.Object data)
                throws CallError,
                       java.lang.InterruptedException

Inserts a key-value pair into memory, where value is an ALValue

Parameters:

key - Name of the value to be inserted.

data - The ALValue to be inserted. This could contain a basic type, or a more complex array. See the ALValue documentation for more information.

Throws:

CallError

java.lang.InterruptedException

insertListData

public void insertListData(java.lang.Object list)
                    throws CallError,
                           java.lang.InterruptedException

Inserts a list of key-value pairs into memory.

Parameters:

list - An ALValue list of the form [[Key, Value],...]. Each item will be inserted.

Throws:

CallError

java.lang.InterruptedException

getType

public java.lang.String getType(java.lang.String key)
                         throws CallError,
                                java.lang.InterruptedException

Gets the storage class of the stored data. This is not the underlying POD type.

Parameters:

key - Name of the variable

Returns:

String type: Data, Event, MicroEvent

Throws:

CallError

java.lang.InterruptedException

raiseEvent

public void raiseEvent(java.lang.String name,
                       java.lang.Object value)
                throws CallError,
                       java.lang.InterruptedException

Publishes the given data to all subscribers.

Parameters:

name - Name of the event to raise.

value - The data associated with the event. This could contain a basic type, or a more complex array. See the ALValue documentation for more information.

Throws:

CallError

java.lang.InterruptedException

raiseMicroEvent

public void raiseMicroEvent(java.lang.String name,
                            java.lang.Object value)
                     throws CallError,
                            java.lang.InterruptedException

Publishes the given data to all subscribers.

Parameters:

name - Name of the event to raise.

value - The data associated with the event. This could contain a basic type, or a more complex array. See the ALValue documentation for more information.

Throws:

CallError

java.lang.InterruptedException

removeEvent

public void removeEvent(java.lang.String name)
                 throws CallError,
                        java.lang.InterruptedException

Removes a event from memory and unsubscribes any exiting subscribers.

Parameters:

name - Name of the event to remove.

Throws:

CallError

java.lang.InterruptedException

subscribeToEvent

public void subscribeToEvent(java.lang.String name,
                             java.lang.String callbackModule,
                             java.lang.String callbackMessage,
                             java.lang.String callbacMethod)
                      throws CallError,
                             java.lang.InterruptedException

DEPRECATED Subscribes to event and automaticaly launches the module capable of generating the event if it is not already running. Please use the version without the callbackMessage parameter.

Parameters:

name - The name of the event to subscribe to

callbackModule - Name of the module to call with notifications

callbackMessage - DEPRECATED Message included in the notification.

callbacMethod - Name of the module's method to call when a data is changed

Throws:

CallError

java.lang.InterruptedException

isStatsEnabled

public java.lang.Boolean isStatsEnabled()
                                 throws CallError,
                                        java.lang.InterruptedException

Throws:

CallError

java.lang.InterruptedException

clearStats

public void clearStats()
                throws CallError,
                       java.lang.InterruptedException

Throws:

CallError

java.lang.InterruptedException

isTraceEnabled

public java.lang.Boolean isTraceEnabled()
                                 throws CallError,
                                        java.lang.InterruptedException

Throws:

CallError

java.lang.InterruptedException

exit

public void exit()
          throws CallError,
                 java.lang.InterruptedException

Exits and unregisters the module.

Throws:

CallError

java.lang.InterruptedException

version

public java.lang.String version()
                         throws CallError,
                                java.lang.InterruptedException

Returns the version of the module.

Returns:

A string containing the version of the module.

Throws:

CallError

java.lang.InterruptedException

ping

public java.lang.Boolean ping()
                       throws CallError,
                              java.lang.InterruptedException

Just a ping. Always returns true

Returns:

returns true

Throws:

CallError

java.lang.InterruptedException

getMethodList

public java.util.List<java.lang.String> getMethodList()
                                               throws CallError,
                                                      java.lang.InterruptedException

Retrieves the module's method list.

Returns:

An array of method names.

Throws:

CallError

java.lang.InterruptedException

getMethodHelp

public java.lang.Object getMethodHelp(java.lang.String methodName)
                               throws CallError,
                                      java.lang.InterruptedException

Retrieves a method's description.

Parameters:

methodName - The name of the method.

Returns:

A structure containing the method's description.

Throws:

CallError

java.lang.InterruptedException

getModuleHelp

public java.lang.Object getModuleHelp()
                               throws CallError,
                                      java.lang.InterruptedException

Retrieves the module's description.

Returns:

A structure describing the module.

Throws:

CallError

java.lang.InterruptedException

wait

public java.lang.Boolean wait(java.lang.Integer id,
                              java.lang.Integer timeoutPeriod)
                       throws CallError,
                              java.lang.InterruptedException

Wait for the end of a long running method that was called using 'post'

Parameters:

id - The ID of the method that was returned when calling the method using 'post'

timeoutPeriod - The timeout period in ms. To wait indefinately, use a timeoutPeriod of zero.

Returns:

True if the timeout period terminated. False if the method returned.

Throws:

CallError

java.lang.InterruptedException

isRunning

public java.lang.Boolean isRunning(java.lang.Integer id)
                            throws CallError,
                                   java.lang.InterruptedException

Returns true if the method is currently running.

Parameters:

id - The ID of the method that was returned when calling the method using 'post'

Returns:

True if the method is currently running

Throws:

CallError

java.lang.InterruptedException

stop

public void stop(java.lang.Integer id)
          throws CallError,
                 java.lang.InterruptedException

returns true if the method is currently running

Parameters:

id - the ID of the method to wait for

Throws:

CallError

java.lang.InterruptedException

getBrokerName

public java.lang.String getBrokerName()
                               throws CallError,
                                      java.lang.InterruptedException

Gets the name of the parent broker.

Returns:

The name of the parent broker.

Throws:

CallError

java.lang.InterruptedException

getUsage

public java.lang.String getUsage(java.lang.String name)
                          throws CallError,
                                 java.lang.InterruptedException

Gets the method usage string. This summarises how to use the method.

Parameters:

name - The name of the method.

Returns:

A string that summarises the usage of the method.

Throws:

CallError

java.lang.InterruptedException

declareEvent

public void declareEvent(java.lang.String eventName)
                  throws CallError,
                         java.lang.InterruptedException

Declares an event to allow future subscriptions to the event

Parameters:

eventName - The name of the event

Throws:

CallError

java.lang.InterruptedException

declareEvent

public void declareEvent(java.lang.String eventName,
                         java.lang.String extractorName)
                  throws CallError,
                         java.lang.InterruptedException

Declares an event to allow future subscriptions to the event

Parameters:

eventName - The name of the event

extractorName - The name of the extractor capable of creating the event

Throws:

CallError

java.lang.InterruptedException

getData

public java.lang.Object getData(java.lang.String key)
                         throws CallError,
                                java.lang.InterruptedException

Gets the value of a key-value pair stored in memory

Parameters:

key - Name of the value.

Returns:

The data as an ALValue. This can often be cast transparently into the original type.

Throws:

CallError

java.lang.InterruptedException

getData

public java.lang.Object getData(java.lang.String key,
                                java.lang.Integer deprecatedParameter)
                         throws CallError,
                                java.lang.InterruptedException

DEPRECATED - Gets the value of a key-value pair stored in memory. Please use the version of this method with no second parameter.

Parameters:

key - Name of the value.

deprecatedParameter - DEPRECATED - This parameter has no effect, but is left for compatibility reason.

Returns:

The data as an ALValue

Throws:

CallError

java.lang.InterruptedException

subscriber

public AnyObject subscriber(java.lang.String eventName)
                     throws CallError,
                            java.lang.InterruptedException

Get an object wrapping a signal bound to the given ALMemory event. Throw if the event does not exist or if it is invalid.

Overrides:

subscriber in class ALMemoryHelper

Parameters:

eventName - Name of the ALMemory event

Returns:

An AnyObject with a signal named "signal"

Throws:

CallError

java.lang.InterruptedException

getTimestamp

public java.lang.Object getTimestamp(java.lang.String key)
                              throws CallError,
                                     java.lang.InterruptedException

Get data value and timestamp

Parameters:

key - Name of the variable

Returns:

A list of all the data key names that contain the given string.

Throws:

CallError

java.lang.InterruptedException

getEventHistory

public java.lang.Object getEventHistory(java.lang.String key)
                                 throws CallError,
                                        java.lang.InterruptedException

Get data value and timestamp

Parameters:

key - Name of the variable

Returns:

A list of all the data key names that contain the given string.

Throws:

CallError

java.lang.InterruptedException

getDataList

public java.util.List<java.lang.String> getDataList(java.lang.String filter)
                                             throws CallError,
                                                    java.lang.InterruptedException

Gets a list of all key names that contain a given string

Parameters:

filter - A string used as the search term

Returns:

A list of all the data key names that contain the given string.

Throws:

CallError

java.lang.InterruptedException

getDataListName

public java.util.List<java.lang.String> getDataListName()
                                                 throws CallError,
                                                        java.lang.InterruptedException

Gets the key names for all the key-value pairs in memory

Returns:

A list containing the keys in memory

Throws:

CallError

java.lang.InterruptedException

getDataOnChange

public java.lang.Object getDataOnChange(java.lang.String key,
                                        java.lang.Integer deprecatedParameter)
                                 throws CallError,
                                        java.lang.InterruptedException

DEPRECATED - Blocks the caller until the value of a key changes

Parameters:

key - Name of the data.

deprecatedParameter - DEPRECATED - this parameter has no effect

Returns:

an array containing all the retrieved data

Throws:

CallError

java.lang.InterruptedException

getDataPtr

public java.lang.Object getDataPtr(java.lang.String key)
                            throws CallError,
                                   java.lang.InterruptedException

Gets a pointer to 32 a bit data item. Beware, the pointer will only be valid during the lifetime of the ALMemory object. Use with care, at initialization, not every loop.

Parameters:

key - Name of the data.

Returns:

A pointer converted to int

Throws:

CallError

java.lang.InterruptedException

getEventList

public java.util.List<java.lang.String> getEventList()
                                              throws CallError,
                                                     java.lang.InterruptedException

Gets a list containing the names of all the declared events

Returns:

A list containing the names of all events

Throws:

CallError

java.lang.InterruptedException

getExtractorEvent

public java.util.List<java.lang.String> getExtractorEvent(java.lang.String extractorName)
                                                   throws CallError,
                                                          java.lang.InterruptedException

Gets the list of all events generated by a given extractor

Parameters:

extractorName - The name of the extractor

Returns:

A list containing the names of the events associated with the given extractor

Throws:

CallError

java.lang.InterruptedException

getListData

public java.lang.Object getListData(java.lang.Object keyList)
                             throws CallError,
                                    java.lang.InterruptedException

Gets the values associated with the given list of keys. This is more efficient than calling getData many times, especially over the network.

Parameters:

keyList - An array containing the key names.

Returns:

An array containing all the values corresponding to the given keys.

Throws:

CallError

java.lang.InterruptedException

getMicroEventList

public java.util.List<java.lang.String> getMicroEventList()
                                                   throws CallError,
                                                          java.lang.InterruptedException

Gets a list containing the names of all the declared micro events

Returns:

A list containing the names of all the microEvents

Throws:

CallError

java.lang.InterruptedException