org.elkoserver.objdb
Class ObjDBRemote

java.lang.Object
  org.elkoserver.objdb.ObjDBRemote

All Implemented Interfaces:

TypeResolver, ObjDB

public class ObjDBRemote
extends Object

Asynchronous access to a remote instance of the object database. This is implemented as a connection to an external repository.

Constructor Summary

ObjDBRemote(ServiceFinder serviceFinder, NetworkManager networkManager, String localName, BootProperties props, String propRoot, Trace appTrace)
Create an object to access a remote object repository.

Method Summary

void	addClass(String tag, Class<?> type) Inform the object database about a mapping from a JSON object type tag string to a Java class.
protected Object	decodeJSONObject(JSONObject jsonObj) Convert a parsed JSON object description into the object it describes.
void	getObject(String ref, String collectionName, ArgRunnable handler) Fetch an object from the repository.
void	putObject(String ref, Encodable obj, String collectionName, boolean requireNew, ArgRunnable handler) Store an object into the repository.
void	queryObjects(JSONObject template, String collectionName, int maxResults, ArgRunnable handler) Query one or more objects from the object database.
void	removeObject(String ref, String collectionName, ArgRunnable handler) Delete an object from the repository.
Class<?>	resolveType(Class<?> baseType, String typeName) Get the class associated with a given JSON type tag string.
void	shutdown() Shutdown the object database.
void	updateObject(String ref, int version, Encodable obj, String collectionName, ArgRunnable handler) Update an object in the repository.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ObjDBRemote

public ObjDBRemote(ServiceFinder serviceFinder,
                   NetworkManager networkManager,
                   String localName,
                   BootProperties props,
                   String propRoot,
                   Trace appTrace)

Create an object to access a remote object repository.

The repository to connect to is specified by configuration properties, but may be indicated in one of two different ways:

The property "propRoot.service", if given, indicates a repository name to ask the Broker for. Specifying this property as the special value 'any' indicates that any repsitory that the Broker knows about will be acceptable.

Alternatively, a repository host may be specified directly using the "propRoot.host" property.

However the repository is indicated, the following properties are also recognized:

The boolean property "propRoot.dontlog", if true, indicates that message traffic between this server and the remote repository should not be logged, even if this server is otherwise logging all message traffic. If unspecified, it defaults to false.

The property "propRoot.retry" may specify a retry interval (in seconds), at which successive attempts will be made to connect to the external repository if earlier attempts have failed. The value -1 (which is the default if this property is left unspecified) indicates that no retries should be attempted.

The property "propRoot.classdesc" may specify a (comma-separated) list of references to class description objects to read from the repository at startup time.

Parameters:

serviceFinder - Access to broker, to locate repository server.

networkManger - Network manager, for making outbound connections.

localName - Name of this server.

props - Properties that the hosting server was configured with

propRoot - Prefix string for generating relevant configuration property names.

appTrace - Trace object for event logging.

Method Detail

getObject

public void getObject(String ref,
                      String collectionName,
                      ArgRunnable handler)

Fetch an object from the repository.

Parameters:

ref - Reference string naming the object desired.

collectionName - Name of collection to get from, or null to take the configured default.

handler - Handler to be called with the result. The result will be the object requested, or null if the object could not be retrieved.

putObject

public void putObject(String ref,
                      Encodable obj,
                      String collectionName,
                      boolean requireNew,
                      ArgRunnable handler)

Store an object into the repository.

Parameters:

ref - Reference string naming the object to be stored.

obj - The object to be stored.

collectionName - Name of collection to put into, or null to take the configured default (or the db doesn't use this abstraction).

requireNew - If true, require object 'ref' not already exist.

handler - Handler to be called with the result. The result will be a status indicator: an error message string if there was an error, or null if the operation was successful.

updateObject

public void updateObject(String ref,
                         int version,
                         Encodable obj,
                         String collectionName,
                         ArgRunnable handler)

Update an object in the repository.

Parameters:

ref - Reference string naming the object to be stored.

version - Version number of the object to be upated.

obj - The object to be stored.

collectionName - Name of collection to put into, or null to take the configured default (or the db doesn't use this abstraction).

handler - Handler to be called with the result. The result will be a status indicator: an error message string if there was an error, or null if the operation was successful.

queryObjects

public void queryObjects(JSONObject template,
                         String collectionName,
                         int maxResults,
                         ArgRunnable handler)

Query one or more objects from the object database.

Parameters:

template - Template object for the objects desired.

collectionName - Name of collection to query, or null to take the configured default.

maxResults - Maximum number of result objects to return, or 0 to indicate no fixed limit.

handler - Handler to be called with the results. The results will be an array of the object(s) requested, or null if no objects could be retrieved.

removeObject

public void removeObject(String ref,
                         String collectionName,
                         ArgRunnable handler)

Delete an object from the repository. It is not considered an error to attempt to remove an object that is not there; such an operation always succeeds.

Parameters:

ref - Reference string naming the object to remove.

collectionName - Name of collection to delete from, or null to take the configured default (or the db doesn't use this abstraction).

handler - Handler to be called with the result. The result will be a status indicator: an error message string if there was an error, or null if the operation was successful.

shutdown

public void shutdown()

Shutdown the object database.

addClass

public void addClass(String tag,
                     Class<?> type)

Inform the object database about a mapping from a JSON object type tag string to a Java class.

Specified by:

addClass in interface ObjDB

Parameters:

tag - The JSON object type tag string.

type - The class that 'tag' labels.

decodeJSONObject

protected Object decodeJSONObject(JSONObject jsonObj)

Convert a parsed JSON object description into the object it describes.

Parameters:

jsonObj - The object being decoded.

Returns:

the object described by 'jsonObj'.

resolveType

public Class<?> resolveType(Class<?> baseType,
                            String typeName)

Get the class associated with a given JSON type tag string.

Specified by:

resolveType in interface TypeResolver

Parameters:

baseType - Base class from which result class must be derived.

typeName - JSON type tag identifying the desired class.

Returns:

a class named by 'typeName' suitable for assignment to a method or constructor parameter of class 'baseType'.