stella.nut
Class UpsDriver

java.lang.Object
  util.PropertyContainer
      util.PropertyResources
          util.PropertyBundles
              io.AbstractDriver
                  stella.nut.UpsDriver

All Implemented Interfaces:

Driver, Cloneable, ExitCleaning, Initializable, LocalizedSupplying, PropertySupplying, ResourceSupplying

public class UpsDriver
extends AbstractDriver
implements ExitCleaning

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 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 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 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

static class	UpsDriver.Client A test class.
private class	UpsDriver.UpsRefresh The task that queries the UPS demon for all served variables at certain time intervalls.

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_OK The correct answer for login processes.
private static String	CMD_DESC The description command.
private static String	CMD_GET The request command.
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_USER The username command.
private static String	CMD_VAR The variable command.
private static String	DEFCR The default end-of-line string.
static String	DEFDRIVERNAME The default ups name
private static String	DEFHOST The default host name where the server is running.
private static String	DEFLIST The default list of served variables.
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 static long	DEFREFRESH The default refresh interval in ms.
private Map<String,String>	describe The look-up table of variable description.
private Set<String>	fails The set of commands currently failed.
private BufferedReader	in The socket reader, a wrapped socket-input stream.
private boolean	islogin True, if socket is connected and ready for IO.
private boolean	isopen 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_LIST The key to the list of variables served.
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_REFRESH The key to the cache-refresh interval.
static String	KEY_USER The key pointing to the end-of-line string sent/received.
private Map<String,String>	lookup The look-up table for caching.
private BufferedWriter	out The socket writer, a wrapped socket-output stream.
private static String	SEPARATOR The separation between commands and instructions.
private Timer	update The timer for updating ups-values.
private Socket	upsd The communication socket.

Fields inherited from class io.AbstractDriver

KEY_DRIVERNAME

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 util.ResourceSupplying

KEY_URLRESOURCES, KEY_URLUSECONFIG, KEY_URLUSECURRENT, KEY_URLUSEHOME

Fields inherited from interface util.PropertySupplying

CONFIG, KEY_CLASS

Constructor Summary

UpsDriver(Map<String,String> prop)
Constructs a new ups-sensor.

Method Summary

boolean	close() Cancels this sensor reading thread.
void	exit() Exits, not caring about failures.
String	getDescription(String key) Reads the description of the sensor as provided by the underlying ups daemon.
boolean	isOpen() Returns true if we can send to the socket.
boolean	open() Initializes the driver.
private String	parseResponse(String query, String response) Parses a response by skipping over the upsname and the variable and deleting any \" from the reply.
private String	queryString(String com, String var) Constructs a query string from a variable name and a desired action.
String	readCache(String key) Reads the sensor.
private String	sendToSocket(String command) Writes to the socket writer.

Methods inherited from class io.AbstractDriver

createDriver, equals, getDriverName, hashCode

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, init, 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, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface util.ResourceSupplying

getResource, getResourceAsStream, getResources

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.Initializable

init

Field Detail

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_LIST

public static final String KEY_LIST

The key to the list of variables served.

See Also:

Constant Field Values

KEY_REFRESH

public static final String KEY_REFRESH

The key to the cache-refresh interval.

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

DEFDRIVERNAME

public static final String DEFDRIVERNAME

The default ups name

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

DEFLIST

private static final String DEFLIST

The default list of served variables.

See Also:

Constant Field Values

DEFREFRESH

private static final long DEFREFRESH

The default refresh interval in ms.

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_GET

private static final String CMD_GET

The request command.

See Also:

Constant Field Values

CMD_VAR

private static final String CMD_VAR

The variable command.

See Also:

Constant Field Values

CMD_DESC

private static final String CMD_DESC

The description command.

See Also:

Constant Field Values

ANS_OK

private static final String ANS_OK

The correct answer for login 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

SEPARATOR

private static final String SEPARATOR

The separation between commands and instructions.

See Also:

Constant Field Values

isopen

private boolean isopen

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

islogin

private boolean islogin

True, if socket is connected and ready for IO.

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.

lookup

private Map<String,String> lookup

The look-up table for caching.

describe

private Map<String,String> describe

The look-up table of variable description.

update

private Timer update

The timer for updating ups-values.

fails

private Set<String> fails

The set of commands currently failed.

Constructor Detail

UpsDriver

public UpsDriver(Map<String,String> prop)

Constructs a new ups-sensor.

Throws:

IllegalArgumentException - If no #KEY_REQUEST property is given.

Method Detail

open

public boolean open()
             throws IOException

Initializes the driver. This does the following:

• Opens a socket to the upsd using KEY_HOST and KEY_PORT.
• If login is required with the KEY_LOGIN key, the login name KEY_LOGIN and the password KEY_PASSWORD are sent.
• The look-up table is set up by parsing the KEY_LIST into served variable names. The description table is set up by immediately issuing a GET DESC . Variables not served by the underlying driver are discarded here.
• The refresh timer task is initialized and started without delay. Though it runs in a different thread, data will not be available immediately as the init method returns

Specified by:

open in interface Driver

Returns:

True if initialization was successful.

Throws:

IOException

close

public boolean close()
              throws IOException

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:

close in interface Driver

Returns:

True if clean-up was successful.

Throws:

IOException

isOpen

public boolean isOpen()

Returns true if we can send to the socket.

Specified by:

isOpen in interface Driver

Returns:

True, if a previous initialization was successful

exit

public void exit()

Exits, not caring about failures.

Specified by:

exit in interface ExitCleaning

readCache

public String readCache(String key)

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 method.

getDescription

public String getDescription(String key)

Reads the description of the sensor as provided by the underlying ups daemon. Might be unspecified, but should not be null.

sendToSocket

private String sendToSocket(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 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.

queryString

private String queryString(String com,
                           String var)

Constructs a query string from a variable name and a desired action. On sending, this string must be preceeded with CMD_GET. On response, this is the starting for successful responses.

parseResponse

private String parseResponse(String query,
                             String response)

Parses a response by skipping over the upsname and the variable and deleting any \" from the reply.