org.iperg.part.core
Class IpObject

java.lang.Object
  org.iperg.part.core.IpObject

Direct Known Subclasses:

IpProcess

public class IpObject
extends java.lang.Object

The IpObject class is the super class of all PART replicated objects.

PART objects can be replicated which means that several copies of a particular PART object can exist simultaneously in different PART processes. The process of copying a PART object from one process to another is called replication. The new object copy which is created as a result of the replication is called a replica. The first instance of a particular PART object is called the master. Thus, a PART object is represented by a master copy, and zero or more replicas.

PART objects can have properties in addition to ordinary class variables. Properties are represented by a name and a string value. Properties also has a group attribute, which is the name of the group to which the property belongs. All properties with the same group name are thus considered to be part of the same group. If no group name is given when a property is created, it will implicitly be made a member of the default group. The name of the default group is given by IpObject.DEFAULT_PROP_GROUP attribute. The IpObject class provides a number of methods for manipulating properties.

When a PART object is replicated, a copy of the object is sent to another process and used to create a new replica. This includes copying all of the object's properties to the new process. The result is a new replica in which the property values are the same as in the "source" object. The values of the object's class variables are not copied, only its properties.

Properties can only be updated in the master copy. This means that only the process holding the master copy of a PART object is allowed to update its properties. Other processes holding a replica of a PART object can subscribe to updates made to the master. This is done using one of the subscribe methods. Subscriptions cause the platform to automatically synchronise the values of a replica's properties with the corresponding values in the master. By selecting the subscription rate, a process can choose how often it wants this synchronisation to occur.

It is also possible to synchronise two replicas explicitly using one of the synchronise methods. When synchronising the local replica with a remote replica, the values of the properties of the two replicas will be set to the most recent values held by any of the replicas. This means that both replicas can be affected by calls to the synchronise methods.

Version:

1.0.0 Initial version

Author:

Olov Stahl - olovs@sics.se

Field Summary

static java.lang.String	DEFAULT_PROP_GROUP
static int	PROP_ADD
static int	PROP_REMOVE
static int	PROP_SET

Constructor Summary

IpObject()
Create a new object.

IpObject(IpIdentifier id)
Create a new object and set its identifier to the given id.

Method Summary

void	addCommandHandler(IpCommandHandler h) Add a handler that will be invoked to handle commands executed via exec.
void	addProperty(java.lang.String group, java.lang.String name, java.lang.String value) Create and initialize a new object property.
void	addPropertyViaFloat(java.lang.String group, java.lang.String name, float value) Add a new object property and set its value using a float.
void	addPropertyViaInt(java.lang.String group, java.lang.String name, int value) Add a new property to the object and set its value using an integer.
protected void	createProperty(java.lang.String group, java.lang.String name, java.lang.String value) A method that can be used to add properties to an object when the object is created.
static java.lang.String	exec(IpIdentifier procId, IpIdentifier objId, java.lang.String call) Execute a command in an arbitrary PART object in an arbitrary PART process.
java.lang.String	exec(java.lang.String call) Execute a command in the object.
static java.util.Enumeration	getAllObjects() Return an enumeration of IpObject instances representing all replicated objects (masters and replicas alike) held by the local process.
java.util.Enumeration	getAllPropertyGroupNames() Get an enumeration of String instances representing the names of all object property groups.
java.util.Enumeration	getAllPropertyNames(java.lang.String group) Get an enumeration of String objects representing the names of all properties that "belongs to" the given group.
IpIdentifier	getId() Get the unique identifier representing this object
IpIdentifier	getMasterHolderId() Get the identifier of the process that holds the master copy of this replicated object.
long	getMostRecentUpdateTime() Get time (as given by System.currentTimeMillis()) of the most recent update to any of the object's the properties.
long	getMostRecentUpdateTime(java.lang.String group, java.lang.String name) Get time (as given by System.currentTimeMillis()) of the most recent update to the property.
static IpObject	getObject(IpIdentifier id) Get a PART object which has a given id.
static java.lang.String	getProperty(IpIdentifier procId, IpIdentifier objId, java.lang.String group, java.lang.String name, int timeout) Get the property value of an object held by an arbitrary PART process.
java.lang.String	getProperty(java.lang.String group, java.lang.String name) Get the value of an object property in a given group.
float	getPropertyAsFloat(java.lang.String group, java.lang.String name, float valueIfNoSuchProp) Get the value of a property in the given group as a float.
int	getPropertyAsInt(java.lang.String group, java.lang.String name, int valueIfNoSuchProp) Get the value of an property in the given group as an integer.
java.lang.String	getScript() Get the object's scripting URL
int	getSubscriptionInterval(java.lang.String group, java.lang.String name) Get the interval at which the local process subscribes to updates to the property with the given name and group.
protected java.lang.String	handleCommand(java.lang.String cmd, java.lang.String[] params) Should be overridden by sub-classes that wish to handle the invocation of a command.
boolean	isDiscoverable() Check if an object is discoverable or not.
boolean	isMaster() Check if this object instance is the master copy.
protected void	propertyUpdateResolve(int type, java.lang.String group, java.lang.String name, java.lang.String value, IpIdentifier sourceProcId) Is called in the master copy of the object as a result of addProperty, removeProperty or setProperty being called in a the master or a replica.
protected void	read(IpInputStream stream) Read the object's state from an input stream.
void	release() Should be called to tell PART to remove any references to the object, for instance in order for the objnect to become deallocated.
static void	releaseAllObjects() Should be called to tell PART to remove references to all replicated objects.
void	removeProperty(java.lang.String group, java.lang.String name) Remove an object property
void	replicate(IpIdentifier procId) Replicate the object to a remote process identified by the given identifier.
protected void	replicaUpdateCb(IpObjectEvent event) Is called when the object (master or replica) has been updated somehow.
void	setDiscoverable(boolean status) Set the discoverable status of a PART object.
void	setProperty(java.lang.String group, java.lang.String name, java.lang.String value) Set the value of an object property in given group.
void	setPropertyViaFloat(java.lang.String group, java.lang.String name, float value) Set the value of a property in given group using a float value.
void	setPropertyViaInt(java.lang.String group, java.lang.String name, int value) Set the value of a property in given group using an integer value.
void	setScript(java.lang.String scriptUrl) Set the script associated to the object.
void	subscribe(java.lang.String group, java.lang.String name, int interval) Subscribe to updates to a property in the given group.
void	subscribeAll(int interval) Subscribe to all object properties using the same interval.
void	synchronise() Synchronise the values of all object properties with the master object copy.
void	synchronise(IpIdentifier procId) Synchronise the values of the replica with the replica (or master) copy held by a remote process.
void	synchroniseProperty(java.lang.String group, java.lang.String name) Synchronise the value of a property in the given group with the master object copy.
void	synchroniseProperty(java.lang.String group, java.lang.String name, IpIdentifier procId) Synchronise the value of a property in the given group with the replica (or master) copy held by another remote process.
java.lang.String	toString() Return a string representation of the PART object.
void	unsubscribe(java.lang.String group, java.lang.String name) Cancel the subscription of a property in the given group.
void	unsubscribeAll() Will cause all local subscriptions to the object's properties to be cancelled.
protected void	write(IpOutputStream stream) Write the state of the object into an output stream.

Methods inherited from class java.lang.Object

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

Field Detail

PROP_ADD

public static final int PROP_ADD

See Also:

Constant Field Values

PROP_REMOVE

public static final int PROP_REMOVE

See Also:

Constant Field Values

PROP_SET

public static final int PROP_SET

See Also:

Constant Field Values

DEFAULT_PROP_GROUP

public static final java.lang.String DEFAULT_PROP_GROUP

See Also:

Constant Field Values

Constructor Detail

IpObject

public IpObject()

Create a new object.

IpObject

public IpObject(IpIdentifier id)

Create a new object and set its identifier to the given id. This constructor should be used when creating master instances only.

Parameters:

id - The object identifier

Method Detail

getId

public IpIdentifier getId()

Get the unique identifier representing this object

Returns:

The object's unique identifier

getObject

public static IpObject getObject(IpIdentifier id)

Get a PART object which has a given id. This method will always return the object if it exists, even if it hasn't been added to the store.

Parameters:

id - The object identifier

getAllObjects

public static java.util.Enumeration getAllObjects()

Return an enumeration of IpObject instances representing all replicated objects (masters and replicas alike) held by the local process.

Returns:

An enumeration of IpObject instances

getMasterHolderId

public IpIdentifier getMasterHolderId()

Get the identifier of the process that holds the master copy of this replicated object.

Returns:

A process identifier

setDiscoverable

public void setDiscoverable(boolean status)

Set the discoverable status of a PART object. A discoverable object may be found by a remote process via an object search, while an undiscoverable object may not.

By default, objects are undiscoverable when created.

Parameters:

status - true makes the object discoverable, false un-discoverable

isDiscoverable

public boolean isDiscoverable()

Check if an object is discoverable or not.

Returns:

The object's discoverable status, true means that the object is discoverable, false that it's not

isMaster

public boolean isMaster()

Check if this object instance is the master copy.

Returns:

true if object is the master, false otherwise.

replicaUpdateCb

protected void replicaUpdateCb(IpObjectEvent event)

Is called when the object (master or replica) has been updated somehow. The update is described by an update event. Should be overridden by sub-classes that wish to be notified when an object is updated. Is called in both master and replicas.

Parameters:

event - An event that describes the update

release

public void release()

Should be called to tell PART to remove any references to the object, for instance in order for the objnect to become deallocated. As an side-effect, all local subscriptions concerning the object's properties will be terminated.

After calling release, calls to IpObject.getObject using the object's identifier will always return null.

releaseAllObjects

public static void releaseAllObjects()

Should be called to tell PART to remove references to all replicated objects. As an side-effect, all local subscriptions concerning the objects' properties will be terminated.

createProperty

protected final void createProperty(java.lang.String group,
                                    java.lang.String name,
                                    java.lang.String value)

A method that can be used to add properties to an object when the object is created. Doesn't throw any exceptions and causes no events to be generated. A typical use of this method is to add properties to the object as part of instantiation. e.g., from within the constructor.

Parameters:

group - The name of the property group, the default group is assumed if value is null

name - The property name

value - The property value

Throws:

java.lang.IllegalArgumentException - if name and/or value parameters are null

addProperty

public void addProperty(java.lang.String group,
                        java.lang.String name,
                        java.lang.String value)
                 throws IpVetoException

Create and initialize a new object property.

The group is a string that can be used to group properties, i.e., to tell PART that they somehow are related.

Parameters:

group - The property group, the default group is assumed if value is null

name - The property name

value - The property value

Throws:

IpVetoException - if the master object doesn't allow the property to be added, or if an timeout occurs while communicating with the master.

java.lang.IllegalArgumentException - if name and/or value parameters are null

removeProperty

public void removeProperty(java.lang.String group,
                           java.lang.String name)
                    throws IpVetoException,
                           IpNoSuchPropertyException

Remove an object property

Parameters:

group - The property group, the default group is assumed if value is null

name - The property name

Throws:

IpVetoException - if the master copy doesn't permit the property to be removed

IpNoSuchPropertyException - if no such property exists in the current object

addPropertyViaInt

public void addPropertyViaInt(java.lang.String group,
                              java.lang.String name,
                              int value)
                       throws IpVetoException

Add a new property to the object and set its value using an integer.

Parameters:

name - The property name

value - The property value in the form of an integer

group - The name of the property group, the default group is assumed if value is null

Throws:

IpVetoException - if the master object doesn't allow the property to be added, or if an timeout occurs while communicating with the master.

addPropertyViaFloat

public void addPropertyViaFloat(java.lang.String group,
                                java.lang.String name,
                                float value)
                         throws IpVetoException

Add a new object property and set its value using a float.

Parameters:

name - The property name

value - The property value in the form of a float

group - The name of the property group, the default group is assumed if value is null

Throws:

IpVetoException - if the master object doesn't allow the property to be added, or if an timeout occurs while communicating with the master.

getProperty

public java.lang.String getProperty(java.lang.String group,
                                    java.lang.String name)

Get the value of an object property in a given group. If group name is

null

, the

IpObject.DEFAULT_PROP_GROUP

group is assumed.

Parameters:

group - The property group, the default group is assumed if value is null

name - The property name

Returns:

The property value if found, null otherwise

getProperty

public static java.lang.String getProperty(IpIdentifier procId,
                                           IpIdentifier objId,
                                           java.lang.String group,
                                           java.lang.String name,
                                           int timeout)
                                    throws IpNoSuchPropertyException,
                                           IpTimeoutException,
                                           java.io.IOException

Get the property value of an object held by an arbitrary PART process. If the process is not the local process, the property value is fetched from the remote process.

Since the value may be fetched from a remote process, a timeout value has to be supplied. If the value can't be retrieved within the time specified by the timeout parameter, a IpTimeoutException will be thrown. The timeout value is only used if the process identifier parameter identifies a remote process.

Note that the property value will always be fetched from the object copy held by the process identified by the process identifier parameter, even if the local process holds a copy of the object.

Parameters:

procId - The identifier of the process holding the object

objId - The identifier of the object holding the property

group - The property group, the default group is assumed if value is null

name - The property name

timeout - Timeout in milliseconds, 0 means no timeout

Throws:

IpNoSuchPropertyException - If the process, object or property doesn't exist

IpTimeoutException - if a timeout occurs before the property value has been retrieved

java.io.IOException - if an io exception occurs while communicating with the remote process

getPropertyAsInt

public int getPropertyAsInt(java.lang.String group,
                            java.lang.String name,
                            int valueIfNoSuchProp)

Get the value of an property in the given group as an integer. If the group name is

null

, the default property group is assumed.

Parameters:

group - The name of the property group, the default group is assumed if value is null

name - The property name

valueIfNoSuchProp - Value to return if no property of the given name exists.

Returns:

The property value as an integer if found, otherwise the value of the valueIfNoSuchProp parameter.

getPropertyAsFloat

public float getPropertyAsFloat(java.lang.String group,
                                java.lang.String name,
                                float valueIfNoSuchProp)

Get the value of a property in the given group as a float. If the group name is

null

, the default property group is assumed.

Parameters:

group - The name of the property group, the default group is assumed if value is null

name - The property name

valueIfNoSuchProp - to return if no property of the given name exists.

Returns:

The property value as a float if found, otherwise the value of the valueIfNoSuchProp parameter.

propertyUpdateResolve

protected void propertyUpdateResolve(int type,
                                     java.lang.String group,
                                     java.lang.String name,
                                     java.lang.String value,
                                     IpIdentifier sourceProcId)
                              throws IpVetoException

Is called in the master copy of the object as a result of addProperty, removeProperty or setProperty being called in a the master or a replica. Must determine if the update should be allowed. Should be overridden in sub-classes that wish to inspect and possibly veto property updates suggested by replicas.

Parameters:

type - IpObject.PROP_ADD, IpObject.PROP_REMOVE or IpObject.PROP_SET

group - The group to which the property belongs

name - The name of the property that is being updated

value - The suggested new value of the property

sourceProcId - The identifier of the process that is trying to make the update

Throws:

IpVetoException - if the update not allowed

setProperty

public void setProperty(java.lang.String group,
                        java.lang.String name,
                        java.lang.String value)
                 throws IpVetoException,
                        IpNoSuchPropertyException

Set the value of an object property in given group. May block waiting for the master process to accept the update. If property group name is

null

, the

IpObject.DEFAULT_PROP_GROUP

group is assumed.

Parameters:

group - The name of the property group, the default group is assumed if value is null

name - The property name

value - The property value

Throws:

java.lang.IllegalArgumentException - if name and/or value parameters are null

IpVetoException - if the master object doesn't allow the property to be updated, or if an timeout occurs while communicating with the master.

IpNoSuchPropertyException - if the given property doesn't exist

setPropertyViaInt

public void setPropertyViaInt(java.lang.String group,
                              java.lang.String name,
                              int value)
                       throws IpVetoException,
                              IpNoSuchPropertyException

Set the value of a property in given group using an integer value.

Parameters:

group - The property group name, the default group is assumed if value is null

name - The property name

value - The property value in the form of an integer

Throws:

IpVetoException - if the local process doesn't have permission to update the property value

IpNoSuchPropertyException - if the given property doesn't exist

setPropertyViaFloat

public void setPropertyViaFloat(java.lang.String group,
                                java.lang.String name,
                                float value)
                         throws IpVetoException,
                                IpNoSuchPropertyException

Set the value of a property in given group using a float value.

Parameters:

group - The name of the property group, the default group is assumed if value is null

name - The property name

value - The property value in the form of a float

Throws:

IpVetoException - if the local process doesn't have permission to update the property value

IpNoSuchPropertyException - if the given property doesn't exist

getMostRecentUpdateTime

public long getMostRecentUpdateTime()

Get time (as given by System.currentTimeMillis()) of the most recent update to any of the object's the properties.

Returns:

Timestamp (System.currentTimeMillis()) of most recent update to any object property, or -1 if the object doesn't have any properties

getMostRecentUpdateTime

public long getMostRecentUpdateTime(java.lang.String group,
                                    java.lang.String name)
                             throws IpNoSuchPropertyException

Get time (as given by System.currentTimeMillis()) of the most recent update to the property.

Parameters:

group - The property group, the default group is assumed if value is null

name - The property name

Returns:

Timestamp (System.currentTimeMillis()) of most recent property update

Throws:

IpNoSuchPropertyException - if the object has no matching property

getSubscriptionInterval

public int getSubscriptionInterval(java.lang.String group,
                                   java.lang.String name)
                            throws IpNoSuchPropertyException

Get the interval at which the local process subscribes to updates to the property with the given name and group.

If the returned subscription interval is > 0, the value indicates the maximum rate (in milliseconds) at which updates to the property will be reported to the local process. A value of 0 indicates that updates will be reported immediately. A value of -1 is not subscribed by the local process.

Parameters:

group - The property group, the default group is assumed if value is null

name - The property name

Returns:

The subscription interval

Throws:

IpNoSuchPropertyException - if the object has no matching property

subscribe

public void subscribe(java.lang.String group,
                      java.lang.String name,
                      int interval)
               throws IpNoSuchPropertyException

Subscribe to updates to a property in the given group. If group name is

null

, the

IpObject.DEFAULT_PROP_GROUP

group is assumed.

The interval parameter can be used to specify the maximum interval at which the process wants to receive update notifications. For instance, if the value is 1000, updates to the object property will be reported at a maximum rate of once per second, even if the value is updated more often than that.

The subscription method can be called more than once to update the subscription interval. The supplied interval value will replace any interval set in previous calls to subscribe.

Parameters:

group - The name of the property group, the default group is assumed if value is null

name - The name of the property

interval - The maximum interval (in milliseconds) at which the process wants to receive object update notifications. A value of 0 means that the process wants be be notified as soon as the property is updated.

Throws:

IpNoSuchPropertyException - if a property with the given name doesn't exist

subscribeAll

public void subscribeAll(int interval)

Subscribe to all object properties using the same interval. Will override any previous property subscriptions.

Parameters:

interval - The subscription interval

unsubscribe

public void unsubscribe(java.lang.String group,
                        java.lang.String name)
                 throws IpNoSuchPropertyException

Cancel the subscription of a property in the given group. If group name is

null

, the

IpObject.DEFAULT_PROP_GROUP

group is assumed.

Parameters:

group - The name of the property group, the default group is assumed if value is null

name - The name of the property for which the active subscription should be cancelled.

Throws:

IpNoSuchPropertyException - if a property with the given name doesn't exist

unsubscribeAll

public void unsubscribeAll()

Will cause all local subscriptions to the object's properties to be cancelled.

synchronise

public void synchronise()
                 throws java.io.IOException

Synchronise the values of all object properties with the master object copy. Means that the values of all local properties will be set to the value of the corresponding properties in the master.

Will block until the object has been synchronised or until an exception is thrown.

Note that the property values will be synchronised regardless of whether the local process subscribes to all properties or not.

If the local process holds the master copy of the object, the method has no effect.

Throws:

java.io.IOException - if an io exception occurs while synchronising. If exception occurs, property values are not guaranteed to have been synchronised.

synchroniseProperty

public void synchroniseProperty(java.lang.String group,
                                java.lang.String name)
                         throws java.io.IOException,
                                IpNoSuchPropertyException

Synchronise the value of a property in the given group with the master object copy. Means that the value of the property will be set to the value of the corresponding property in the master. If group name is

null

, the

IpObject.DEFAULT_PROP_GROUP

group is assumed.

Will block until the property value has been synchronised or until an exception is thrown.

Note that the property value will be synchronised regardless of whether the local process subscribes to updates to the property or not.

If the local process holds the master copy of the object, the method has no effect.

Parameters:

group - The name of the property group, the default group is assumed if value is null

name - The name of the property to synchronise

Throws:

java.io.IOException - if an io exception occurs while synchronising. If exception occurs, the property value is not guaranteed to have been synchronised.

IpNoSuchPropertyException - if a property with the given name doesn't exist

synchronise

public void synchronise(IpIdentifier procId)
                 throws java.io.IOException,
                        IpNoSuchPropertyException

Synchronise the values of the replica with the replica (or master) copy held by a remote process. Will cause all properties of the local and remote replicas to be set to the most recent values held by any of the two replicas.

If the remote process doesn't hold a replica of the PART object, an IOException will be thrown.

Will block until the object has been synchronised or until an exception is thrown.

Note that the property values will be synchronised regardless of whether the local process subscribes to all properties or not.

If the local process holds the master copy of the object, the method has no effect.

Parameters:

procId - The identifier of the remote process

Throws:

java.io.IOException - if an io exception occurs while synchronising. If exception occurs, property values are not guaranteed to have been synchronised.

IpNoSuchPropertyException - if a property with the given name doesn't exist

synchroniseProperty

public void synchroniseProperty(java.lang.String group,
                                java.lang.String name,
                                IpIdentifier procId)
                         throws java.io.IOException,
                                IpNoSuchPropertyException

Synchronise the value of a property in the given group with the replica (or master) copy held by another remote process. Will cause the property in both replicas to be set to the most recent value held by any of them. If property group name is

null

, the

IpObject.DEFAULT_PROP_GROUP

group is assumed.

If the remote process doesn't hold a replica of the PART object, an IOException will be thrown.

Will block until the property has been synchronised or until an exception is thrown.

Note that the property value will be synchronised regardless of whether the local process subscribes to the property or not.

If the local process holds the master copy of the object, the method has no effect.

Parameters:

group - The name of the property group, the default group is assumed if value is null

name - The name of the property to synchronise

procId - The identifier of the remote process

Throws:

java.io.IOException - if an io exception occurs while synchronising. If exception occurs, property values are not guaranteed to have been synchronised.

IpNoSuchPropertyException - if a property with the given name doesn't exist

getAllPropertyGroupNames

public java.util.Enumeration getAllPropertyGroupNames()

Get an enumeration of String instances representing the names of all object property groups. For instance, the following code will print the names of all property groups:

 Enumeration names = obj.getAllPropertyGroupNames();
 while (names.hasMoreElements()) {
    System.out.println((String)names.nextElement());
 } 

Returns:

An enumeration of group property names. Will not be

null

but will be empty if no properties has been added to the object.

getAllPropertyNames

public java.util.Enumeration getAllPropertyNames(java.lang.String group)

Get an enumeration of String objects representing the names of all properties that "belongs to" the given group. For instance, the following code will print the names of all properties belonging to the group

group1

:

 Enumeration names = obj.getAllPropertyNames("group1");
 while (names.hasMoreElements()) {
    System.out.println((String)names.nextElement());
 } 

Parameters:

group - The property group name. If value is

null

, the

IpObject.DEFAULT_PROP_GROUP

group is assumed.

Returns:

An enumeration of group property names. Will not be

null

but will be empty if the given group doesn't exist.

write

protected void write(IpOutputStream stream)
              throws java.io.IOException

Write the state of the object into an output stream. Object classes that extend IpObject shouldn't have to override the write method since it handles all dynamic properties. However, it is still possible to do so if such classes need to write some additional state information. If write is indeed overridden, the IpObject.write method must be called at the start of the overriding method. A class specific write method must therefore look like this:

 protected void write(IpOutputStream stream)
     throws IOException
 {
     super.write(stream);

     // write class specific state information
     ...
 }

Parameters:

stream - The output stream into which the object's state should be written

Throws:

java.io.IOException - if an io exception occured while writing the object to the stream

read

protected void read(IpInputStream stream)
             throws java.io.IOException

Read the object's state from an input stream. Object classes that extend IpObject shouldn't have to override the read method since it handles all dynamic properties. However, it is still possible to do so if such classes need to read some additional state information. If read is indeed overridden, the IpObject.read method must be called at the start of the overriding method. A class specific read method must therefore look like this:

 protected void read(IpInputStream stream)
     throws IOException
 {
     super.read(stream);

     // read class specific state information
     ...
 }

Parameters:

stream - The input stream from which the object's state should be read

Throws:

java.io.IOException - if the read failed

toString

public java.lang.String toString()

Return a string representation of the PART object. The string syntax is:

"id {group.prop=value, group.prop=value, ...}"

Overrides:

toString in class java.lang.Object

Returns:

A string reresenting the object

replicate

public void replicate(IpIdentifier procId)
               throws java.io.IOException

Replicate the object to a remote process identified by the given identifier. Results in the object being sent over the network and "delivered" to the remote process. If the object doesn't already exist in the remote process it will be created, which will cause an IpObjectEvent of type IpObjectEvent.OBJ_NEW to be triggered. If the object already exist in the remote process, the replication will be aborted, i.e., the remote object replica will not be changed in any way.

Parameters:

procId - The identifier of the remote process

Throws:

java.io.IOException - if an IO exception occurs while replicating the object

addCommandHandler

public void addCommandHandler(IpCommandHandler h)

Add a handler that will be invoked to handle commands executed via exec. Command handlers can only be added on the master copy of an object.

Parameters:

h - The command handler.

setScript

public void setScript(java.lang.String scriptUrl)
               throws IpVetoException

Set the script associated to the object. An object can have only one script, so the call will replace the current script.

A script is given via a "URL" with the syntax lang://script, where lang is the scripting language, e.g., javascript or tcl, and the script is the actual scripting code.

If the script is set successfully, the scripts init method is invoked if defined. The name of the init procedure is defined by IpScriptInterp.SCRIPT_INIT_PROC. Note that the script doesn't have to define this procedure.

Parameters:

scriptUrl - A string in the form lang://script. May not be null.

Throws:

IpVetoException - if the update is refused, e.g., due to the script being syntactically incorrect

getScript

public java.lang.String getScript()

Get the object's scripting URL

exec

public java.lang.String exec(java.lang.String call)
                      throws IpException

Execute a command in the object.

Commands are executed either by command handlers, or by scripts. When a command is executed using exec(call), the command is first handed to the command handlers added via the addCommandHandler method. The script is first handed to the handler that was added first. If this handler does not handle the command, i.e., it returns null, the command is handed to the next handler, and so on. If a handler returns a value which is not null, the "iteration" is stopped and the the value is returned from exec(call). If no command handler handles the command, the object's own handleCommand method is called. If this method doesn't handle the command, PART tries to execute a script method with the same name and parameter as the given by the call parameter. If the script execution returns a value, this value is made the return value of the call to exec(call). If no script exists, or if the script invocation fails, an IpException exception is thrown.

Parameters:

call - A call string which must have the format 'cmd(arg1, ..., argn)'

Returns:

The result of the command execution

Throws:

IpException - if the command execution failed, for instance due to the command being unhandled.

exec

public static java.lang.String exec(IpIdentifier procId,
                                    IpIdentifier objId,
                                    java.lang.String call)
                             throws IpException

Execute a command in an arbitrary PART object in an arbitrary PART process.

Commands are executed either by command handlers, or by scripts. When a command is executed using exec(procId, objId, call), the command is first sent to the (possibly) remote process identified by the procId parameter. When the command has arrived at this process, the object, identified by the objId is located. Once this is done, the call is then handed to the object's command handlers, added via the addCommandHandler method. The script is first handed to the handler that was added first. If this handler does not handle the command, i.e., it returns null, the command is handed to the next handler, and so on. If a handler returns a value which is not null, the "iteration" is stopped and the the value is sent back to the calling process and returned from exec(procId, objId, call). If no command handler handles the command, the object's own handleCommand method is called. If this method doesn't handle the command, PART tries to execute a script method with the same name and parameter as the given by the call parameter. If the script execution returns a value, this value is sent back to the calling process and made the return value of the call to exec(procId, objId, call). If no script exists, or if the script invocation fails, an IpException exception is thrown at the calling process.

If the process to which the call is sent discovers that it's not holding the master copy of the object, the call will be forwarded to the master process. The result of the execution on the master process will then be sent back to the calling process, i.e., the process caliing exec(procId, objId, call).

Parameters:

procId - The identifier of the process where the command should be executed. May be the local or some remote process.

objId - The identifier of the object in which the command will be executed.

call - A call string which must have the format 'cmd(arg1, ..., argn)'

Returns:

The result of the command execution

Throws:

IpException - if the command execution failed, for instance due to the command being unhandled.

handleCommand

protected java.lang.String handleCommand(java.lang.String cmd,
                                         java.lang.String[] params)
                                  throws IpException

Should be overridden by sub-classes that wish to handle the invocation of a command.

Parameters:

cmd - The command name

params - The call parameters

Throws:

IpException - if the execution failed for some reason