UpsDriver

java.lang.Object
- util.PropertyContainer
- - io.AbstractDriver
  - - stella.nut.UpsDriver

All Implemented Interfaces:

Driver, Cloneable, ExitCleaning, Initializable, PropertySupplying
```
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.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`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.

Field Summary

Fields
Modifier and Type	Field and Description
`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.PropertyContainer
KEY_LISTSEPARATOR, KEY_MAPKEYVALUECHAR, KEY_MAPSEPARATOR

Fields inherited from interface util.PropertySupplying
CONFIG, KEY_CLASS

Constructor Summary

Constructors
Constructor and Description

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

Constructors
Constructor and Description
`UpsDriver(Map<String,String> prop)` Constructs a new ups-sensor.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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.
`void`	`init()` Initializing never fails as all relevant keys have default values.
`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.PropertyContainer
augment, augment, augment, augment, augment, clone, 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, initProperties, isNew, parseObject, parseObject, reload, reload, removeProperty, requires, rescanned, setObject, setProperties, setProperty, stringProperties, toString

Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

- 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
  - init
```
public void init()
```
    Initializing never fails as all relevant keys have default values.
    
    Specified by:
    
    init in interface Initializable
  - 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.

Class UpsDriver

Nested Class Summary

Field Summary

Fields inherited from class io.AbstractDriver

Fields inherited from class util.PropertyContainer

Fields inherited from interface util.PropertySupplying

Constructor Summary

Method Summary

Methods inherited from class io.AbstractDriver

Methods inherited from class util.PropertyContainer

Methods inherited from class java.lang.Object

Field Detail

KEY_HOST

KEY_PORT

KEY_LIST

KEY_REFRESH

KEY_CR

KEY_LOGIN

KEY_USER

KEY_PASSWORD

DEFDRIVERNAME

DEFHOST

DEFPORT

DEFLIST

DEFREFRESH

DEFLOGIN

DEFCR

CMD_LOGIN

CMD_LOGOUT

CMD_USER

CMD_PASSWORD

CMD_GET

CMD_VAR

CMD_DESC

ANS_OK

ANS_ERROR

SEPARATOR

isopen

islogin

upsd

in

out

lookup

describe

update

fails

Constructor Detail

UpsDriver

Method Detail

init

open

close

isOpen

exit

readCache

getDescription

sendToSocket

queryString

parseResponse