things.thing
Class THING

java.lang.Object
  extended by things.thing.BASE
      extended by things.thing.THING
All Implemented Interfaces:
BASEInterface, THINGInterface

public abstract class THING
extends BASE
implements THINGInterface

A thing.

 The life cycle of a thing (with default behavior:
 definition -> instance(check parms) -> call ->  -> RESULTS -> return
                                             -> ERROR           -> trap    -> RESULTS -> return
                                             -> FAULT           -> trap    -> RESULTS -> propagate          
 

NOTES:
Logging is currently done with a system logger. May want to change that.
Ultimately, RESULT should be reported as Level.DATA. Only the root THING will do so automatically, rolling up the registered results of any calls, depending on how the THINGS were implements.. A simple INFO logging of each completed THING will be done. Naturally, any THING can explicitly report results at any time.

Version:
1.0

Version History

EPG - Initial - 26 FEB 07
 
Author:
Erich P. Gatejen

Field Summary
 
Fields inherited from class things.thing.BASE
localProperties, localSystemLogger, mySystemInterface
 
Constructor Summary
THING()
           
 
Method Summary
 void ACCEPT_HALT()
          Accept a halt.
 void ACCEPT_PAUSE()
          Accept a pause.
 RESULT CALCULATE_RESULT()
          Calculate the result based on the defined results and their settings.
 RESULT call_chain()
          This is the class call point.
 RESULT CALL(java.lang.String thingName)
          Call a THING.
 void CATCH_ERROR(ThingsException te)
          Default ERROR trap.
 void CATCH_FAULT(ThingsException te)
          Default FAULT trap.
 void CHECK_REQUIRED()
          Make sure all required properties exist.
 void DEFINE_RESULT(java.lang.String name, java.lang.String description, ResultExpectation expectation)
          Define a result.
abstract  void DEFINITION()
          Definition step.
 void EXPRESS(RESULT theResult)
          Express a result.
 RESULT getInterimResult()
          Get the interim result, if available.
 ExpressionInterface getParentExpressionInterface()
          Get a reference tot he parent expression interface.
 RESULT getResult()
          Get the final result, if available.
 void init(SystemInterface si, ControlInterface ci, ExpressionInterface ei, ExpressionInterface parent)
          Initialize this THING.
 MODULE INSTANCE(java.lang.String moduleName)
          Instantiate a module.
 MODULE MODULE(java.lang.String moduleName)
          Get a module.
 void PAUSING()
          The THING is about to pause.
abstract  void PROCESS()
          The process can only be called once per instance!
 void REQUIRE_PROPERTY(java.lang.String name)
          Require a property.
 RESULT RESULTS(RESULT defaultReport)
          Optional result step.
 long RUN_TIME()
          Get how long the thing has been running in milliseconds.
 RESULT RUN(java.lang.String thingName)
          Run a THING.
 void SET_EXPRESSOR(java.lang.String destination)
          Set an expressor.
 void SET_RESULT(java.lang.String name, Data.Type resultType)
          Set result based on a result type only.
 void SET_RESULT(java.lang.String name, RESULT result)
          Set result based on a complete RESULT.
 void UNPAUSING()
          The THING is about to unpause.
 
Methods inherited from class things.thing.BASE
CONFIG_PROPERTY_TOOLKIT, GET_LOGGER, GET_NAME, GET_UNIVERSE_ACCESSOR, GET_UNIVERSE, PROPERTY_READER_TOOLKIT, systemInit
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface things.thing.THINGInterface
GET_UNIVERSE
 
Methods inherited from interface things.thing.BASEInterface
GET_LOGGER
 

Constructor Detail

THING

public THING()
Method Detail

DEFINITION

public abstract void DEFINITION()
                         throws UserException
Definition step.

Throws:
UserException

PROCESS

public abstract void PROCESS()
                      throws java.lang.Throwable
The process can only be called once per instance!

Throws:
any - Throwable. It's important to let InterruptedException's to escape or the system may pound your THING with interruptions.
java.lang.Throwable

RESULTS

public RESULT RESULTS(RESULT defaultReport)
               throws ThingsException
Optional result step. The default will report results based on defined tests. Overload it if you want to manipulate the results. If you return null, it will use the system defined results. The default will return null;

Parameters:
defaultReport - the result the system calculated based on defined tests.
Returns:
the actual result you want to report.
Throws:
ThingException
ThingsException

CATCH_FAULT

public void CATCH_FAULT(ThingsException te)
                 throws UserException
Default FAULT trap. It will just propagate it as a UserException FAULT.

Parameters:
te - the offending exception
Throws:
UserException

CATCH_ERROR

public void CATCH_ERROR(ThingsException te)
                 throws UserException
Default ERROR trap. It won't do anything with it.

Parameters:
te - the offending exception
Throws:
UserException

PAUSING

public void PAUSING()
             throws UserException
The THING is about to pause. This gives it a chance to prepare. Do not linger here!

Throws:
UserException

UNPAUSING

public void UNPAUSING()
               throws UserException
The THING is about to unpause. This gives it a chance to prepare. Do not linger here!

Throws:
UserException

INSTANCE

public MODULE INSTANCE(java.lang.String moduleName)
                throws UserException,
                       java.lang.InterruptedException
Instantiate a module. It will seek and create the one as named and init it. You'll have to cast it to the specific class if you want to access subclass methods.

Specified by:
INSTANCE in interface THINGInterface
Parameters:
moduleName - the name of the module. This must match the class name for the MODULE or it will not be found and run.
Returns:
the MODULE
Throws:
UserException - or InterruptedException. It's important to let InterruptedException out.
java.lang.InterruptedException

CALL

public RESULT CALL(java.lang.String thingName)
            throws UserException,
                   java.lang.InterruptedException
Call a THING. A new instance of it will be created.

Specified by:
CALL in interface THINGInterface
Parameters:
thingName - the name of the thing. This must match the class name for the THING or it will not be found and run.
Returns:
the RESULT of the call.
Throws:
UserException - or InterruptedException. It's important to let InterruptedException out.
java.lang.InterruptedException

RUN

public RESULT RUN(java.lang.String thingName)
           throws UserException,
                  java.lang.InterruptedException
Run a THING. A new instance of it will be created. It will be run in a separate process, but it will inherit a common expression interface.

Parameters:
thingName - the name of the thing. This must match the class name for the THING or it will not be found and run.
Returns:
the RESULT of the call. The result will have the attribute ATTR_THING_PROCESS_ID identifying the kernal process id of the running thing.
Throws:
UserException - or InterruptedException. It's important to let InterruptedException out.
java.lang.InterruptedException

EXPRESS

public void EXPRESS(RESULT theResult)
             throws UserException
Express a result. It is up to the environment as to where it will be expressed, be it to the local log or across the wire. It is up to the kernel to make this reliable and there will be no receipt for it. If you absolutely must be certain that your receipt made it somewhere, use a channel.

Specified by:
EXPRESS in interface THINGInterface
Throws:
UserException

SET_EXPRESSOR

public void SET_EXPRESSOR(java.lang.String destination)
                   throws UserException
Set an expressor. This will become the parent expression interface and all child THINGS will use it (unless they call SET_EXPRESSOR too).

Parameters:
destination - the destination for the expressions. This is up to the implementation. It might be a universe address or a channel.
Throws:
UserException

MODULE

public MODULE MODULE(java.lang.String moduleName)
              throws UserException,
                     java.lang.InterruptedException
Get a module. Each call will yield a unique instance. It will be initialized in the same context as the THING.

Parameters:
moduleName - the name of the module. This must match the class name for the MODULE or it will not be found and run.
Returns:
the MODULE itself.
Throws:
UserException - or InterruptedException. It's important to let InterruptedException out.
java.lang.InterruptedException

RUN_TIME

public long RUN_TIME()
              throws UserException
Get how long the thing has been running in milliseconds. This is not how much processing time has accumulated, but from the moment it started running until it stopped, pauses and whatever included.

Specified by:
RUN_TIME in interface THINGInterface
Returns:
milliseconds.
Throws:
UserException

ACCEPT_PAUSE

public void ACCEPT_PAUSE()
Accept a pause. If the processes has a pause request, allow the pause. This is for NICE things that will allow the system to pause them.


ACCEPT_HALT

public void ACCEPT_HALT()
                 throws UserException
Accept a halt. If the processes has a halt request, allow the halt. It will result in a exception that should be allowed out.

Throws:
UserException

DEFINE_RESULT

public void DEFINE_RESULT(java.lang.String name,
                          java.lang.String description,
                          ResultExpectation expectation)
                   throws UserException
Define a result. It'll overwrite any result definition of the same name.

Parameters:
name -
description -
expectation -
Throws:
UserException

SET_RESULT

public void SET_RESULT(java.lang.String name,
                       Data.Type resultType)
                throws UserException
Set result based on a result type only. A complete result will not be available for expression. IF the result is alreadt set, it'll be replaced with this result.

Parameters:
name - the name of the result
resultType - the result type as defined in Data
Throws:
a - UserException, usually only if the result was not defined.
UserException
See Also:
Data

SET_RESULT

public void SET_RESULT(java.lang.String name,
                       RESULT result)
                throws UserException
Set result based on a complete RESULT. IF the result is already set, it'll be replaced with this result.

Parameters:
name - the name of the result
result - the actual result
Throws:
a - UserException, usually only if the result was not defined.
UserException

CALCULATE_RESULT

public RESULT CALCULATE_RESULT()
                        throws UserException
Calculate the result based on the defined results and their settings. There are the following rules:
All results must be PASS for the final result to PASS.
A single ABORT will make the final result an ABORT, otherwise:
A single EXCEPTION will make the final result an EXCEPTION, otherwise:
a single FAIL will make the final result a FAIL, otherwise:
a single INCONCLUSIVE will make the final result a FAIL.

Returns:
the overall result.
Throws:
UserException

REQUIRE_PROPERTY

public void REQUIRE_PROPERTY(java.lang.String name)
                      throws UserException
Require a property.

Parameters:
name -
Throws:
UserException

CHECK_REQUIRED

public void CHECK_REQUIRED()
                    throws UserException
Make sure all required properties exist. If they don't, it'll throw an error exception.

Throws:
UserException

init

public void init(SystemInterface si,
                 ControlInterface ci,
                 ExpressionInterface ei,
                 ExpressionInterface parent)
          throws UserException
Initialize this THING.

Parameters:
si - A system interface.
ci - Control interface.
ei - The parent expression interface. If null, nothing will express to it.
Throws:
UserException - which will always be a FAULT.

call_chain

public RESULT call_chain()
                  throws UserException,
                         ThingsException,
                         java.lang.InterruptedException
This is the class call point. This will be invoked by the kernel if it is a root process or another THING through the CALL. Don't call it directly. It is not reentrant.

Returns:
the result
Throws:
UserException
ThingsException
java.lang.InterruptedException

getResult

public RESULT getResult()
Get the final result, if available. Usually, you'd only need to see this if there was a fatal exception.

Returns:
the last result or null if it hasn't been calculated yet. The method getInterimResult will force them to calculate.

getInterimResult

public RESULT getInterimResult()
                        throws ThingsException
Get the interim result, if available. Usually, you'd only need to see this if there was a fatal exception.

Returns:
the most recent results.
Throws:
ThingsException - for whatever reason. It may come from the THING's RESULTS implementation.

getParentExpressionInterface

public ExpressionInterface getParentExpressionInterface()
Get a reference tot he parent expression interface. This exists because java doesn't have friends. Gah. Don't use it. Only the kernel and result managers will.

Returns:
the parent expression interface.


Things.