livespace.services
Class Entity

java.lang.Object
  dsto.dfc.databeans.AbstractDataObject
      dsto.dfc.databeans.SimpleDataObject
          dsto.dfc.databeans.FancyDataObject
              livespace.services.Entity

All Implemented Interfaces:

IDataObject, IDataObjectChildListener, Cloneable

Direct Known Subclasses:

Amplifier, AudioMixerEntity, CallEntity, CameraEntity, ClipboardEntity, ComputerEntity, DirectoryEntryEntity, DisplayEntity, DocumentEntity, DocumentLibraryEntity, EntityList.ListEntity, EventCategory, GenericEntity, InfoRepositoryEntity, LightEntity, Link, LogEntry, MediaView, MetaApp, MetaAppElement, MetaAppElementGroup, MetaApps, PictureEntity, PictureProgramLayoutEntity, PictureProgramWindowEntity, PositionableDevice, PresenceEntity, QueryEntity, RoomEntity, RoomPresentation, RoomSchematicEntity, SchematicItem, ScreenConnection, ScreenSharing, SessionEntity, Sessions, SpeakerEntity, Teamscope, TeamscopeProject, TeamscopeSession, TeamthinkEntity, Trash, VideoInputEntity, VideoOutputEntity, VideoSourceEntity, VirtualMonitorEntity, VTCEntity

public abstract class Entity
extends FancyDataObject

Base class for Livespace service entities. An entity is simply a data bean (IDataBean) with a two guaranteed fields: a unique ID and a human-readable name (where possible).

Entities may be published and replicated using the Livespace container classes EntityClient and EntityServer.

Entities must have a default constructor, although this may be non-public.

Entities have a logical type, which is simply a string accessed via getType() e.g. "computer", "light", "person". Although specialised subclasses of Entity are often used for representing difference types as a convenience (e.g. ComputerEntity) the only thing that matters on the Livespace bus is the entity type. When an entity is instantiated locally from a remote copy, the framework checks to see if a mapping from entity type to a Java class exists using Livespace.findEntityClass(String) and uses that class for the local entity instance if it exists. If not, then a GenericEntity is used. Clients that care if a particular Java class will be used for a given type must therefore make sure that it is registered using Livespace.registerEntityClass(String, Class).

Author:

Matthew Phillips

To do:

add missing primitive versions of waitForProperty ()

Field Summary

EntityContainer	container The client or server container this entity is managed by.
String	id The unique ID for the entity.
protected long	lastTouched Last time the entity got an update from the server (used by client container only).
String	name The human-readable name of the entity for presentation purposes.
protected int	unconfirmedUpdates The number of updates for which we haven't seen a response from the server yet (used by client container only).

Fields inherited from class dsto.dfc.databeans.AbstractDataObject

listeners

Fields inherited from interface dsto.dfc.databeans.IDataObject

OVERRIDE, PERSISTENT, PERSISTENT_OVERRIDE, TRANSIENT, TRANSIENT_OVERRIDE

Constructor Summary

Entity()
Create a default instance with an automatic ID and name.

Entity(String id)
Create a new instance.

Entity(String id, String name)
Create a new instance.

Method Summary

protected static Entity	create(String id, String entityType) Create an instance of an Entity using the registered type class if available.
protected static String	createId() Shortcut to create a unique ID.
Elvin	getElvin() Shortcut to get the Elvin connection from the current container.
abstract String	getType() The type of the object (eg "room", "light", "volume", etc).
static String	getType(Class<? extends Entity> entityClass) Shortcut to extract the type of an Entity class.
TypeInfo	getTypeInfo() Get meta data type info for the entity (if any).
Object	mutex() Get the mutual exclusion lock for this entity.
static boolean	sameEntity(Entity e1, Entity e2) Test if two entities are the same by ID comparison.
IDataObject	shallowClone() Clone the entity.
void	waitForProperty(String property, boolean value) Wait for a property value to be changed from the client container's thread.
void	waitForProperty(String property, int value) Wait for a property value to be changed from the client container's thread.
Object	waitForProperty(String property, Object value) Wait for a property value to be changed from the client container's thread.
Object	waitForProperty(String property, Object value, long maxWait) Wait for a property value to be changed from the client container's thread.

Methods inherited from class dsto.dfc.databeans.FancyDataObject

childPropertyChanged, getValue, isTransient, propertyIterator, setValue

Methods inherited from class dsto.dfc.databeans.SimpleDataObject

getFieldNames, setValue

Methods inherited from class dsto.dfc.databeans.AbstractDataObject

addFirstPropertyListener, addPropertyListener, firePropertyChangedEvent, firePropertyChangedEvent, firePropertyChangedEvent, firePropertyChangedEvent, firePropertyChangedEvent, firePropertyChangedEvent, getBeanValue, getBooleanValue, getBooleanValue, getCharValue, getCharValue, getDoubleValue, getDoubleValue, getFloatValue, getFloatValue, getIntValue, getIntValue, getLongValue, getLongValue, getObjectValue, getPropertyListeners, getShortValue, getStringValue, registerValue, removePropertyListener, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, toString, unregisterValue

Methods inherited from class java.lang.Object

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

Field Detail

id

public String id

The unique ID for the entity. This must not change once the object has been added to a registry.

name

public String name

The human-readable name of the entity for presentation purposes. This should try to be unique within the class of entity, but doesn't need to be. If no sensible name exists, this should be the same as the ID. This field may be changed at any time.

container

public transient EntityContainer container

The client or server container this entity is managed by. May be null if not in a container.

unconfirmedUpdates

protected transient int unconfirmedUpdates

The number of updates for which we haven't seen a response from the server yet (used by client container only).

lastTouched

protected transient long lastTouched

Last time the entity got an update from the server (used by client container only).

Constructor Detail

Entity

public Entity()

Create a default instance with an automatic ID and name.

Entity

public Entity(String id)

Create a new instance.

Parameters:

id - The entity ID (will be used as default name also).

Entity

public Entity(String id,
              String name)

Create a new instance.

Parameters:

id - The entity ID.

name - The entity name.

Method Detail

shallowClone

public IDataObject shallowClone()

Clone the entity. NOTE: the cloned entity will have the same ID as the original. This is intentional since the clone contract requries a functionally identical copy, but users should be careful to assign a new ID (Livespace.createUniqueId()) if the original entity will continue to be used.

Specified by:

shallowClone in interface IDataObject

Overrides:

shallowClone in class FancyDataObject

Returns:

A new object of the same type, with the same values as the original.

See Also:

DataObjects.deepClone(IDataObject)

getTypeInfo

public TypeInfo getTypeInfo()

Get meta data type info for the entity (if any). This simply calls TypeRegistry.peekTypeInfo(String) with the entity's type (getType ()) as the argument.

To register meta type info for an entity, use TypeRegistry.register(String, TypeInfo).

Specified by:

getTypeInfo in interface IDataObject

Overrides:

getTypeInfo in class SimpleDataObject

Returns:

The type info, or null if none defined.

See Also:

TypeRegistry

getType

public abstract String getType()

The type of the object (eg "room", "light", "volume", etc). This must be unique to the entity class.

NOTE: it is also a good practice to provide a static field that defines the entity type on the class: eg

 public static final String ENTITY_TYPE = "room";
 

getElvin

public Elvin getElvin()
               throws IllegalStateException

Shortcut to get the Elvin connection from the current container.

Returns:

The Elvin connection.

Throws:

IllegalStateException - if there is no container for the entity.

waitForProperty

public void waitForProperty(String property,
                            boolean value)
                     throws SynchronizationException

Wait for a property value to be changed from the client container's thread.

Parameters:

property - The property name,

value - The required value.

Throws:

SynchronizationException - if the value hasn't changed in the default time.

See Also:

Livespace.ENTITY_RESPONSE_TIMEOUT

waitForProperty

public void waitForProperty(String property,
                            int value)
                     throws SynchronizationException

Wait for a property value to be changed from the client container's thread.

Parameters:

property - The property name,

value - The required value.

Throws:

SynchronizationException - if the value hasn't changed in the default time.

See Also:

Livespace.ENTITY_RESPONSE_TIMEOUT

waitForProperty

public Object waitForProperty(String property,
                              Object value)
                       throws SynchronizationException

Wait for a property value to be changed from the client container's thread.

Parameters:

property - The property name,

value - The required value.

Returns:

The new property value.

Throws:

SynchronizationException - if the value hasn't changed in the default time.

See Also:

Livespace.ENTITY_RESPONSE_TIMEOUT

waitForProperty

public Object waitForProperty(String property,
                              Object value,
                              long maxWait)
                       throws SynchronizationException

Wait for a property value to be changed from the client container's thread.

Parameters:

property - The property name,

value - The required value.

maxWait - The maximum time (in millis) to wait.

Returns:

The new property value.

Throws:

SynchronizationException - if the value hasn't changed in the default time.

getType

public static String getType(Class<? extends Entity> entityClass)

Shortcut to extract the type of an Entity class.

Parameters:

entityClass - An Entity-derived class.

Returns:

The result of getType().

sameEntity

public static boolean sameEntity(Entity e1,
                                 Entity e2)

Test if two entities are the same by ID comparison.

mutex

public Object mutex()

Get the mutual exclusion lock for this entity. If the entity is currently shared in a container, this is the root entity registry. If not shared, this is the entity itself.

create

protected static Entity create(String id,
                               String entityType)
                        throws IllegalArgumentException

Create an instance of an Entity using the registered type class if available.

Parameters:

id - The ID for the entity.

entityType - The entity type.

Returns:

A new instance.

Throws:

IllegalArgumentException - if the entity could not be instantiated or ID is null.

See Also:

Livespace.findEntityClass(String), EntityContainer.createEntity(String, String)

createId

protected static String createId()

Shortcut to create a unique ID. Delegates to Livespace.createUniqueId().