org.universAAL.support.utils
Class UAAL

java.lang.Object
  org.universAAL.support.utils.UAAL

public class UAAL
extends Object

This is a central helper class that allows you to interact with universAAL from a very high level, use its main features, and doing it with few or no extra classes and little code.

Not all the possible features of universAAL are accessible from it, only the most typical and straight/forward, namely:

Send Context Events

Subscribe for Context Events

Call Services

Provide Services

Request User Interaction and handle Response

And all of these without (virtually) having to implement extensions of uAAL classes, which may come in handy for already existing applications which just want to connect easily to uAAL. Actually some of these provided simplified features use a Listener Interface-oriented approach, for which it may be necessary to create additional classes for implementing them or do it in existing classes, although in general it is possible to create the implementation in the method calls themselves without much complication.

Notice that for allowing this, this UAAL class takes care of instantiating and maintaining all needed uAAL wrapper classes, so for as long as you don't call terminate() it will keep hold of these resources. This also means that the performance might not be as polite as it could if you handled your own implementations of uAAL wrappers with the native API or the other sublayers of this utilities API. The purpose of this UAAL class was never to improve the performance but to simplify the coding.

To use the class methods, just instantiate it with a valid uAAL ModuleContext. For instance, from an Activator:

    private UAAL u;

    public void start(BundleContext bcontext) throws Exception {
        Activator.osgiContext = bcontext;
        Activator.context = uAALBundleContainer.THE_CONTAINER
                .registerModule(new Object[] { bcontext });
        u = new UAAL(context);
        ...
    }
 

Remember to release the resources when you stop your application (like in Activator.stop() method) by calling terminate().

Author:

alfiva

Constructor Summary

UAAL(ModuleContext context)
This constructor just assigns the Module Context: the rest of resources used by this class are not initialized.

Method Summary

ServiceResponse	callS(ServiceRequest r) Calls a Service with a Service Request.
void	provideS(ServiceProfile[] p, ISListener l) Registers Service Profiles and specifies how the calls to these profiles would be handled.
void	requestUI(UIRequest ui, IUIListener l) Requests User Interaction and specifies how the response would be handled.
void	sendC(ContextEvent e) Sends a Context Event.
void	subscribeC(ContextEventPattern[] p, ICListener l) Subscribes for Context Events and specifies how the events would be handled.
void	terminate() Closes all uAAL wrapper classes created by this UAAL helper until now (by calling their .close() method) and eliminates them.

Methods inherited from class java.lang.Object

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

Constructor Detail

UAAL

public UAAL(ModuleContext context)

This constructor just assigns the Module Context: the rest of resources used by this class are not initialized. They will be automatically initialized as they are needed when you use the uAAL features methods of the class, so you don't have to do anything else. All resources will be maintained until you call terminate().

Although it is possible to have as many instances of this class as desired (no restrictions are set about it), it is recommended to maintain just a single(ton) instance of it, and make it accessible to the rest of your application code.

Parameters:

context - The uAAL Module Context.

Method Detail

sendC

public void sendC(ContextEvent e)

Sends a Context Event.

UAAL helper automatically creates its own internal Context Publisher if this is the first time the method is called. The Publisher is described as either a Gauge or a Controller depending on if you are providing Services (you called method provideS()). The URI of the Provider is automatically set to http://ontology.universAAL.org/SimpleUAAL .owl#ContextEventsProvider and it cannot be changed. Currently, the pattern that describes the provided events of this provider is empty, which means it can publish any type of event.

Parameters:

e - The Context Event to send.

callS

public ServiceResponse callS(ServiceRequest r)

Calls a Service with a Service Request.

UAAL helper automatically creates its own internal Default Service Caller if this is the first time the method is called. The call to the service is synchronous: this method returns the response of the call straight from Service Bus. You will have to deal with it.

Remember that the simplified API in this library ( org.universAAL.support.utils.service packages) can assist you in creating Service Requests and handling Service Responses.

Parameters:

r - The Service Request describing the Service to call.

Returns:

The Service Response to the call returned by the Service Bus.

See Also:

Request

requestUI

public void requestUI(UIRequest ui,
                      IUIListener l)

Requests User Interaction and specifies how the response would be handled.

UAAL helper automatically creates its own internal UI Caller if this is the first time the method is called. An implementation of IUIListener must be passed that will handle the response to the UI Request that is being sent. The response contains the user input to the forms described in the UI Request, so the listener must be ready to work with the fields, controls, submits and identifiers used in the request. There can only be a single listener associated to the UI Caller at a time, which means this method cannot be called again with a new listener until the previous response has been received and processed by the old listener. Another solution is using always the same instance of the listener, which should then be ready to handle any possible UI response to your application.

Remember that the simplified API in this library ( org.universAAL.support.utils.ui packages) can assist you in creating UI Requests.

Parameters:

ui - The UI request with the output to display to the user.

l - The listener that will handle the response to that UI request.

See Also:

Dialog, Message, SubDialog

subscribeC

public void subscribeC(ContextEventPattern[] p,
                       ICListener l)

Subscribes for Context Events and specifies how the events would be handled.

UAAL helper automatically creates a new own internal Context Subscriber each time this method is called. An implementation of ICListener must be passed that will handle the reception of an event that matches the passed patterns. The listener is associated to the patterns: All events that match the patterns are received by the listener (regardless of any other calls to this method). The listener remains active and associated to the patterns until terminate() is called. Since every call to this method creates a new subscriber, you should be careful with how many times you call this method. Usually, a limited number of subscriptions is needed. Remember that you can combine different patterns to be handled by a single listener.

Remember that the simplified API in this library ( org.universAAL.support.utils.context packages) can assist you in creating Context Event Patterns.

Parameters:

p - An array of Context Event Patterns describing the Context Events that will be handled by the listener.

l - The listener that will handle the received event that matches the patterns.

See Also:

Pattern

provideS

public void provideS(ServiceProfile[] p,
                     ISListener l)

Registers Service Profiles and specifies how the calls to these profiles would be handled.

UAAL helper automatically creates a new own internal Service Callee each time this method is called. An implementation of ISListener must be passed that will handle the call request that matches the provided profiles. The listener is associated to the profiles: All call requests that match the profiles are received by the listener (regardless of any other calls to this method). The listener remains active and associated to the profiles until terminate() is called. Since every call to this method creates a new callee, you should be careful with how many times you call this method. Usually, a limited number of callees is needed.

Remember that the simplified API in this library ( org.universAAL.support.utils.service packages) can assist you in creating Service Profiles.

Parameters:

p - An array of Service Profiles describing the provided services that will be handled by the listener.

l - The listener that will handle the received call request that matches the provided service profiles.

See Also:

Profile

terminate

public void terminate()

Closes all uAAL wrapper classes created by this UAAL helper until now (by calling their .close() method) and eliminates them. The reference to the Module Context is maintained, however. This allows to perform new calls to the uAAL features methods, which will create new uAAL wrappers in the helper.