livespace.services
Class Livespace

java.lang.Object
  livespace.services.Livespace

public final class Livespace
extends Object

Basic definitions and methods used by Livespace clients.

Author:

Matthew Phillips

Field Summary

static int	ENTITY_RESPONSE_TIMEOUT The default maximum amount of time to wait (in millis) before an entity is considered not to be responding.
static int	PROTOCOL_VERSION The Livespace protocol version in use.

Method Summary

static Scheduler	acquireScheduler() Get a shared scheduler for background tasks.
static String	createUniqueId() Create a unique ID.
static String	elvinToJava(String elvinName) Convert an Elvin-style field name to a Java-style member name.
static String	escapeNtfnField(String field) Escape a string that will be used as a field value in a notification.
static String	escapeNtfnString(String str) Escape a string to be used as a string value in a notification.
static String	fileToUrl(String path) Convert a file path into a "file:" based URL.
static Class<? extends Entity>	findEntityClass(String entityType) Find the class registered to represent instances of a given entity type.
static String	getBuildDate() Returns the time stamp when the Livespace software was built.
static String	getBundlePath() Returns the location where the bundles were obtained from at startup
static String	getCurrentConfigPath() Returns the path where the current configuration files were obtained from.
static String	getDefaultConfigPath() Returns the path where the default configuration files were obtained from.
static String	getDeployConfigs() Returns which deploy configuration were used at startup for the running OSGi client as a comma delimetered list eg.
static String	getElvinUrl() Returns the configured url of the elvin router
static String	getHostCategory() Alias for OsgiUtil.getHostCategory().
static String	getHostName() Alias for OsgiUtil.getHostName().
static String	getIPAddress()
static RoomEntity	getOrCreateLocalRoom(Elvin elvin) Finds the local RoomEntity or creates it if it's not available using the provided Elvin.
static String	getRelease() Returns the Livespace release.
static String	getWorkingDirectory() Returns the directory path to the Livespace client working directory.
static boolean	isFederated(Entity entity) Determines whether the entity is a local entity or a federated entity
static boolean	isFederated(Object object) Determines whether the object is a federated entity.
static String	javaToElvin(String javaName) Convert Java-style member name to an Elvin-style field name.
static Scheduler	peekScheduler() For testing only.
static int	peekSchedulerClients() For testing only.
static void	readValue(Map<?,?> values, String source, IDataObject object, String target) Shortcut to read a value from a Map and copy it into an IDataObject (eg an Entity).
static Map<String,Object>	registeredEntityClasses() Get an (unmodifiable) map from registered types -> class name.
static void	registerEntityClass(Class<? extends Entity> entityClass) Shortcut to register a class for an entity type using Entity.getType(Class) to automatically get the type.
static void	registerEntityClass(String entityType, Class<?> entityClass) Register a given subclass of Entity to be used when entities of a given entity type are instantiated by a client or server.
static void	registerEntityClass(String entityType, String entityClassName) Register a given subclass of Entity to be used when entities of a given entity type are instantiated by a client or server.
protected static void	registerStandardEntityTypes() Register standard, known entity types via registerEntityClass(String, String).
static void	releaseScheduler() Release a shared scheduler allocated by acquireScheduler().
static void	schedule(Scheduler.Task task) Shortcut to schedule a task on the shared scheduler.
static void	schedule(Scheduler.Task task, long delay) Shortcut to schedule a task on the shared scheduler.
static void	unschedule(Scheduler.Task task)

Methods inherited from class java.lang.Object

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

Field Detail

PROTOCOL_VERSION

public static final int PROTOCOL_VERSION

The Livespace protocol version in use. Version 1.0 (1000) was the default up to release 1.1. Version 2.0 (2000) in release 1.2 added the option for GZIP compression for large XML values.

Use the livespace.bus.protocol_version property to change the version at runtime. Use "livespace.bus.compress_xml=true|false" to enable/disable XML compression (compression is automatically disabled if you select the 1.0 protocol.

ENTITY_RESPONSE_TIMEOUT

public static final int ENTITY_RESPONSE_TIMEOUT

The default maximum amount of time to wait (in millis) before an entity is considered not to be responding.

See Also:

EntityClient.setLivenessTimeouts(long, long, long), Constant Field Values

Method Detail

registerStandardEntityTypes

protected static void registerStandardEntityTypes()

Register standard, known entity types via registerEntityClass(String, String). May be called more than once.

registerEntityClass

public static void registerEntityClass(Class<? extends Entity> entityClass)

Shortcut to register a class for an entity type using Entity.getType(Class) to automatically get the type.

Parameters:

entityClass - A subclass of Entity.

See Also:

registerEntityClass(String, Class)

registerEntityClass

public static void registerEntityClass(String entityType,
                                       Class<?> entityClass)

Register a given subclass of Entity to be used when entities of a given entity type are instantiated by a client or server. If no class is registered for an entity, then GenericEntity is used.

Parameters:

entityType - The entity type (see Entity.getType().

entityClass - The class of entity. Must be a subclass of Entity.

See Also:

registerEntityClass(String, String), findEntityClass(String)

registerEntityClass

public static void registerEntityClass(String entityType,
                                       String entityClassName)

Register a given subclass of Entity to be used when entities of a given entity type are instantiated by a client or server. This version allows the class to be mapped by name, allowing lazy loading of the actual class file. If no class is registered for an entity, then GenericEntity is used.

Parameters:

entityType - The entity type (see Entity.getType().

entityClassName - The name of the entity class of entity. Must be a subclass of Entity.

See Also:

registerEntityClass(String, Class), findEntityClass(String)

registeredEntityClasses

public static Map<String,Object> registeredEntityClasses()

Get an (unmodifiable) map from registered types -> class name.

findEntityClass

public static Class<? extends Entity> findEntityClass(String entityType)

Find the class registered to represent instances of a given entity type. If none is registered, GenericEntity is used.

See Also:

registerEntityClass(String, Class)

acquireScheduler

public static Scheduler acquireScheduler()

Get a shared scheduler for background tasks. This is a non-daemon thread, so clients must release it when done using releaseScheduler() or the VM will not exit properly.

releaseScheduler

public static void releaseScheduler()

Release a shared scheduler allocated by acquireScheduler().

schedule

public static void schedule(Scheduler.Task task)

Shortcut to schedule a task on the shared scheduler.

See Also:

acquireScheduler()

schedule

public static void schedule(Scheduler.Task task,
                            long delay)

Shortcut to schedule a task on the shared scheduler.

See Also:

acquireScheduler()

unschedule

public static void unschedule(Scheduler.Task task)

peekScheduler

public static Scheduler peekScheduler()

For testing only.

peekSchedulerClients

public static int peekSchedulerClients()

For testing only.

createUniqueId

public static String createUniqueId()

Create a unique ID.

escapeNtfnString

public static String escapeNtfnString(String str)

Escape a string to be used as a string value in a notification.

escapeNtfnField

public static String escapeNtfnField(String field)

Escape a string that will be used as a field value in a notification.

readValue

public static void readValue(Map<?,?> values,
                             String source,
                             IDataObject object,
                             String target)

Shortcut to read a value from a Map and copy it into an IDataObject (eg an Entity). Does nothing if the value does not exist in the map.

Parameters:

values - The Map of values to read from.

source - The name of the source property in the map.

object - The target object.

target - The name of the target property in this entity.

See Also:

readValue(Map, String, IDataObject, String)

elvinToJava

public static String elvinToJava(String elvinName)

Convert an Elvin-style field name to a Java-style member name. Eg "Entity-Name" becomes "entityName".

See Also:

javaToElvin(String)

javaToElvin

public static String javaToElvin(String javaName)

Convert Java-style member name to an Elvin-style field name. Eg "name" becomes "Name". "entityName" becomes "Entity-Name", "fieldID" becomes "Field-ID". If the Java name contains '-' chars, which would be ambiguous when translated back, then the name is wrapped in [ and ] and not otherwise transformed.

See Also:

elvinToJava(String)

fileToUrl

public static String fileToUrl(String path)

Convert a file path into a "file:" based URL. Does nothing if the path already seems to be a URL.

getHostName

public static String getHostName()
                          throws IOException

Alias for OsgiUtil.getHostName().

Throws:

IOException

getIPAddress

public static String getIPAddress()
                           throws IOException

Throws:

IOException

getHostCategory

public static String getHostCategory()

Alias for OsgiUtil.getHostCategory().

getRelease

public static String getRelease()

Returns the Livespace release.

getBuildDate

public static String getBuildDate()

Returns the time stamp when the Livespace software was built.

getDeployConfigs

public static String getDeployConfigs()

Returns which deploy configuration were used at startup for the running OSGi client as a comma delimetered list eg. server, client

getBundlePath

public static String getBundlePath()

Returns the location where the bundles were obtained from at startup

getElvinUrl

public static String getElvinUrl()

Returns the configured url of the elvin router

getCurrentConfigPath

public static String getCurrentConfigPath()

Returns the path where the current configuration files were obtained from.

getDefaultConfigPath

public static String getDefaultConfigPath()

Returns the path where the default configuration files were obtained from.

getWorkingDirectory

public static String getWorkingDirectory()
                                  throws InvalidParameterException

Returns the directory path to the Livespace client working directory.

Returns:

Returns the directory path to the Livespace client working directory.

Throws:

InvalidParameterException - if the System property livespace.osgi.work_dir is not set.

getOrCreateLocalRoom

public static RoomEntity getOrCreateLocalRoom(Elvin elvin)
                                       throws IOException

Finds the local RoomEntity or creates it if it's not available using the provided Elvin.

Parameters:

elvin - The Elvin hosting the RoomEntity

Returns:

The RoomEntity running on the provided Elvin.

Throws:

IOException - If an IO error occurs while contacting Elvin.

isFederated

public static boolean isFederated(Entity entity)

Determines whether the entity is a local entity or a federated entity

Parameters:

entity - The entity to test.

Returns:

Returns true if the entity is a federated entity

isFederated

public static boolean isFederated(Object object)

Determines whether the object is a federated entity. Note if the object is not type entity this method will return false.

Parameters:

object - The object value to test.

Returns:

Returns true if the entity is a federated entity