livespace.services
Class EntityClient

java.lang.Object
  livespace.services.EntityContainer
      livespace.services.EntityClient

All Implemented Interfaces:

PropertyListener, Disposable, Closeable, EventListener, CloseListener, NotificationListener

public class EntityClient
extends EntityContainer

A container that populates its entity registry with available entities matching a type query and keeps them up to date with state changes.

NOTES:

• Entity instance allocation: both server and client containers maintain a *per-container* weak cache of all entity instances anywhere in the tree of objects held by the container (this does *not* include other data object types). This means that, if an entity anywhere in the tree is remotely deleted and then added again, and the client still has reference(s) to it (e.g. has added a listener), then the original entity instance will be reused. This allows clients to safely hold references to entities that will stay "live" across entity delete/add cycles (e.g. remote server start/stop).
• The entity "container" property: when an entity is added to a container, the container property will be set and generate a property changed event *after* it is added to the registry. When an entity is removed from a container it will generate a property change event *after* it is removed from the registry. The container property can thus be used by entity listeners to detect when it is added and deleted. The downside is that listeners of entity add events will see the container as being null.

todo work out to better handle the case where we see two init's in quick succession: one global on server start and one from a "find". This often happens in tests where server and client start up very close to each other, but will happen in the field from time to time. Since most clients don't bother with "synchronised (entities) ..." around blocks of changes, this can lead to strange behaviours.

Author:

Matthew Phillips

See Also:

EntityServer

Nested Class Summary

Nested classes/interfaces inherited from class livespace.services.EntityContainer

EntityContainer.EmitNotificationTask

Field Summary

protected livespace.services.EntityClient.DeadEntityWatcher	deadEntityWatcher
protected boolean	inhibitEventHandling
protected Subscription	subscription

Fields inherited from class livespace.services.EntityContainer

containerId, elvin, entities, room, scheduler

Constructor Summary

EntityClient(Elvin elvin, RoomEntity room, String entityType)
Create an instance within a given room scope (ie discovered entities are visible only to the current room).

EntityClient(Elvin elvin, RoomEntity room, String entityType, EntityRegistry entities)
Create an instance within a given room scope (ie discovered entities are visible only to the current room).

EntityClient(Elvin elvin, String entityType)
Create an instance with no room scope (ie contained entities have global scope).

Method Summary

Notification	createRequestNtfn(Entity entity, String action) Create the base template for a Livespace request notification, filling in all required fields.
Notification	createUpdateNtfn() Create the base template for a Livespace update request, filling in all required fields.
protected XmlInput	createXmlInput() Overriden to enable the XmlEntityCodec.clearUndefinedProperties setting so that clients clear out any defunct properties.
void	dispose() Dispose of the object (unregister listeners, close open resources etc).
void	forcePingAll(long responseTimeout) Force client to ping all current entities for liveness.
protected void	handleNotification(NotificationEvent e)
protected void	ping(Collection<Entity> pinged, Entity entity) Send a ping to an entity, adding it to pinged if successful.
void	propertyValueChanged(PropertyEvent e) Handles property changes to entities in the registry by emitting the appropriate update requests.
void	setLivenessTimeouts(long livenessTimeout, long scanInterval, long pingTimeout) Change liveness timeouts used for detecting dead entities.
protected void	subscribe(String entityType)

Methods inherited from class livespace.services.EntityContainer

close, connectionClosed, createEntity, createXmlOutput, emit, emitAsync, getOrCreateEntity, isClosed, isInResponseToMe, mutex, notificationReceived, read, registerEntityTree, setContainerRecursively, setContainerRecursively, setDefaultUpdaterForThread, setUpdateExecutor, shouldPublish, splitPropertyPath, write, write

Methods inherited from class java.lang.Object

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

Field Detail

subscription

protected Subscription subscription

inhibitEventHandling

protected boolean inhibitEventHandling

deadEntityWatcher

protected livespace.services.EntityClient.DeadEntityWatcher deadEntityWatcher

Constructor Detail

EntityClient

public EntityClient(Elvin elvin,
                    String entityType)
             throws IOException

Create an instance with no room scope (ie contained entities have global scope). This version is usually used just for hosting a RoomEntity.

Parameters:

elvin - The Elvin service.

entityType - The type of entity to discover. This is the value returned by Entity.getType().

Throws:

IOException

See Also:

EntityClient(Elvin, RoomEntity, String)

EntityClient

public EntityClient(Elvin elvin,
                    RoomEntity room,
                    String entityType)
             throws IOException

Create an instance within a given room scope (ie discovered entities are visible only to the current room).

Parameters:

elvin - The Elvin connection.

room - The room the entities are part of. This may be null meaning the entities are not part of a room.

entityType - The type of entity to discover. This is the value returned by Entity.getType().

Throws:

IOException

See Also:

EntityClient(Elvin, RoomEntity, String, EntityRegistry)

EntityClient

public EntityClient(Elvin elvin,
                    RoomEntity room,
                    String entityType,
                    EntityRegistry entities)
             throws IOException

Create an instance within a given room scope (ie discovered entities are visible only to the current room).

Parameters:

elvin - The Elvin connection.

room - The room the entities are part of. This may be null meaning the entities are not part of a room.

entityType - The type of entity to discover. This is the value returned by Entity.getType().

entities - The initial entity registry instance. This is to allow a client to add a listener *before* the client starts populating the registry. It is an error for the the registry not to be empty.

Throws:

IOException

Method Detail

dispose

public void dispose()

Description copied from interface: Disposable

Dispose of the object (unregister listeners, close open resources etc). It should be safe to call this method more than once. Note for beans that support client event listeners: if there are listeners registered when this is called, this method should do nothing.

Specified by:

dispose in interface Disposable

Overrides:

dispose in class EntityContainer

subscribe

protected void subscribe(String entityType)
                  throws IOException

Throws:

IOException

createUpdateNtfn

public Notification createUpdateNtfn()

Create the base template for a Livespace update request, filling in all required fields. This is a shortcut that generates a broadcast request that applies to all entities of the class being managed by the client

Returns:

The template notification. Clients will fill in the fields with values to be updated.

See Also:

createUpdateNtfn()

createRequestNtfn

public Notification createRequestNtfn(Entity entity,
                                      String action)

Create the base template for a Livespace request notification, filling in all required fields. Clients will fill in the fields with values to be updated.

Parameters:

entity - The entity to be updated. May be null to apply to all entities of the class being managed by the client.

Returns:

A template notification.

handleNotification

protected void handleNotification(NotificationEvent e)

Specified by:

handleNotification in class EntityContainer

propertyValueChanged

public void propertyValueChanged(PropertyEvent e)

Handles property changes to entities in the registry by emitting the appropriate update requests.

setLivenessTimeouts

public void setLivenessTimeouts(long livenessTimeout,
                                long scanInterval,
                                long pingTimeout)

Change liveness timeouts used for detecting dead entities. All durations are in milliseconds.

Parameters:

livenessTimeout - New max time before an entity may be checked for liveness.

scanInterval - The interval between scans.

pingTimeout - Max time for server to respond to a ping.

createXmlInput

protected XmlInput createXmlInput()

Overriden to enable the XmlEntityCodec.clearUndefinedProperties setting so that clients clear out any defunct properties.

Overrides:

createXmlInput in class EntityContainer

forcePingAll

public void forcePingAll(long responseTimeout)

Force client to ping all current entities for liveness. This is mainly for testing: clients should not normally call this as it could generate a lot of unneccesary traffic.

Parameters:

responseTimeout - The maximum amount of time pinged entities have to respond: after this they are counted as dead and deleted.

ping

protected void ping(Collection<Entity> pinged,
                    Entity entity)

Send a ping to an entity, adding it to pinged if successful.