games.strategy.engine.vault
Class Vault

java.lang.Object
  extended by games.strategy.engine.vault.Vault

public class Vault
extends java.lang.Object

A vault is a secure way for the client and server to share information without trusting each other.

Data can be locked in the vault by a node. This data then is not readable by other nodes until the data is unlocked.

When the data is unlocked by the original node, other nodes can read the data. When data is put in the vault, it cant be changed by the originating node.

NOTE: to allow the data locked in the vault to be gc'd, the release(VaultID id) method should be called when it is no longer needed.

Author:
Sean Bridges

Constructor Summary
Vault(IChannelMessenger channelMessenger)
           
 
Method Summary
 byte[] get(VaultID id)
          Get the unlocked data.
 boolean isUnlocked(VaultID id)
          Note - if an id has been released, then this will return false.
 java.util.List<VaultID> knownIds()
           
 boolean knowsAbout(VaultID id)
          Do we know about the given vault id.
 VaultID lock(byte[] data)
          place data in the vault.
 void release(VaultID id)
          Allow all data associated with the given vault id to be released and garbage collected An id can be released by any node.
 void shutDown()
           
 void unlock(VaultID id)
          allow other nodes to see the data.
 void waitForID(VaultID id, long timeoutMS)
          Waits until we know about a given vault id.
 void waitForIdToUnlock(VaultID id, long timeout)
          Wait until the given id is unlocked
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Vault

public Vault(IChannelMessenger channelMessenger)
Parameters:
channelMessenger -
Method Detail

shutDown

public void shutDown()

lock

public VaultID lock(byte[] data)
place data in the vault. An encrypted form of the data is sent at this time to all nodes.

The same key used to encrypt the KNOWN_VALUE so that nodes can verify the key when it is used to decrypt the data.

Parameters:
data - - the data to lock
Returns:
the VaultId of the data

unlock

public void unlock(VaultID id)
allow other nodes to see the data.

You can only unlock data that was locked by the same instance of the Vault

Parameters:
id - - the vault id to unlock

isUnlocked

public boolean isUnlocked(VaultID id)
Note - if an id has been released, then this will return false. If this instance of vault locked id, then this method will return true if the id has not been released.

Returns:
- has this id been unlocked

get

public byte[] get(VaultID id)
           throws NotUnlockedException
Get the unlocked data.

Throws:
NotUnlockedException

knowsAbout

public boolean knowsAbout(VaultID id)
Do we know about the given vault id.


knownIds

public java.util.List<VaultID> knownIds()

release

public void release(VaultID id)
Allow all data associated with the given vault id to be released and garbage collected

An id can be released by any node.

If the id has already been released, then nothing will happen.


waitForID

public void waitForID(VaultID id,
                      long timeoutMS)
Waits until we know about a given vault id. waits for at most timeout milliseconds


waitForIdToUnlock

public void waitForIdToUnlock(VaultID id,
                              long timeout)
Wait until the given id is unlocked