livespace.services
Class Persistence

java.lang.Object
  livespace.services.Persistence

public final class Persistence
extends Object

Livespace persistent storage services. Allows services to access settings and other data in the form of persistent data beans.

TODO use file locking to stop concurrent access.

Author:

Matthew Phillips

Method Summary

static void	closeObject(IDataBean bean) Close a persistent object previously returned by openObject(RoomEntity, String).
static String	getDataFile(RoomEntity room, String path) Create a path for a general data file stored in the persistent storage area.
static IDataBean	openObject(RoomEntity room, String path) Open/create a persistent object identified by a given logical path.
static IDataBean	openObjectHostScope(RoomEntity room, String path) Open/create a persistent object identified by a given logical path.
static IDataBean	readObject(String persistenceFile) Read a saved persistent object from a DBXML file.

Methods inherited from class java.lang.Object

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

Method Detail

openObject

public static IDataBean openObject(RoomEntity room,
                                   String path)
                            throws ClassNotFoundException,
                                   IOException,
                                   IllegalArgumentException

Open/create a persistent object identified by a given logical path. The objects created by this service are automatically persistent across sessions. Multiple calls during one session with the same room and path will result in the same object instance being returned.

The objects managed via this call are room-wide, i.e. the same object will be opened regardless of which host the service runs on. For services that need to run on multiple hosts concurrently, use openObjectHostScope(RoomEntity, String)instead.

Clients should closeObject(IDataBean)when they're finished with the object.

Parameters:

room - The room. The base URI for data storage is taken from here.

path - The logical path for the persistent object. This usually has some obvious relationship to the service type and may contain any number of "subdirectories" if the service wants to have more than one persistent object. Examples include: "lights/entities", "volume/mixer1", "volume/stateCache".

Returns:

A data bean whose contents will be persistent across sessions.

Throws:

IllegalArgumentException - if an error is found in the structure of an existing serialized object instance.

ClassNotFoundException - If a class referenced by the persistent object cannot be found.

IOException - If a generic IO error occurs during reading the persistent object.

See Also:

openObjectHostScope(RoomEntity, String)

readObject

public static IDataBean readObject(String persistenceFile)
                            throws ClassNotFoundException,
                                   IOException,
                                   IllegalArgumentException

Read a saved persistent object from a DBXML file. This is intended for clients outside of the Livespace managed environment. Livespace hosted client will generally use openObject(RoomEntity, String) rather than this method.

Parameters:

persistenceFile - The name of the file to open.

Returns:

The decoded object.

Throws:

ClassNotFoundException

IOException

IllegalArgumentException

See Also:

openObject(RoomEntity, String)

openObjectHostScope

public static IDataBean openObjectHostScope(RoomEntity room,
                                            String path)
                                     throws ClassNotFoundException,
                                            IOException,
                                            IllegalArgumentException

Open/create a persistent object identified by a given logical path. The objects created by this service are automatically persistent across sessions. Multiple calls during one session with the same room and path will result in the same object instance being returned.

The objects managed via this call are host-local, i.e. a separate objects will be opened on different hosts. This allows the same service to run on multiple hosts concurrently with per-host persistent state.

Clients should closeObject(IDataBean)when they're finished with the object.

Parameters:

room - The room. The base URI for data storage is taken from here.

path - The logical path for the persistent object. This usually has some obvious relationship to the service type and may contain any number of "subdirectories" if the service wants to have more than one persistent object. Examples include: "lights/entities", "volume/mixer1", "volume/stateCache".

Returns:

A data bean whose contents will be persistent across sessions.

Throws:

IllegalArgumentException - if an error is found in the structure of an existing serialized object instance.

ClassNotFoundException - If a class referenced by the persistent object cannot be found.

IOException - If a generic IO error occurs during reading the persistent object.

UnknownHostException - if the host's name could not be determined.

See Also:

openObject(RoomEntity, String), Localhost

closeObject

public static void closeObject(IDataBean bean)

Close a persistent object previously returned by openObject(RoomEntity, String).

Parameters:

bean - The persistent object.

getDataFile

public static String getDataFile(RoomEntity room,
                                 String path)

Create a path for a general data file stored in the persistent storage area. e.g. getDataFile ("messages.db").

Parameters:

room - The local room. The base URI for data storage is taken from here.

path - The final part of the path for the file.

Returns:

A path for the required data file.