stella.sensor
Class Ups

java.lang.Object
  util.PropertyContainer
      util.PropertyResources
          util.PropertyBundles
              util.rmi.RmiPropertyContainer
                  util.rmi.AbstractRmiCaster
                      stella.sensor.AbstractSensor
                          stella.sensor.TimerTaskSensor
                              stella.sensor.DataSensor
                                  stella.sensor.CumulativeSensor
                                      stella.sensor.PredictiveSensor
                                          stella.sensor.SmoothingSensor
                                              stella.sensor.DerivativeSensor
                                                  stella.sensor.WeatherSensor
                                                      stella.sensor.Ups

All Implemented Interfaces:

Cloneable, Remote, Caster, DataCaster, RmiDataCaster, RmiErrorCaster, Cumulating, Deriving, Predicting, Smoothing, Telemetering, WeatherJudging, WeatherCaster, ExitCleaning, Initializable, LocalizedSupplying, PropertySupplying, ResourceSupplying, RmiCaster, RmiPropertyBearing

public abstract class Ups
extends WeatherSensor

A class to represent an ups. This requires the following things to be set up:

• The low-level control of the UPS is mastered with the NUT (Network UPS Tools) software package.
• The low-level control provides the driver to the equipment UPS.
• The demon server upsd is running on a (remote) host.
• The UPS-sensor acts as a NUT-client. It communicates with the upsd via TCP-sockets on port KEY_PORT, which should alwys be DEFPORT
• Different UPS can be specified with the KEY_UPSNAME
• If login at the start-up of the sensor and accordingly a logout from the UPS should be performed, the appropriate KEY_LOGIN should point to true.
• If a user name and/or a password should be used with the connection, the keys KEY_USER and KEY_PASSWORD should be present in the properties. Note that the password will be given in plain ASCII.
• The variable checked by this UPS-sensor should be named in the properties with the KEY_REQUEST key. The answer retrieved is passed to the abstract method processAnswer(java.lang.String) which should return a double that equals the current sensor value. If the answer is connected with a weather-event, the resolution must also be done within this method.
• Because the upsd can throw a number of error messages, this sensor can throw various error messages through its RmiErrorCaster functionality. These errors can be trapped by an appropriate error handler.

The standard sequence initiated when starting a ups-sensor involves the following steps, in sequential order.

• On thread construction, the sensor logs in at the upsd-server if the KEY_LOGIN property is true.
• At each sensor readout, a socket connection to the server at host KEY_HOST is established, using the port name specified with the KEY_PORT key. This port should always be DEFPORT. The host key should point to a valid host name.
• If a user name and/or password property is set, they are sent to the socket, first user name than password.
• The variable monitored is queried using the REQ command of the communications protocol.
• The answer received from the server is stripped for the variable name and the remaining value is passed to the processAnswer(java.lang.String) method.
• The socket connection is closed.
• A call to the sensors cancel() method performs a logout from the upsd if the KEY_LOGIN property is set and login was completed successfully at the sensor's construction.
Note that this is an abstract class. Concrete daugther classes must provide a processAnswer(java.lang.String) method. Any weather-event related issues must also be solved within this method. This is particularily true for delayed weather events. To not interfere with this weather-event generation, the standard methods used by the weather sensor will always return true.

Nested Class Summary

Nested classes/interfaces inherited from class stella.sensor.TimerTaskSensor

TimerTaskSensor.SensorRead

Nested classes/interfaces inherited from class util.PropertyResources

PropertyResources.URLResource

Field Summary

private static String	ANS_ERROR The leading string for error-replies.
private static String	ANS_LOGIN The correct answer for login processes.
private static String	ANS_REQUEST The correct answer for request processes.
private static String	CMD_LOGIN The login command.
private static String	CMD_LOGOUT The logout command.
private static String	CMD_PASSWORD The password command.
private static String	CMD_REQUEST The request command.
private static String	CMD_USER The username command.
private static String	DEFCR The default end-of-line string.
private static String	DEFHOST The default host name where the server is running.
private static boolean	DEFLOGIN The default port number for the communication to the server.
private static int	DEFPORT The default port number for the communication to the server.
private BufferedReader	in The socket reader, a wrapped socket-input stream.
private boolean	islogin True, if sensor logged in at upsd as a power-drawing unit.
static String	KEY_CR The key pointing to the end-of-line string sent/received.
static String	KEY_HOST The key to the host name of the ups-server.
static String	KEY_LOGIN The key pointing to the end-of-line string sent/received.
static String	KEY_PASSWORD The key pointing to the end-of-line string sent/received.
static String	KEY_PORT The key to the communications port to the ups-server.
static String	KEY_REQUEST The key pointing to the end-of-line string sent/received.
static String	KEY_UPSNAME Key to the UPS-name.
static String	KEY_USER The key pointing to the end-of-line string sent/received.
private BufferedWriter	out The socket writer, a wrapped socket-output stream.
private Socket	upsd The communication socket.

Fields inherited from class stella.sensor.WeatherSensor

KEY_DERIVATIVEINVALID, KEY_DERIVATIVEPARAMETER, KEY_INVERSE, KEY_INVERSEDERIVATIVE, KEY_JUDGEDERIVATIVE, KEY_JUDGEPREDICT, KEY_JUDGERAW, KEY_JUDGESMOOTH, KEY_PREDICTINVALID, KEY_PREDICTPARAMETER, KEY_RAWINVALID, KEY_RAWPARAMETER, KEY_RETARDBADDERIVATIVE, KEY_RETARDBADPREDICT, KEY_RETARDBADRAW, KEY_RETARDBADSMOOTH, KEY_RETARDGOODDERIVATIVE, KEY_RETARDGOODPREDICT, KEY_RETARDGOODRAW, KEY_RETARDGOODSMOOTH, KEY_SMOOTHINVALID, KEY_SMOOTHPARAMETER

Fields inherited from class stella.sensor.DerivativeSensor

DEFRAWDERIVATIVE, derive, KEY_DERIVATIVEADVISE, KEY_DERIVE, KEY_PATH, KEY_RAWDERIVATIVE, z

Fields inherited from class stella.sensor.SmoothingSensor

f, g, KEY_SMOOTH, KEY_SMOOTHADVISE

Fields inherited from class stella.sensor.PredictiveSensor

KEY_BASE, KEY_CHI, KEY_EXTRAPOLATE, KEY_FUTURE, KEY_PREDICTADVISE, predict

Fields inherited from class stella.sensor.CumulativeSensor

KEY_AVERAGE, KEY_MEMORY, KEY_PACK

Fields inherited from class stella.sensor.DataSensor

DEFRAWFORMAT, DEFREPORT, DEFSIGMAFORMAT, KEY_RAWFORMAT, KEY_REPORT, KEY_SIGMAFORMAT

Fields inherited from class stella.sensor.TimerTaskSensor

KEY_RESPAWN

Fields inherited from class stella.sensor.AbstractSensor

KEY_BIND, KEY_BINDNAME, KEY_CONVERT, KEY_DESCRIPTION, KEY_SENSORNAME

Fields inherited from class util.rmi.AbstractRmiCaster

ALTERNATEHOST, ALTERNATEPORT, KEY_EXPORTPORT, KEY_REGISTRYHOST, KEY_REGISTRYPORT

Fields inherited from class util.PropertyBundles

KEY_LOCALECOUNTRY, KEY_LOCALELANGUAGE, KEY_RESOURCEBUNDLES

Fields inherited from class util.PropertyResources

KEY_NOINITONCREATE, localurl, locate, POSTFIX_DIR, POSTFIX_EXT, POSTFIX_FILE, POSTFIX_LIST, POSTFIX_URL, urlset

Fields inherited from class util.PropertyContainer

KEY_LISTSEPARATOR, KEY_MAPKEYVALUECHAR, KEY_MAPSEPARATOR

Fields inherited from interface stella.rmi.RmiDataCaster

NAMING_EXTENSION

Fields inherited from interface util.PropertySupplying

CONFIG, KEY_CLASS

Fields inherited from interface util.ResourceSupplying

KEY_URLRESOURCES, KEY_URLUSECONFIG, KEY_URLUSECURRENT, KEY_URLUSEHOME

Constructor Summary

protected

Ups(Map prop) Constructs a new ups-sensor.

Method Summary

void	cancel() Cancels this sensor reading thread.
private boolean	closeSocket() Closes a client-socket to the ups server.
protected void	errorReceived(String error) Treats incoming error replies.
TimerTask	initSensorTimerTask() Initializes the thread the ups-sensor should run in.
private boolean	openSocket() Opens a client-socket to the ups-server.
protected abstract double	processAnswer(String answer) Subclasses must provide a body for this method.
protected double	readSensor() Reads the sensor.
private String	send(String command) Writes to the socket writer.
private String	sendToSocket(String command) Opens a socket to the ups-server, writes out a specified command, reads in the response and closes the socket before returning.

Methods inherited from class stella.sensor.WeatherSensor

addWeatherListener, conductOneMeasure, currentlyClear, currentlyRetarding, generateDataEvent, getMinClearUpTime, getSensorInitInfo, goodFromDerivative, goodFromPredict, goodFromRaw, goodFromSmooth, isDerivativeRetard, isPredictRetard, isRawRetard, isSmoothRetard, judgeWeather, notifyWeatherListener, removeWeatherListener, status

Methods inherited from class stella.sensor.DerivativeSensor

deriveAt, getDerivativeFormat, getDerivativeToggleInfo, getDerivator, getLastDerivative, isDerivativeAdvise, isDeriving, newData, regetDerive, registerDerivator

Methods inherited from class stella.sensor.SmoothingSensor

getLastSmooth, getSmoother, getSmoothToggleInfo, isSmoothAdvise, isSmoothing, regetSmooth, registerSmoother, smoothOne

Methods inherited from class stella.sensor.PredictiveSensor

getExtrapolation, getLastPredict, getPredictToggleInfo, isPredictAdvise, isPredicting, isReliable, predictFrom, regetPredict

Methods inherited from class stella.sensor.CumulativeSensor

cumulateOne, getLastRaw, getLastTime, getMaxSize, getMemory, getSize

Methods inherited from class stella.sensor.DataSensor

addDataListener, addRmiDataListener, exit, getRawFormat, getSigmaFormat, removeDataListener, removeRmiDataListener, report

Methods inherited from class stella.sensor.TimerTaskSensor

equals, getRawToggleInfo, getReading, getRespawn, getTimeOfRead, hashCode, isReady, regetRaw, setTimeOfRead, validReading

Methods inherited from class stella.sensor.AbstractSensor

addRmiErrorListener, createSensor, getBindName, getConvert, getSensorDescription, getSensorName, init, notifyErrorListener, removeRmiErrorListener, setConvert, toString

Methods inherited from class util.rmi.AbstractRmiCaster

bindAlternate, bindToRegistry, bindToRegistry, bindToRegistry, casterExit, casterExit, getBindName, isValid, unbindFromRegistry, unbindFromRegistry

Methods inherited from class util.rmi.RmiPropertyContainer

containsRemoteProperty, getRemoteProperties, getRemoteProperty, setRemoteProperty

Methods inherited from class util.PropertyBundles

clone, getLocalized, getLocalized, getLocalizedString, getLocalizedString, loadResource

Methods inherited from class util.PropertyResources

createFrom, createFrom, createFrom, getApplet, getAsResources, getLocalClassLoader, getPropertiesToKey, getPropertiesToKey, getResource, getResourceAsStream, getResourceFromKey, getResources, keyCreate, keyCreate, reload, setApplet

Methods inherited from class util.PropertyContainer

augment, augment, augment, defaultBoolean, defaultChar, defaultDouble, defaultFloat, defaultInt, defaultLong, defaultObject, defaultObject, defaultProperties, defaultProperty, getAsBoolean, getAsChar, getAsDouble, getAsEnums, getAsFloat, getAsInt, getAsList, getAsLong, getAsMap, getAsMap, getAsObject, getAsObject, getProperties, getProperty, has, isNew, parseObject, reload, removeProperty, rescanned, setObject, setProperties, setProperty, stringProperties

Methods inherited from class java.lang.Object

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

Methods inherited from interface stella.sensor.Cumulating

cumulateOne, getLastRaw, getLastTime, getMaxSize, getSize, getTimeOfRead, regetRaw

Methods inherited from interface util.rmi.RmiCaster

bindToRegistry, isValid, unbindFromRegistry

Methods inherited from interface stella.sensor.Telemetering

validReading

Methods inherited from interface util.PropertySupplying

defaultBoolean, defaultChar, defaultDouble, defaultFloat, defaultInt, defaultLong, defaultObject, defaultObject, defaultProperties, defaultProperty, getAsBoolean, getAsChar, getAsDouble, getAsFloat, getAsInt, getAsList, getAsLong, getAsMap, getAsObject, getAsObject, getProperties, getProperty, has, parseObject, removeProperty, setObject, setProperty, stringProperties

Methods inherited from interface util.ResourceSupplying

getResource, getResourceAsStream, getResources

Field Detail

KEY_UPSNAME

public static final String KEY_UPSNAME

Key to the UPS-name. Only necessary if more than one UPS is served.

See Also:

Constant Field Values

KEY_HOST

public static final String KEY_HOST

The key to the host name of the ups-server.

See Also:

Constant Field Values

KEY_PORT

public static final String KEY_PORT

The key to the communications port to the ups-server.

See Also:

Constant Field Values

KEY_CR

public static final String KEY_CR

The key pointing to the end-of-line string sent/received.

See Also:

Constant Field Values

KEY_LOGIN

public static final String KEY_LOGIN

The key pointing to the end-of-line string sent/received.

See Also:

Constant Field Values

KEY_USER

public static final String KEY_USER

The key pointing to the end-of-line string sent/received.

See Also:

Constant Field Values

KEY_PASSWORD

public static final String KEY_PASSWORD

The key pointing to the end-of-line string sent/received.

See Also:

Constant Field Values

KEY_REQUEST

public static final String KEY_REQUEST

The key pointing to the end-of-line string sent/received.

See Also:

Constant Field Values

DEFHOST

private static final String DEFHOST

The default host name where the server is running.

See Also:

Constant Field Values

DEFPORT

private static final int DEFPORT

The default port number for the communication to the server.

See Also:

Constant Field Values

DEFLOGIN

private static final boolean DEFLOGIN

The default port number for the communication to the server.

See Also:

Constant Field Values

DEFCR

private static final String DEFCR

The default end-of-line string.

See Also:

Constant Field Values

CMD_LOGIN

private static final String CMD_LOGIN

The login command.

See Also:

Constant Field Values

CMD_LOGOUT

private static final String CMD_LOGOUT

The logout command.

See Also:

Constant Field Values

CMD_USER

private static final String CMD_USER

The username command.

See Also:

Constant Field Values

CMD_PASSWORD

private static final String CMD_PASSWORD

The password command.

See Also:

Constant Field Values

CMD_REQUEST

private static final String CMD_REQUEST

The request command.

See Also:

Constant Field Values

ANS_LOGIN

private static final String ANS_LOGIN

The correct answer for login processes.

See Also:

Constant Field Values

ANS_REQUEST

private static final String ANS_REQUEST

The correct answer for request processes.

See Also:

Constant Field Values

ANS_ERROR

private static final String ANS_ERROR

The leading string for error-replies.

See Also:

Constant Field Values

islogin

private boolean islogin

True, if sensor logged in at upsd as a power-drawing unit.

upsd

private Socket upsd

The communication socket. This is a client socket.

in

private BufferedReader in

The socket reader, a wrapped socket-input stream.

out

private BufferedWriter out

The socket writer, a wrapped socket-output stream.

Constructor Detail

Ups

protected Ups(Map prop)
       throws RemoteException

Constructs a new ups-sensor.

Throws:

IllegalArgumentException - If no KEY_REQUEST property is given.

RemoteException

Method Detail

initSensorTimerTask

public TimerTask initSensorTimerTask()

Initializes the thread the ups-sensor should run in. If the KEY_LOGIN property is true, this sensor logs in at the upsd-server.

Specified by:

initSensorTimerTask in interface Telemetering

Overrides:

initSensorTimerTask in class TimerTaskSensor

Returns:

The ready-to-start timer-task of this sensor.

See Also:

Telemetering.getRespawn()

cancel

public void cancel()

Cancels this sensor reading thread. If at initalizing the sensor logged successfully into the upsd with the CMD_LOGIN command, a logout is performed prior to stopping this thread.

Specified by:

cancel in interface Telemetering

Overrides:

cancel in class TimerTaskSensor

readSensor

protected double readSensor()

Reads the sensor. This method sends a request for a named variable (KEY_REQUEST) to the upsd. The incomming reply is stripped from the confirmation part and only the variable value is passed to the processAnswer(java.lang.String) method.

Specified by:

readSensor in class TimerTaskSensor

See Also:

ConvertToPhysical

processAnswer

protected abstract double processAnswer(String answer)

Subclasses must provide a body for this method. It must do the following

• Interpret the returned requested variable value as a double.
• If the interpretation shows that the weather conditions should change, a weather event should be generated. If this involves some retardation, this must also be handled here.
• If the interpretation reveals a condition that cannot be handled as a simple weather event, an appropriate error event should be generated and passed to the listeners.
• The weather-event notification mechanism is still working. If the class wants to use this one, either of the three WeatherJudging methods should be overridn.

openSocket

private boolean openSocket()

Opens a client-socket to the ups-server. If the opening of the client socket was successful, the I/O streams associated with the socket are also opened and wrapped into a buffered reader/writer.

Returns:

True, if opening was successful.

closeSocket

private boolean closeSocket()

Closes a client-socket to the ups server. If streams where associated to the sockets, they are closed seperately before closing the socket connetion.

Returns:

True, if closing was successful.

send

private String send(String command)

Writes to the socket writer. The string read in as a response from the server, casted to upper case, is returned. If the response read in from the socket indicates an error message, the response is passed to the errorReceived(java.lang.String) method, after the leading ANS_ERROR code has been stripped from the response.

This method expects the streams to be open, no further checks are made.

sendToSocket

private String sendToSocket(String command)

Opens a socket to the ups-server, writes out a specified command, reads in the response and closes the socket before returning.

errorReceived

protected void errorReceived(String error)

Treats incoming error replies. Depending on the error it is either sent as a status or an appropriate error message to registered error listeners. Additionally, the plain error message is passed to the Syslog. All errors should occur at each request and should therefore be traceable at startup.

Parameters:

error - The error message without the leading ANS_ERROR.