Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## things.thing
Class THING

    java.lang.Object
      things.thing.BASE
          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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Things.