equip.data
Class DataProxy

java.lang.Object
  equip.runtime.Object
      equip.runtime.ValueBase
          equip.net.ServiceProxy
              equip.data.DataProxy

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

DataProxyImpl, Server

public abstract class DataProxy

extends ServiceProxy

The main API for a dataspace replica, whether client or server. Note that equip.data.beans provides an alternative and simple Java API IDataspace for dataspaces using this.

Field Summary

ItemBinding[]

initialItems Internal - any initial data items to place into the dataspace (e.g. when de-serialised)

Fields inherited from class equip.net.ServiceProxy

serviceMoniker

Constructor Summary

DataProxy()
Default no-arg constructor

Method Summary

boolean	_equals_helper(DataProxy c) Internal IDL-generated equality test helper
boolean	_matches_helper(DataProxy c) Internal IDL-generated match test helper
abstract void	activateAsync() Create a thread to repeatedly attempt to activate this dataspace (assuming that it is a client) whenever its activation fails.
abstract void	addEvent(Event event) Add a new event into the dataspace.
abstract void	addItem(ItemData item, int locked, boolean processBound, boolean local, Lease itemLease) add item event helper - create and publish an AddEvent.
abstract void	beginBusy() this dangerous internal API lets you suspend the enactment of events; also make a matching call to endBusy().
abstract DataSession	createSession(DataCallback callback, ValueBase closure) Create a new data session in which to express interest in events and data items and to get callbacks/notifications.
abstract void	deleteItem(GUID id, boolean local) delete item event helper - create and publish an DeleteEvent.
abstract void	deleteSession(DataSession session) Delete a DataSession previously created with createSession(equip.data.DataCallback, equip.runtime.ValueBase); effectively any remaining EventPatterns will be removed.
abstract void	endBusy() this dangerous internal API lets you resume the enactment of events; only call to match a previous call to beginBusy().
boolean	equals(java.lang.Object c) Standard IDL-generated equality test.
abstract ItemData	getItem(GUID id) Get an ItemData from the local dataspace by item GUID.
abstract ItemBinding	getItemBinding(GUID id) Get an ItemBinding from the local dataspace by item GUID.
java.lang.String	getModuleName() IDL-generated helper routine to get module name (currently unimplemented).
abstract GUID	getResponsible() Get this dataspace replica's 'responsible' GUID, which is a globally unique identifier for this dataspace replica.
boolean	matches(java.lang.Object c) Standard IDL-generated template match test.
abstract void	queueEvent(Event event) (always) Queued add of a new event into the dataspace.
void	readObject(ObjectInputStream in) Internal IDL-generated serialisation helper.
abstract void	setDefaultAgent(GUID defaultAgentId) Set a default GUID to be used as the default owner and/or requestor for locally generated events and data items.
abstract void	setPersist(boolean persistFlag) Whether this dataspace replica should try to associate persistently with its server/peer.
abstract void	terminate() Destroy this dataspace, terminating any communication and threads and (hopefully) allowing all resources to be released/GCed.
abstract void	updateItem(ItemData item, boolean local, boolean reliable) update item event helper - create and publish an UpdateEvent with default priority (0).
abstract void	updateItem2(ItemData item, boolean local, boolean reliable, int priority) update item event helper - create and publish an UpdateEvent.
abstract void	waitForEvents(boolean local) Block and wait for all pending events to be enacted.
void	writeObject(ObjectOutputStream out) Internal IDL-generated serialisation helper.

Methods inherited from class equip.net.ServiceProxy

_equals_helper, _matches_helper, activate, deactivate

Methods inherited from class equip.runtime.ValueBase

_equals_helper, _matches_helper, clone

Methods inherited from class java.lang.Object

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

Field Detail

initialItems

public ItemBinding[] initialItems

Internal - any initial data items to place into the dataspace (e.g. when de-serialised)

Constructor Detail

DataProxy

public DataProxy()

Default no-arg constructor

Method Detail

activateAsync

public abstract void activateAsync()

Create a thread to repeatedly attempt to activate this dataspace (assuming that it is a client) whenever its activation fails. This is an alternative to ServiceProxy.activate(equip.net.DeactivateCallback, equip.runtime.ValueBase) and ServiceProxy.deactivate() which are also implemented for direct control over activation.

setPersist

public abstract void setPersist(boolean persistFlag)

Whether this dataspace replica should try to associate persistently with its server/peer. A persistent association will not be garbage collected when the underlying network connection is removed or fails. This option is largely untested at the moment, and should really have a Lease mechanism to handle garbage collection: use with care.

Note that replicas are identified to each other by the responsible GUID of each.

Parameters:

persistFlag - Whether to connect persistently.

addEvent

public abstract void addEvent(Event event)

Add a new event into the dataspace. Note that if the dataspace is already busy (e.g. in an event notification callback) then the event will be queued internally for subsequent asynchronous delivery.

Parameters:

event - The event to published.

queueEvent

public abstract void queueEvent(Event event)

(always) Queued add of a new event into the dataspace.

Parameters:

event - The event to published.

getItemBinding

public abstract ItemBinding getItemBinding(GUID id)

Get an ItemBinding from the local dataspace by item GUID.

Parameters:

id - The item's GUID.

Returns:

The item's binding to the dataspace replica, or null if unknown.

getItem

public abstract ItemData getItem(GUID id)

Get an ItemData from the local dataspace by item GUID.

Parameters:

id - The item's GUID.

Returns:

The item's value in the dataspace replica, or null if unknown.

setDefaultAgent

public abstract void setDefaultAgent(GUID defaultAgentId)

Set a default GUID to be used as the default owner and/or requestor for locally generated events and data items.

Parameters:

defaultAgentId - GUID to use as default owner/requestor

addItem

public abstract void addItem(ItemData item,
                             int locked,
                             boolean processBound,
                             boolean local,
                             Lease itemLease)

add item event helper - create and publish an AddEvent.

Parameters:

item - The value of the new item (including id).

locked - See ItemBindingInfo.locked.

processBound - See ItemBindingInfo.processBound.

local - See ItemBindingInfo.local.

itemLease - See ItemBindingInfo.itemLease.

updateItem2

public abstract void updateItem2(ItemData item,
                                 boolean local,
                                 boolean reliable,
                                 int priority)

update item event helper - create and publish an UpdateEvent. NOTE: if this is an item with a lease and you want the lease to be renewed then use an addItem repeatedly instead (with the new Lease value in the ItemBinding).

Parameters:

item - The new value of the item (including original id).

local - See EventMetadata.local.

reliable - See EventMetadata.reliable.

priority - See EventMetadata.priority.

updateItem

public abstract void updateItem(ItemData item,
                                boolean local,
                                boolean reliable)

update item event helper - create and publish an UpdateEvent with default priority (0). NOTE: if this is an item with a lease and you want the lease to be renewed then use an addItem repeatedly instead (with the new Lease value in the ItemBinding).

Parameters:

item - The new value of the item (including original id).

local - See EventMetadata.local.

reliable - See EventMetadata.reliable.

deleteItem

public abstract void deleteItem(GUID id,
                                boolean local)

delete item event helper - create and publish an DeleteEvent.

Parameters:

id - The GUID of the item to be deleted.

local - See EventMetadata.local.

waitForEvents

public abstract void waitForEvents(boolean local)

Block and wait for all pending events to be enacted. Be careful or this will deadlock, so make sure nothing else is going on in that thread!. Only in Java, at the moment (2003-10-16).

Parameters:

local - Wait only for local events (if false, then also send a message to the server dataspace and wait for it to come back as well).

createSession

public abstract DataSession createSession(DataCallback callback,
                                          ValueBase closure)

Create a new data session in which to express interest in events and data items and to get callbacks/notifications. See also information about DataCallback and (usually easier to use) DataCallbackPost.

Parameters:

callback - Event-handling subclass of DataCallback or DataCallbackPost, notified about events matching any EventPatterns that are added to new session.

closure - Optional application parameter provided to the callback notification (can be null).

Returns:

A new DataSession to which EventPatterns can be added to cause replication and/or notifications of events and items.

deleteSession

public abstract void deleteSession(DataSession session)

Delete a DataSession previously created with createSession(equip.data.DataCallback, equip.runtime.ValueBase); effectively any remaining EventPatterns will be removed.

In C++ the caller will still hold the last reference to the data session object, which must be released in order for the session object to actually be deleted.

Parameters:

session - The DataSession object returned from createSession(equip.data.DataCallback, equip.runtime.ValueBase) to be deleted from the dataspace.

beginBusy

public abstract void beginBusy()

this dangerous internal API lets you suspend the enactment of events; also make a matching call to endBusy(). Easy to deadlock with unmatched calls!

endBusy

public abstract void endBusy()

this dangerous internal API lets you resume the enactment of events; only call to match a previous call to beginBusy(). Easy to deadlock - or break synchronization - with unmatched calls!

getResponsible

public abstract GUID getResponsible()

Get this dataspace replica's 'responsible' GUID, which is a globally unique identifier for this dataspace replica.

Returns:

The dataspace replica's own GUID.

terminate

public abstract void terminate()

Destroy this dataspace, terminating any communication and threads and (hopefully) allowing all resources to be released/GCed.

getModuleName

public java.lang.String getModuleName()

IDL-generated helper routine to get module name (currently unimplemented).

Overrides:

getModuleName in class ServiceProxy

Returns:

name of this class's module

equals

public boolean equals(java.lang.Object c)

Standard IDL-generated equality test.

Overrides:

equals in class ServiceProxy

Parameters:

c - The object to be compared against this.

Returns:

true if this is equal to c

_equals_helper

public boolean _equals_helper(DataProxy c)

Internal IDL-generated equality test helper

matches

public boolean matches(java.lang.Object c)

Standard IDL-generated template match test.

Overrides:

matches in class ServiceProxy

Parameters:

c - The object to be checked against this template.

Returns:

true if this (as a template) matches the argument

_matches_helper

public boolean _matches_helper(DataProxy c)

Internal IDL-generated match test helper

writeObject

public void writeObject(ObjectOutputStream out)
                 throws java.io.IOException

Internal IDL-generated serialisation helper. Used by ObjectInputStream and ObjectOutputStream only.

Overrides:

writeObject in class ServiceProxy

Throws:

java.io.IOException

readObject

public void readObject(ObjectInputStream in)
                throws java.io.IOException,
                       java.lang.ClassNotFoundException,
                       java.lang.InstantiationException

Internal IDL-generated serialisation helper. Used by ObjectInputStream and ObjectOutputStream only.

Overrides:

readObject in class ServiceProxy

Throws:

java.io.IOException

java.lang.ClassNotFoundException

java.lang.InstantiationException