UniDA BasicGUI: Implementation Guide

About

This document explains the implementation of UniDA BasicGUI application, showing how to use the UniDA library API that allows the development of applications that handle hardware devices with independence of the technologies used in each device and their particular characteristics.

BasicGUI structure

BasicGUI is a simple Java application based on Swing that uses the UniDA library. Its use is documented in its Use Guide, suffice it to say here that the GUI shows information about the detected UniDA gateways and its devices, and allows to compose and send UniDA messages to them.

The unida_java_basicgui project contains the full implementation of BasicGUI. Because of the simplicity of this implementation, the controllers for this application are coded in the classes that act as main frame and dialog windows.

The UNIDALibraryBasicGUI class is a JFrame that acts as main window and entry point. For each kind of UniDA "request" message that can be edited and sent there is a JDialog class:

• CommandsDialog
• OnOffCommandsDialog
• DeviceStatesDialog
• DeviceStateDialog
• DeviceWriteStateDialog
• DeviceStateSubscriptionDialog
• AddAutonomousBehaviourRuleDialog
• AutonomousBehaviourChangeScenarioDialog
• AutonomousBehaviourQueryScenariosDialog
• ManageAutonomousBehaviourRulesDialog

Every one of these dialogs are launched from UNIDALibraryBasicGUI to act on a selected UniDA device, with the exception of AutonomousBehaviourDialog that manages the rules contained in an UniDA gateway.

BasicGUI design

The following class diagram shows the most importante relations and responsibilities that form BasicGUI. For the sake of clarity, only one kind of dialog is showed (CommandsDialog).

Different colors are used, to distinguish between:

• UniDA API usages (in green).
• Java Swing and AWT dependencies (in grey).
• BasicGUI own classes (in orange).

As the diagram shows, there is a single entry point to access the information about the detected UniDA devices (and gateways) as well as the methods to handle UniDA messages: InMemoryUniDAInstantiationFacade.

Accessing UniDA devices

When the InMemoryUniDAInstantiationFacade instance is initialized, any gateway announce message received is processed to build and update the in-memory database with all the information about the gateway and the UniDA devices it handles.

InMemoryUniDAInstantiationFacade provides an implementation for the interface IUniDAManagementFacade, which grant access to that database. To retrieve the detected UniDA gateways:

Collection<Gateway> gateways = 
 instantiationFacade.getDeviceManageFacade().findAllDeviceGateways(
   0, 
   Integer.MAX_VALUE);

Each Gateway object contains the information of all the UniDA devices the gateway handles.

Sending UniDA messages to a device

A different facade is provided by InMemoryUniDAInstantiationFacade in order to allow the user to send "request" messages to an UniDA device: an implementation of IDeviceOperationFacade.

To send one of those messages, the only needed objects are:

• An IDevice (obtained using the IUniDAManagementFacade previously shown) that represents the UniDA device which is the destination of the message
• The metadata (based on the UniDA DOGONT ontology) that identifies the action of the message (for example, sending one command that belongs to a control functionality).
• Aditional parameters that depend on the nature of the message (for example, values for the parameters in an UniDA command message).

As an example, this snippet shows an UniDA command message being built and sent:

IDevice device = 
 instantiationFacade.getDeviceManageFacade().findById(deviceId);
ControlCommandMetadata commandMetadata = 
 new ControlCommandMetadata(
   DomoParsing.instance().getDefaultOntologyNamespace() + commandId, 
   0);
ControlFunctionalityMetadata functionalityMetadata =
 new ControlFunctionalityMetadata(
   DomoParsing.instance().getDefaultOntologyNamespace() + funcId, 
   new ControlCommandMetadata[0]);
instantiationFacade.getDeviceOperationFacade().asyncSendCommand(
   device,
   functionalityMetadata,
   commandMetadata, 
   DomoParsing.valuesInStringToArray(values),
   new CommandsDialog.OpCback());

In order to handle messages received as response, a callback is needed. In this case, a proper implementation of IDeviceOperationCallback.

private class OpCback implements IDeviceOperationCallback 
{
 @Override
 public void notifyQueryDeviceStateResult(
         OperationTicket ticket, 
         IDevice dev, 
         DeviceState state) 
 {
   throw new UnsupportedOperationException("Invalid response for an UniDA Command.");
  }
 @Override
 public void notifyQueryDeviceStatesResult(
         OperationTicket ticket, 
         IDevice dev, 
         Collection<DeviceState> states) 
 {
   throw new UnsupportedOperationException("Invalid response for an UniDA Command.");
 }
 @Override
 public void notifyWriteDeviceStateResult(
         OperationTicket ticket, 
         IDevice dev)
 {
   throw new UnsupportedOperationException("Invalid response for an UniDA Command.");
 }
 @Override
 public void notifySendCommandQueryStateResult(
         OperationTicket ticket, 
         IDevice dev, 
         ControlFunctionalityMetadata fund, 
         ControlCommandMetadata cmd, 
         Collection<String> params, 
         Collection<DeviceState> states) 
 {
   throw new UnsupportedOperationException("Invalid response for an UniDA Command.");
 }
 @Override
 public void notifyCommandExecution(
         OperationTicket ticket, 
         IDevice dev, 
         ControlFunctionalityMetadata func, 
         ControlCommandMetadata cmd) 
 {
   jTextInfoExecution.setText("yippee!");
 }
 @Override
 public void notifyOperationFailure(
         OperationTicket ticket, 
         IDevice dev, 
         OperationFailures failure, 
         String failureDescription) 
 {
   jTextInfoExecution.setText("oh no!");
 }
}

The identifiers for the metadata used to build the messages must come from this ontology: DogOnt "base" ontology, classes added for UniDA .

Managing autonomous behaviour rules

TBD