com.phidgets
Class Dictionary

java.lang.Object
  extended bycom.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.