com.phidgets
Class Dictionary

java.lang.Object
  com.phidgets.Dictionary

public class Dictionary

extends java.lang.Object

This class represents the Phidget Dictionary.

The Phidget Dictionary is a service provided by the Phidget Webservice. The Webservice maintains a centralized dictionary of key-value pairs that can be accessed and changed from any number of clients.

Note that the Webservice uses this dictionary to control access to Phidgets through the openRemote and openRemoteIP interfaces, and as such, you should never add or modify a key that starts with /PSK/ or /PCK/, unless you want to explicitly modify Phidget specific data -- and this is highly discouraged, as it's very easy to break things. Listening to these keys is fine if so desired.

The intended use for the dictionary is as a central repository for communication and persistent storage of data between several client applications. As an example - a higher level interface exposed by one application -- which controls the Phidgets, for others to access -- rather then every client talking directly to the Phidgets themselves.

The dictionary makes use of extended regular expressions for key matching.

Author:

Phidgets Inc.

Field Summary

long

handle

Constructor Summary

Dictionary()
The default constructor.

Method Summary

void	add(java.lang.String key, java.lang.String val) Adds a new key to the Dictionary, or modifies the value of an existing key.
void	add(java.lang.String key, java.lang.String val, boolean persistent) Adds a new key to the Dictionary, or modifies the value of an existing key.
void	addServerConnectListener(ServerConnectListener l) Adds an serverConnect listener.
void	addServerDisconnectListener(ServerDisconnectListener l) Adds an serverDisconnect listener.
void	close() Closes this Dictionary.
java.lang.String	get(java.lang.String key) Gets the value for a key.
java.lang.String	getServerAddress() Returns the Address of a Phidget Webservice when this Dictionary was opened as remote.
java.lang.String	getServerID() Returns the Server ID of a Phidget Webservice when this Dictionary was opened as remote.
int	getServerPort() Returns the Port of a Phidget Webservice when this Dictionary was opened as remote.
boolean	isAttached() Returns the attached status of this Dictionary.
boolean	isAttachedToServer() Returns the network attached status for remotely opened Phidgets.
void	open(java.lang.String serverID) Open this Dictionary remotely using a Server ID.
void	open(java.lang.String ipAddress, int port) Open this Dictionary remotely using an IP Address.
void	open(java.lang.String ipAddress, int port, java.lang.String password) Open this Dictionary remotely and securely, using an IP Address.
void	open(java.lang.String serverID, java.lang.String password) Open this Dictionary remotely and securely, using a Server ID.
void	remove(java.lang.String pattern) Removes a key, or set of keys, from the Dictionary.
void	removeServerConnectListener(ServerConnectListener l) Removes an serverConnect listener.
void	removeServerDisconnectListener(ServerDisconnectListener l) Removes an serverDisconnect listener.
java.lang.String	toString() Return a Sring describing this dictionary.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

handle

public long handle

Constructor Detail

Dictionary

public Dictionary()
           throws PhidgetException

The default constructor. Creating a Phidget Dictionary object will initialize the dictionary handle internally, but open still needs to be called to actually work with it.

Method Detail

getServerAddress

public final java.lang.String getServerAddress()
                                        throws PhidgetException

Returns the Address of a Phidget Webservice when this Dictionary was opened as remote. This may be an IP Address or a hostname.

Returns:

Server Address

Throws:

PhidgetException - if this Dictionary was not opened.

getServerID

public final java.lang.String getServerID()
                                   throws PhidgetException

Returns the Server ID of a Phidget Webservice when this Dictionary was opened as remote. This is an arbitrary server identifier, independant of IP address and Port.

Returns:

Server ID

Throws:

PhidgetException - if this Dictionary was not opened.

getServerPort

public final int getServerPort()
                        throws PhidgetException

Returns the Port of a Phidget Webservice when this Dictionary was opened as remote.

Returns:

Server Port

Throws:

PhidgetException - if this Dictionary was not opened.

isAttached

public final boolean isAttached()
                         throws PhidgetException

Returns the attached status of this Dictionary.

Returns:

Status

Throws:

PhidgetException - If this Dictionary is not opened.

isAttachedToServer

public final boolean isAttachedToServer()
                                 throws PhidgetException

Returns the network attached status for remotely opened Phidgets. This method returns True or False, depending on whether a connection to the Phidget WebService is open - or not. If this is false for a remote Phidget then the connection is not active - either because a connection has not yet been established, or because the connection was terminated.

Returns:

Status

Throws:

PhidgetException - If this Phidget is not opened.

add

public final void add(java.lang.String key,
                      java.lang.String val)
               throws PhidgetException

Adds a new key to the Dictionary, or modifies the value of an existing key.

The key can only contain numbers, letters, "/", ".", "-", "_", and must begin with a letter, "_" or "/".

The value can contain any value.

The key will stay in the dictionary until explicitly removed.

Throws:

PhidgetException

add

public final void add(java.lang.String key,
                      java.lang.String val,
                      boolean persistent)
               throws PhidgetException

Adds a new key to the Dictionary, or modifies the value of an existing key.

The key can only contain numbers, letters, "/", ".", "-", "_", and must begin with a letter, "_" or "/".

The value can contain any value.

The persistent value controls whether a key will stay in the dictionary after the client that created it disconnects. If persistent == 0, the key is removed when the connection closes. Otherwise the key remains in the dictionary until it is explicitly removed.

Throws:

PhidgetException

remove

public final void remove(java.lang.String pattern)
                  throws PhidgetException

Removes a key, or set of keys, from the Dictionary.

The key name is a regular expressions pattern, and so care must be taken to only have it match the specific keys you want to remove.

Throws:

PhidgetException

get

public final java.lang.String get(java.lang.String key)
                           throws PhidgetException

Gets the value for a key.

Throws:

PhidgetException

open

public final void open(java.lang.String ipAddress,
                       int port,
                       java.lang.String password)
                throws PhidgetException

Open this Dictionary remotely and securely, using an IP Address.

This method is the same as open(String ipAddress, int port), except that it specifies a password. This password can be set as a parameter when starting the Phidget Webservice.

Throws:

PhidgetException

open

public final void open(java.lang.String ipAddress,
                       int port)
                throws PhidgetException

Open this Dictionary remotely using an IP Address.

This version of open is network based, and relies on the Phidget Webservice running at the specified Address and Port before open is called.

Parameters:

ipAddress - IP Address or hostname of the Phidget Webservice

port - Port of the Phidget Webservice

Throws:

PhidgetException - if the Phidget Webservice cannot be contacted

open

public final void open(java.lang.String serverID,
                       java.lang.String password)
                throws PhidgetException

Open this Dictionary remotely and securely, using a Server ID.

This method is the same as open(String serverID), except that it specifies a password. This password can be set as a parameter when starting the Phidget Webservice.

Throws:

PhidgetException

open

public final void open(java.lang.String serverID)
                throws PhidgetException

Open this Dictionary remotely using a Server ID.

This version of open is network based.

Parameters:

serverID - ServerID of the Phidget Webservice

Throws:

PhidgetException

close

public final void close()
                 throws PhidgetException

Closes this Dictionary. This will shut down all threads dealing with this Dictionary and you won't receive any more events.

Throws:

PhidgetException - If this Dictionary is not opened.

addServerConnectListener

public final void addServerConnectListener(ServerConnectListener l)

Adds an serverConnect listener. The serverConnect handler is a method that will be called when a connection to a server is made

There is no limit on the number of serverConnect handlers that can be registered for a particular Manager.

Parameters:

l - An implemetation of the ServerConnectListener interface

removeServerConnectListener

public final void removeServerConnectListener(ServerConnectListener l)

Removes an serverConnect listener. This will remove a previously added serverConnect listener.

addServerDisconnectListener

public final void addServerDisconnectListener(ServerDisconnectListener l)

Adds an serverDisconnect listener. The serverDisconnect handler is a method that will be called when a connection to a server is terminated.

There is no limit on the number of serverDisconnect handlers that can be registered for a particular Manager.

Parameters:

l - An implemetation of the ServerDisconnectListener interface

removeServerDisconnectListener

public final void removeServerDisconnectListener(ServerDisconnectListener l)

Removes an serverDisconnect listener. This will remove a previously added serverDisconnect listener.

toString

public java.lang.String toString()

Return a Sring describing this dictionary.