things.thinger
Interface SystemInterface

All Known Subinterfaces:
SystemSuperInterface
All Known Implementing Classes:
KernelBasic, KernelBasicBase

public interface SystemInterface

System Interface.

Version:
1.0

Version History

EPG - Initial - 7 OCT 03
 
Author:
Erich P. Gatejen

Field Summary
static int DEFAULT_REPORTING_THRESHOLD
          General constants
 
Method Summary
 WhoAmI getCallingProcessId()
          Get process ID for the calling prosess.
 ThingsPropertyViewReader getConfigProperties()
          Get the read only properties for this for the caller only.
 ThingsPropertyView getLocalProperties()
          Get local property view for the caller only.
 ThingsPropertyTree getLocalPropertiesImplementation()
          Get an empty tree using the preferred, non-persistent implementation for the local host.
 FileSystemLocator getLogLocal(java.lang.String id)
          Get a local reference to the log if possible.
 ExpressionInterface getNamedExpressor(java.lang.String name)
          Forge a new named expressor.
 Logger getNamedLogger(java.lang.String name)
          Forge a new named logger.
 ProcessInterface getProcessInterface(java.lang.String id)
          Get a process interface.
 Table<java.lang.String> getProcessList()
          Get the process list.
 ThingsState getProcessState(java.lang.String id)
          Get the state of a specific process.
 ThingsPropertyView getSharedProperties()
          Get shared property view for this server.
 Logger getSystemLogger()
          Get a system logger for the process.
 Universe getUniverse(java.lang.String name)
          Get a universe by the local name.
 MODULE loadModule(java.lang.String name)
          Load a module but don't do anything with it.
 THING loadThing(java.lang.String name)
          Load a thing but don't run it.
 SystemSuperInterface requestSuperSystemInterface()
          Ask the kernel for a SuperSystemInterface.
 java.lang.String runThing(java.lang.String name)
           
 java.lang.String runThing(java.lang.String name, ExpressionInterface parentExpressor)
          Load and run a thing in a new process, giving an expression parent.
 java.lang.String runThing(java.lang.String name, ExpressionInterface parentExpressor, ThingsPropertyView properties)
          Load and run a thing in a new process, giving an expression parent.
 void waitProcessDone(java.lang.String id)
          Wait until the named process if done (meaning any state that satisfies ProcessInterface.ThingsState.isDeadOrDying()==true).
 

Field Detail

DEFAULT_REPORTING_THRESHOLD

static final int DEFAULT_REPORTING_THRESHOLD
General constants

See Also:
Constant Field Values
Method Detail

getSystemLogger

Logger getSystemLogger()
                       throws SystemException
Get a system logger for the process.

Returns:
A logger.
Throws:
SystemException
See Also:
Logger

getNamedLogger

Logger getNamedLogger(java.lang.String name)
                      throws ThingsException
Forge a new named logger. If a logger already exists for that name, it may cause an exception, depending on how it resolves.

Parameters:
name - the name. It will be unique. It's up to kernel on how the name is resolved.
Returns:
A logger.
Throws:
things.thinger.ThingsException
ThingsException
See Also:
Logger

getNamedExpressor

ExpressionInterface getNamedExpressor(java.lang.String name)
                                      throws ThingsException
Forge a new named expressor.

Parameters:
name - the name. Generally, it should be unique. It's up to kernel on how the name is resolved and if name reuse is allowed.
Returns:
an expression interface.
Throws:
things.thinger.ThingsException
ThingsException
See Also:
ExpressionInterface

getLocalProperties

ThingsPropertyView getLocalProperties()
                                      throws SystemException
Get local property view for the caller only.

Returns:
a property view
Throws:
SystemException

getSharedProperties

ThingsPropertyView getSharedProperties()
                                       throws ThingsException
Get shared property view for this server. Anyone can read and write to them.

Returns:
a property view
Throws:
things.thinger.ThingsException
ThingsException

getConfigProperties

ThingsPropertyViewReader getConfigProperties()
                                             throws SystemException
Get the read only properties for this for the caller only. These are configuration properties managed by the system.

Returns:
a property view reader
Throws:
SystemException

getProcessList

Table<java.lang.String> getProcessList()
                                       throws SystemException
Get the process list.

The process list will be a Table.

Returns:
A table representing the process list.
Throws:
SystemException
See Also:
Table

getProcessState

ThingsState getProcessState(java.lang.String id)
                            throws SystemException
Get the state of a specific process.

If the process is not found, the state is ProcessInterface.ThingsState.STATE_INVALID.

NO CLEARANCE REQUIRED.

Parameters:
id - String id of the process.
Returns:
The state.
Throws:
SystemException
See Also:
ProcessInterface

getProcessInterface

ProcessInterface getProcessInterface(java.lang.String id)
                                     throws SystemException
Get a process interface. You can only get a process of equal or less clearance.

Parameters:
id - String id of the process.
Returns:
The interface
Throws:
SystemException
See Also:
ProcessInterface

waitProcessDone

void waitProcessDone(java.lang.String id)
                     throws SystemException,
                            java.lang.InterruptedException
Wait until the named process if done (meaning any state that satisfies ProcessInterface.ThingsState.isDeadOrDying()==true).

If the process is not found, it will quietly return.

NO CLEARANCE REQUIRED.

Parameters:
id - String id of the process.
Throws:
SystemException - for general errors or InterruptedException for thread control. Always let the InterruptedException out.
java.lang.InterruptedException
See Also:
ProcessInterface

getLogLocal

FileSystemLocator getLogLocal(java.lang.String id)
                              throws ThingsException,
                                     java.lang.InterruptedException
Get a local reference to the log if possible. This is totally up to the implementation. It may be the whole log, a snippet, or null (no log at all).

NO CLEARANCE REQUIRED.

Parameters:
id - String id of the process.
Returns:
log file locator or null
Throws:
things.thinger.ThingsException - for general errors or InterruptedException for thread control. Always let the InterruptedException out.
ThingsException
java.lang.InterruptedException
See Also:
ProcessInterface, FileSystemLocator

loadThing

THING loadThing(java.lang.String name)
                throws SystemException
Load a thing but don't run it. It will only construct. It's up to the user to initialize and call it. Typically, the user should call .init() and then .call_chain(). This is mostly so that THINGs can calll other THINGs, so perhaps it is best to just use THING.CALL instead--if you can.

Parameters:
name - the name that the loader can use to find it. Typically, the full class name.
Returns:
The constructed thing.
Throws:
SystemException

loadModule

MODULE loadModule(java.lang.String name)
                  throws SystemException
Load a module but don't do anything with it. It will only construct. It's up to the user to initialize it.

Parameters:
name - the name that the loader can use to find it. Typically, the full class name.
Returns:
The constructed MODULE
Throws:
SystemException

runThing

java.lang.String runThing(java.lang.String name)
                          throws SystemException
Parameters:
name - the resolvable name of the thing.oad and run a thing in a new process.
Returns:
The process id of the THING.
Throws:
SystemException

runThing

java.lang.String runThing(java.lang.String name,
                          ExpressionInterface parentExpressor)
                          throws ThingsException
Load and run a thing in a new process, giving an expression parent. All expressions will go to the parent, plus whatever local mechanism the kernel decides.

Parameters:
name - the resolvable name of the thing.
parentExpressor - the parent expressor.
Returns:
The process id of the THING.
Throws:
things.thinger.ThingsException
ThingsException

runThing

java.lang.String runThing(java.lang.String name,
                          ExpressionInterface parentExpressor,
                          ThingsPropertyView properties)
                          throws ThingsException
Load and run a thing in a new process, giving an expression parent. All expressions will go to the parent, plus whatever local mechanism the kernel decides. This will let you add properties to the THING's view before it starts.

Parameters:
name - the resolvable name of the thing.
parentExpressor - the parent expressor. Set to null if there is no parent.
properties - properties to add to the THING processes specific view.
Returns:
The process id of the THING.
Throws:
things.thinger.ThingsException
ThingsException

requestSuperSystemInterface

SystemSuperInterface requestSuperSystemInterface()
                                                 throws SystemException
Ask the kernel for a SuperSystemInterface. If you can't have it, you'll get a SystemException. Generally, only services are allowed to have it.

Returns:
The super system interface.
Throws:
SystemException
See Also:
SystemSuperInterface

getUniverse

Universe getUniverse(java.lang.String name)
                     throws SystemException
Get a universe by the local name. (This is the local name in the registry.) It will make sure the requestor has sufficient clearance to get it.

Parameters:
name - the local name for the universe
Returns:
The universe.
Throws:
SystemException
See Also:
Universe

getCallingProcessId

WhoAmI getCallingProcessId()
                           throws SystemException
Get process ID for the calling prosess.

Returns:
The ID.
Throws:
SystemException

getLocalPropertiesImplementation

ThingsPropertyTree getLocalPropertiesImplementation()
                                                    throws ThingsException
Get an empty tree using the preferred, non-persistent implementation for the local host.

Returns:
a new property tree.
Throws:
ThingsException


Things.