objectivehtml.oms
Class OMSObject

java.lang.Object
  |
  +--objectivehtml.oms.OMSObject

Direct Known Subclasses:

HtmlElement, HtmlRadioButtonGroup

public abstract class OMSObject

extends java.lang.Object

This abstract class is the base class of all objects that are capable of participating in the Objective Html Messaging System (OMS).

There are 2 major components to OMS, the signal and the slot. A signal is emitted by objects that wish to inform other objects (the slots) of an interesting event. The signal can carry additional information in the form of object parameters, the slot can also receives these object parameters. A signal can be connected to many slots and a slot can be connected to many signals.

A signal is simply a Java instance method. Once a signal is emitted all slots that are connected to it will receive the signal regardless of whether the other slots successfully process the signal. The connected slot methods will receive the signal in the same order they were connected to the signal method. The only syntatical requirement of a signal method is that it public and returns a Signal object. However the signal will not work unless the signal method is correctly implemented.

A slot is simply a Java instance method. When a signal is received by a listening slot object, the slot method will execute. Generally its desirable for a slot method not to throw any exceptions and have itself handle any exceptions that it might encounter. If you wish a slot method to throw an exception, then you can provide an ErrorHandler object. A ErrorHandler object is simply a class that implements the ErrorHandler interface. If this is provided then the handleError(SlotId, Signal, Throwable) will be called when an exception is thrown by the slot method. If no error handler object is provided then any exceptions thrown by the slots simple have their stack-traces printed to the standard out. Any public method can be a slot. Even a signal method can act as a slot.

A signal and a slot signature's must match for them to be connected. i.e. The parameter types of the signal must match the slot and in the correct order too. A slot can accept less parameters that the signal can give, in this case the extra parameters are lost. The opposite is not true however, a slot method cannot have more arguments that a signal method it is connecting to.

See Also:

SignalId, SlotId, Signal, ErrorHandler

Constructor Summary

OMSObject()
Constructs an instance of OMSObject.

Method Summary

protected static boolean	compareClasses(java.lang.Class objSubClass, java.lang.Class objSuperClass) This method compares two classes.
static void	connect(SlotId objSlotId, SignalId objSignalId) This is used to connect a slot to a signal.
static void	disconnect(SlotId objSlotId, SignalId objSignalId) This is used to disconnect a slot to a signal.
static void	emit(Signal objSignal) Emits the signal to all the connected slots.
boolean	isAlive() Returns whether the object is alive or not.
protected void	setAlive(boolean bAlive) Sets the object to be alive or dead.
SignalId	signal(java.lang.String sSignalSignature) Returns the signal for the given signal signature.
SlotId	slot(java.lang.String sSlotSignature) Returns the slot for the given slot signature.
SlotId	slot(java.lang.String sSlotSignature, ErrorHandler objErrorHandler) Returns the slot for the given slot signature.

Methods inherited from class java.lang.Object

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

Constructor Detail

OMSObject

public OMSObject()

Constructs an instance of OMSObject.

Method Detail

disconnect

public static void disconnect(SlotId objSlotId,
                              SignalId objSignalId)

This is used to disconnect a slot to a signal.

Parameters:

objSlotId - the slot id

objSignalId - the signal id

connect

public static void connect(SlotId objSlotId,
                           SignalId objSignalId)
                    throws InvalidSlotException

This is used to connect a slot to a signal. A slot can only be connected once to a signal. Once a slot is connected to a signal, calling this method again with the same slot and signal will have no effect.

Parameters:

objSlotId - the slot id

objSignalId - the signal id

Throws:

InvalidSlotException - if the slot does not match the signal

emit

public static void emit(Signal objSignal)

Emits the signal to all the connected slots. The connected slot methods will be called in the same order they were connected to the signal (i.e. the first connected slot will be executed first, the second connected slot is next, and so on). The parameter values given by the Signal method are passed to each slot method. If the slot method has less arguments than the signal method then the extra arguments are lost. If the slot method throws an exception and has an ErrorHandler object set for it then the handleError method will be called. If no ErrorHandler object is for the slot then the exception will have its stack-trace printed to standard out and the exception is simply eaten up.

If the slot method is also a signal method, then this signal is then emitted.

Parameters:

objSignal - the signal to emit

slot

public SlotId slot(java.lang.String sSlotSignature,
                   ErrorHandler objErrorHandler)
            throws InvalidSlotException

Returns the slot for the given slot signature. The error handler object objErrorHandler is added to the slot.

A method signature has the following pattern (this applies to slots and signals):

method-name(argtype1, argtype2, ...)

Some points:

1. There should be no spaces between the opening parenthesis and the method name
2. For primitive types simply use there natural names, i.e. byte, short, int, long, float, double, char, boolean
3. For all classes of the java.lang package you can omit the package name from argument type. e.g. String
4. For all classes that are not in the java.lang package you must specify the full class name including the package name
5. All argument types must be separated by a comma
6. There must be a closing parenthesis
7. If the method has no arguments then you still need an opening and closing parenthesis

Parameters:

sSlotSignature - the slot signature

objErrorHandler - the error handler for the slot

Returns:

the slot id

Throws:

InvalidSlotException - if the slot cannot be found

See Also:

slot(String)

slot

public SlotId slot(java.lang.String sSlotSignature)
            throws InvalidSlotException

Returns the slot for the given slot signature. There is no error handler for this slot. See the slot(String, ErrorHandler) method on how the method signature pattern should be.

Parameters:

sSlotSignature - the slot signature

Returns:

the slot id

Throws:

InvalidSlotException - if the slot cannot be found

See Also:

slot(String, ErrorHandler)

signal

public SignalId signal(java.lang.String sSignalSignature)
                throws InvalidSignalException

Returns the signal for the given signal signature. See the slot(String, ErrorHandler) method on how the method signature pattern should be.

Parameters:

sSignalSignature - the signal signature

Returns:

the signal id

Throws:

InvalidSignalException - if the signal cannot be found

See Also:

slot(String, ErrorHandler)

compareClasses

protected static boolean compareClasses(java.lang.Class objSubClass,
                                        java.lang.Class objSuperClass)

This method compares two classes. Returns true if the classes are the same, false otherwise.

Parameters:

objSubClass - the sub-class

objSuperClass - the super-class

Returns:

true if the classes are the same, false otherwise

setAlive

protected void setAlive(boolean bAlive)

Sets the object to be alive or dead. A object that is not alive cannot receive signals or send signals.

Parameters:

bAlive - true if active, false otherwise

See Also:

isAlive()

isAlive

public boolean isAlive()

Returns whether the object is alive or not.

Returns:

true if the object is alive, false otherwise

See Also:

setAlive(boolean)