agentland.device
Class DeviceAgent

java.lang.Object
  |
  +--java.rmi.server.RemoteObject
        |
        +--java.rmi.server.RemoteServer
              |
              +--java.rmi.server.UnicastRemoteObject
                    |
                    +--metaglue.AgentAgent
                          |
                          +--agentland.util.GoodAgent
                                |
                                +--agentland.resource.ManagedAgent
                                      |
                                      +--agentland.device.DeviceAgent

All Implemented Interfaces:

Agent, Device, Good, Managed, MetagluePrimitives, Remote, Serializable, Spy

Direct Known Subclasses:

AnotherDummyDeviceAgent, BaseAmplifierAgent, BaseMuxAgent, DisplayDeviceAgent, DrapesAgent, DummyDeviceAgent, IRAgent, LightAgent, ManualProjectorAgent, MultiDeviceAgent, ProjectionScreenAgent, UniversalDeviceAgent, X10Agent

public class DeviceAgent

extends ManagedAgent

implements Device

This is the agent that all device agents should inherit from. There are a few things this class should facilitate:

• Device Error Handling - there are a few methods here that will deal with problems occuring while controlling devices. The idea is that information about all failures should be recorded somewhere in the system but it should not necessarily propagate to the caller. So I think that exceptions that arise while controlling devices should be forwarded to a special TroubleShooter agent. Meanwhile the methods should always return a boolean indicating if they were successful or not. That way callers will know if things went ok and if they want to know more about what went wrong, they will be able to ask the TroubleShooter.
• Managing the state of the device -- there are a few methods here for managing the state: setState, getState and resetState. It is assumed that the state of the device is always stored as DeviceState object (or a decendant). Whenever state changes, the device controller should call updateState or setState and this will not only update the state object but will also send out a notification about it.
• Managing the naming of the device -- there are a bunch of methods for keeping track of all the names that can be used to refer to this device. The list of names is frozen so it is persistent and specific to society, occupation and designation.

See Also:

AgentAgent, Device, Serialized Form

Inner classes inherited from class metaglue.AgentAgent

AgentAgent.Attribute

Field Summary

protected String	defaultState
protected String	fName
protected Vector	names
protected PersistentMap	states

Fields inherited from class agentland.resource.ManagedAgent

rm, society

Fields inherited from class agentland.util.GoodAgent

alert, notifier

Fields inherited from class java.rmi.server.RemoteObject

ref

Fields inherited from interface metaglue.Agent

ALIVE, DIED, NO_METAGLUE, NOT_RUNNING, STARTING

Constructor Summary

DeviceAgent()

Method Summary

void	addName(String newName) Allows you to add a new name by which this device can be known (or referred to)
protected Secret	createStateChangeNotification(DeviceState s) This method creates the state change notification.
protected DeviceState	ensureState(String name) Returns a state with given name if one exists or creates a new one
protected String[]	getDefaultNames() Override this method to set the default names for your device; this method is only called if we cannot defrost names set previously
protected String	getDefaultStateName()
String	getName() Returns THE name for the device, i.e.
Vector	getNames() Returns all names for this device; if there are no names, you get back an empty vector.
DeviceState	getState() Returns the current value of the defalult state of the device
DeviceState	getState(String name) returns the current value of a named state of this device
Vector	getStateNames() Returns a vector with the names of all states of this device
boolean	hasName(String name) returns true if this device can be called by the name passed as a parameter (matching is done in case-insensitive way)
protected void	quietException(DeviceException ex) When there is a problem in the functioning of a device, any exception should be signalled through this method rather than by throwing it directly (unless really necessary).
void	resetAllStates() Resets all the states to the default values (as defined by each device state object) -- you may want to override this method to set your own reset values of each state.
String	resetName(String newName) Clears all names for this device and sets newName as the only name for it.
void	resetState() Resets the default state
void	resetState(String name) Resets a particular state
protected void	setDefaultStateName(String name) Allows you to set the name of the device which will be considered "THE" state for the device
String	setName(int pos, String newName) Allows you to change the name on the list; starting index is 0;
void	setState(DeviceState state) This method is for "external" use only (i.e.
protected void	throwException(DeviceException ex)
protected void	updateState(DeviceState s) for internal use only -- calls updateState(s, true)
protected void	updateState(DeviceState s, boolean announce) for internal use only -- updates the state of the device to s and, optionally, sends out a notification about state change.
protected DeviceState	updateState(String name, boolean value)
protected DeviceState	updateState(String name, boolean value, int confidence)
protected DeviceState	updateState(String name, int value)
protected DeviceState	updateState(String name, int value, int confidence)
protected DeviceState	updateState(String name, Object value) Just lets you update the state value without changing the confidence
protected DeviceState	updateState(String name, Object value, int confidence) A shortcut method

Methods inherited from class agentland.resource.ManagedAgent

connect, getAlert, getNeed, isAvailable, isAvailable, reliesOn, reliesOn, replace, replace, request, request, request, requestAgent, requestAgent, resources, resourcesByAgentID, setNeed, tiedTo, yank, yank, yank

Methods inherited from class agentland.util.GoodAgent

addSpy, addSpy, alert, alertString, beep, error, getHistory, getHistoryElement, getPersistentMap, log, notify, removeSpy, removeSpy, resetHistory, safeRely, safeRely, safeRely, setNiceLogName, tell

Methods inherited from class metaglue.AgentAgent

addMonitor, alive, defrost, defrostAll, defrostBoolean, defrostInt, defrostString, fixAttribute, fixAttribute, freeze, freeze, freeze, freezeAll, freezeVar, getAgentID, getAttribute, getCatalog, getCatalogID, getDesignation, getFrozenVariables, getLogLevel, getMetaglueAgent, getMetaglueAgentID, getOccupation, getProperties, getSociety, log, log, lookupClass, obtainMetaglueAgent, obtainMetaglueAgent, obtainMetaglueAgentByName, reliesOn, reliesOnSynch, removeFrozen, replaceExceptionHandler, setFreezeName, setLogLevel, setLogName, shutdown, startAgent, startAgentOn, startAgentOn, startup, status, tiedTo, tiedTo, tiedTo, tiedTo, tieToDesignation, whereAreYou

Methods inherited from class java.rmi.server.UnicastRemoteObject

clone, exportObject, exportObject, exportObject, unexportObject

Methods inherited from class java.rmi.server.RemoteServer

getClientHost, getLog, setLog

Methods inherited from class java.rmi.server.RemoteObject

equals, getRef, hashCode, toString, toStub

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface agentland.resource.Managed

getNeed, replace, replace, resources, yank, yank

Methods inherited from interface agentland.util.Good

getHistory, getHistoryElement, resetHistory

Methods inherited from interface metaglue.Agent

addMonitor, alive, getAgentID, getMetaglueAgentID, shutdown, startup, whereAreYou

Methods inherited from interface agentland.util.Spy

tell

Field Detail

defaultState

protected String defaultState

states

protected PersistentMap states

fName

protected String fName

names

protected Vector names

Constructor Detail

DeviceAgent

public DeviceAgent()
            throws RemoteException

Method Detail

quietException

protected void quietException(DeviceException ex)

When there is a problem in the functioning of a device, any exception should be signalled through this method rather than by throwing it directly (unless really necessary). Exceptions passed to this method will be passed to the TroubleShooter and thrown only under special conditions.

Parameters:

ex - The exception to be taken care of

throwException

protected void throwException(DeviceException ex)
                       throws DeviceException

getDefaultNames

protected String[] getDefaultNames()

Override this method to set the default names for your device; this method is only called if we cannot defrost names set previously

Returns:

a Vector value

resetName

public String resetName(String newName)
                 throws RemoteException

Clears all names for this device and sets newName as the only name for it.

Specified by:

resetName in interface Device

Returns:

the old main name

addName

public void addName(String newName)
             throws RemoteException

Allows you to add a new name by which this device can be known (or referred to)

Specified by:

addName in interface Device

getName

public String getName()
               throws RemoteException

Returns THE name for the device, i.e. the first name on the list of names for this device

Specified by:

getName in interface Device

getNames

public Vector getNames()
                throws RemoteException

Returns all names for this device; if there are no names, you get back an empty vector.

Specified by:

getNames in interface Device

setName

public String setName(int pos,
                      String newName)
               throws RemoteException

Allows you to change the name on the list; starting index is 0;

Specified by:

setName in interface Device

Parameters:

pos - index of the name to change (corresponding to what you see when you do getNames()

newName - new name

Returns:

the old name or null if index was out of bounds

hasName

public boolean hasName(String name)
                throws RemoteException

returns true if this device can be called by the name passed as a parameter (matching is done in case-insensitive way)

Specified by:

hasName in interface Device

setState

public void setState(DeviceState state)
              throws RemoteException

This method is for "external" use only (i.e. for other people to externally reset the state of a device. By default it calls updateState(state)

Specified by:

setState in interface Device

Parameters:

state - the new state for the device

resetAllStates

public void resetAllStates()
                    throws RemoteException

Resets all the states to the default values (as defined by each device state object) -- you may want to override this method to set your own reset values of each state.

Specified by:

resetAllStates in interface Device

resetState

public void resetState()
                throws RemoteException

Resets the default state

Specified by:

resetState in interface Device

resetState

public void resetState(String name)
                throws RemoteException

Resets a particular state

Specified by:

resetState in interface Device

getState

public DeviceState getState()
                     throws RemoteException

Returns the current value of the defalult state of the device

Specified by:

getState in interface Device

getState

public DeviceState getState(String name)
                     throws RemoteException

returns the current value of a named state of this device

Specified by:

getState in interface Device

getStateNames

public Vector getStateNames()
                     throws RemoteException

Returns a vector with the names of all states of this device

Specified by:

getStateNames in interface Device

setDefaultStateName

protected void setDefaultStateName(String name)

Allows you to set the name of the device which will be considered "THE" state for the device

getDefaultStateName

protected String getDefaultStateName()

updateState

protected void updateState(DeviceState s)
                    throws RemoteException

for internal use only -- calls updateState(s, true)

updateState

protected void updateState(DeviceState s,
                           boolean announce)
                    throws RemoteException

for internal use only -- updates the state of the device to s and, optionally, sends out a notification about state change. The current consensus is that by default notifications do not include the state object. If the state does not exist, it gets created

Parameters:

s - new state of the device

announce - true if you want notification to be sent, false if you want it to be a quiet operation.

updateState

protected DeviceState updateState(String name,
                                  Object value,
                                  int confidence)
                           throws RemoteException

A shortcut method

Parameters:

name - name of the state to update

value - new value for this state

confidence - new confidence for the state

updateState

protected DeviceState updateState(String name,
                                  Object value)
                           throws RemoteException

Just lets you update the state value without changing the confidence

ensureState

protected DeviceState ensureState(String name)
                           throws RemoteException

Returns a state with given name if one exists or creates a new one

updateState

protected DeviceState updateState(String name,
                                  int value,
                                  int confidence)
                           throws RemoteException

updateState

protected DeviceState updateState(String name,
                                  int value)
                           throws RemoteException

updateState

protected DeviceState updateState(String name,
                                  boolean value,
                                  int confidence)
                           throws RemoteException

updateState

protected DeviceState updateState(String name,
                                  boolean value)
                           throws RemoteException

createStateChangeNotification

protected Secret createStateChangeNotification(DeviceState s)
                                        throws RemoteException

This method creates the state change notification. It's separated out from the updateState method so that agents can override it. By default this method uses fName variable to produce the name of the notification. For example, a notification for state change of a lamp will be named device.lamp.stateChange where "lamp" is the value of the fName variable.

Parameters:

s - new state of the device. This parameter is not used by this version of the method but may be useful for agents inheriting from this one.

Returns:

a Secret, or the notification to be sent out.