things.thinger.kernel.basic
Class KernelBasic

java.lang.Object
  extended by java.lang.Thread
      extended by things.thinger.kernel.ThingsProcess
          extended by things.thinger.kernel.basic.KernelBasicBase
              extended by things.thinger.kernel.basic.KernelBasic
All Implemented Interfaces:
java.lang.Runnable, Verbose, KernelBasic_Constants, ControlInterface, ProcessInterface, ResourceListener, SystemInterface, SystemSuperInterface

public class KernelBasic
extends KernelBasicBase

Implements a system interface for the basic Kernel.

Version:
1.0

Version History

 EPG - Initial - 12 JUN 05
 EPG - Split base and main - 6 FEB 06
 
Author:
Erich P. Gatejen

Nested Class Summary
 
Nested classes/interfaces inherited from class java.lang.Thread
java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler
 
Field Summary
 
Fields inherited from class things.thinger.kernel.basic.KernelBasicBase
bootstrapLogger, config_LOGGING_FACTORY_IMPLEMENTATION, config_LOGGING_LEVEL, config_SYSTEM_FILESYSTEM_ROOT, config_USER_FILESYSTEM_ROOT, cullPropsOnDeathMap, deathList, deathWatchMonitor, kernelLogger, kernelSpaceID, kernelStoplight, loadedServiceList, loader, localPropertyCache, loggerCache, loggerFileMap, myGlobalPropertiesKit, myGlobalPropertiesTree, myGlobalPropertiesViewRoot, pcbNumber, processes, resources, sharedGlobalPropertiesView, START_PROCESSED_ID, startupRendezvous, systemConduits, systemFilesystem, systemUniverse, universeRegistry, userFilesystem, userGlobalConfigView, userGlobalPropertiesView, userSpaceID, userUniverse, verbose
 
Fields inherited from class things.thinger.kernel.ThingsProcess
DEFAULT_NAME, internalResult, myPostLogger, ssi
 
Fields inherited from class java.lang.Thread
MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY
 
Fields inherited from interface things.thinger.SystemInterface
DEFAULT_REPORTING_THRESHOLD
 
Fields inherited from interface things.thinger.kernel.basic.KernelBasic_Constants
CHANNEL_SYSTEM_BACKBONE, CONFIG_DIRECTORY, CORE_SERVICES, CORE_SERVICES_suffix_CLASS, CORE_SERVICES_suffix_LOCAL, CORE_SERVICES_suffix_NAME, DEBUGGING_IDE, DEFAULT_KERNEL_CLEARANCE, DEFAULT_LOGGING_FACTORY_IMPLEMENTATION, DEFAULT_SERVICE_CLEARANCE, DEFAULT_UNIVERSE_CONFIG, DEFAULT_USER_CLEARANCE, ID_SEPERATOR, KERNEL_ID_STRING, KERNEL_ID_TAG, KERNEL_LOG_PATH, KERNEL_RUNTIME_SLEEP_INTERVAL, KERNEL_SHUTDOWN__SWEEPS, LOG_DIRECTORY, LOG_SUFFIX, LOGGING_FACTORY_IMPLEMENTATION, LOGGING_LEVEL, PROCESS_ID_STRING_PREFIX, PROCESS_ID_TAG_PREFIX, RESOURCENAME_LOGGER_PREFIX, SERVICE_ID_STRING_PREFIX, SERVICE_ID_TAG_PREFIX, SERVICE_LOG_PREFIX, SHARED_ROOT_GLOBAL_SPACE, SYSTEM_FILESYSTEM_ROOT, THINGS_CACHE_LOCATION, THINGS_UNIVERSE_LOCATION_PLY, UNIVERSE_SYSTEM_DEFAULT_NAME_CONFIG, UNIVERSE_USER_DEFAULT_NAME_CONFIG, USER_FILESYSTEM_ROOT, USER_LOG_PREFIX, USER_ROOT, USER_ROOT_CONFIGURED_SPACE, USER_ROOT_GLOBAL_SPACE, USER_ROOT_PROCESS_SPACE, USER_suffix_KERNEL_NAME, USERSPACE_ID_STRING, USERSPACE_ID_TAG
 
Constructor Summary
KernelBasic()
           
 
Method Summary
 void deathNotice(ThingsException te)
          Typically, this is how a process will tell the kernel it is dying, so that the kernel can clear resources.
 void flingException(ThingsException te)
          Typically, this is a last ditch way for a process or module to pass info to the kernel when something very bad is happening.
 WhoAmI getCallingProcessId()
          Get process ID for the calling prosess.
 ThingsPropertyViewReader getConfigProperties()
          Get the read only properties for this for the caller only.
 ThingsPropertyView getConfigPropertiesWritable()
          Get the configuration properties that are writable.
 ThingsPropertyView getGlobalProperties()
          Get system global property view
 ThingsPropertyView getLocalProperties()
          Get local property view for the caller only.
 ThingsPropertyView getLocalProperties(java.lang.String id)
          Get local property view for the given id.
 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.
 ConduitController getSystemConduits()
          Get the system conduit controller.
 Logger getSystemLogger()
          Get a system logger for the process.
This is implemented with the numbered call GET_SYSTEM_LOGGER.
 Universe getUniverse(java.lang.String name)
          Get a universe by the local name.
 ThingsPropertyView getUserGlobalProperties()
          Get user global property view.
 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.
 void registerProcess(PCB processPCB, Clearance processClearance)
          Register a ready-made PCB.
 void requestQuit()
          Ask the server to quit.
 SystemSuperInterface requestSuperSystemInterface()
          Ask the kernel for a SuperSystemInterface.
 java.lang.String runThing(java.lang.String name)
          Load and run a thing in a new process.
 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.
 WhoAmI startProcess(ThingsProcess processObject, ThingsPropertyView properties)
          Start the passed process.
 WhoAmI startProcess(ThingsProcess processObject, ThingsPropertyView properties, Clearance processClearance)
          Start the passed process.
 void waitProcessDone(java.lang.String id)
          Wait until the named process if done (meaning any state that satisfies ProcessInterface.ThingsState.isDeadOrDying()==true).
 
Methods inherited from class things.thinger.kernel.basic.KernelBasicBase
bootstrap, constructThingsProcess, destructThingsProcess, executeThingsProcess, forgeLogger, getListenerId, getProcessName, resourceRevocation, resourceRevoked
 
Methods inherited from class things.thinger.kernel.ThingsProcess
acceptHalt, acceptPause, finalize, fix, forceFinalize, forceHalt, getCurrentState, getCurrentStateNumeric, getProcessId, getResult, getStartTime, getThingsState, init, isVerbose, release, releasePause, requestHalt, requestPause, run, screech, verboseOff, verboseOn
 
Methods inherited from class java.lang.Thread
activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

KernelBasic

public KernelBasic()
            throws SystemException
Throws:
SystemException
Method Detail

getGlobalProperties

public ThingsPropertyView getGlobalProperties()
                                       throws SystemException
Get system global property view

Returns:
a property view
Throws:
SystemException

getUserGlobalProperties

public ThingsPropertyView getUserGlobalProperties()
                                           throws SystemException
Get user global property view.

Returns:
a property view
Throws:
SystemException

getSharedProperties

public 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

getConfigPropertiesWritable

public ThingsPropertyView getConfigPropertiesWritable()
                                               throws SystemException
Get the configuration properties that are writable. Anything that has access to the SSI can touch these.

Returns:
a property view
Throws:
SystemException

getLocalProperties

public ThingsPropertyView getLocalProperties(java.lang.String id)
                                      throws SystemException
Get local property view for the given id.

Parameters:
id - String id of the process.
Returns:
a property view or null if the id doesn't identify any known process.
Throws:
SystemException

requestQuit

public void requestQuit()
Ask the server to quit. This version will cause a rapid forced halt of the kernel. It will try to stop the services. It will not let any SystemException escape.


deathNotice

public void deathNotice(ThingsException te)
Typically, this is how a process will tell the kernel it is dying, so that the kernel can clear resources. This really should be the LAST thing a process does before exiting run(). If can be used instead of flingException.

Parameters:
te - a Things exception that indicates the reason for the death. It may be null if it was normal termination.
Throws:
SystemException
See Also:
WhoAmI

flingException

public void flingException(ThingsException te)
Typically, this is a last ditch way for a process or module to pass info to the kernel when something very bad is happening. There is no feedback loop.

Parameters:
te - a Things exception
Throws:
SystemException
See Also:
WhoAmI

startProcess

public WhoAmI startProcess(ThingsProcess processObject,
                           ThingsPropertyView properties)
                    throws java.lang.Throwable
Start the passed process. Assume a loader will be doing this. The process should be loaded, constructed, but not initialized. If the state is not STATE_CONSTRUCTION, it will throw an exception.
All processes started with this will have DEFAULT_USER_CLEARANCE.

Parameters:
processObject - This will be a ThingsProcess or subclass.
properties - These are properties to add (or supplant) to the processes specific view before starting the process. It is ok to pass null if there are none.
Returns:
the ID of the started process.
Throws:
java.lang.Throwable
See Also:
WhoAmI

startProcess

public WhoAmI startProcess(ThingsProcess processObject,
                           ThingsPropertyView properties,
                           Clearance processClearance)
                    throws java.lang.Throwable
Start the passed process. Assume a loader will be doing this. The process should be loaded, constructed, but not initialized. If the state is not STATE_CONSTRUCTION, it will throw an exception.

Parameters:
processObject - This will be a ThingsProcess or subclass.
properties - These are properties to add (or supplant) to the processes specific view before starting the process. It is ok to pass null if there are none.
processClearance - specify the process clearance level. This must be at or lower than the calling process's clearance.
Returns:
the ID of the started process.
Throws:
java.lang.Throwable
See Also:
WhoAmI

registerProcess

public void registerProcess(PCB processPCB,
                            Clearance processClearance)
                     throws ThingsException
Register a ready-made PCB. It'll allows you to set the clearance level. The kernel may choose to deny the operation. So normally, use startProcess instead. This exists mostly for debugging and testing.

Parameters:
processPCB - This will be a ready-made PCB.
processClearance - The clearance level. This will be immutable.
Throws:
ThingsException

getSystemConduits

public ConduitController getSystemConduits()
                                    throws SystemException
Get the system conduit controller. These are for conduits between privileged services.

Returns:
a ConduitController
Throws:
SystemException
See Also:
ConduitController

getSystemLogger

public Logger getSystemLogger()
                       throws SystemException
Get a system logger for the process.
This is implemented with the numbered call GET_SYSTEM_LOGGER.

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

getNamedLogger

public Logger getNamedLogger(java.lang.String name)
                      throws SystemException
Forge a new named logger. If a logger already exists for that name, it may cause an exception, depending on how it resolves.
KernelBasic treats the name as a universe address and will log to a file at that location.

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

getNamedExpressor

public ExpressionInterface getNamedExpressor(java.lang.String name)
                                      throws SystemException
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:
SystemException
See Also:
ExpressionInterface

getLogLocal

public FileSystemLocator getLogLocal(java.lang.String id)
                              throws SystemException,
                                     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:
SystemException - for general errors or InterruptedException for thread control. Always let the InterruptedException out.
java.lang.InterruptedException
See Also:
ProcessInterface, FileSystemLocator

loadThing

public THING loadThing(java.lang.String name)
                throws SystemException
Load a thing but don't run it. It will only construct. It's up to you 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

public 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

public java.lang.String runThing(java.lang.String name)
                          throws SystemException
Load and run a thing in a new process.

Parameters:
name - The name of the thing. The KernalBasic implementation will assume the name is the same as the full class name. If it cannot find the class in the path, it will fail.
Returns:
The process id of the THING.
Throws:
SystemException

runThing

public java.lang.String runThing(java.lang.String name,
                                 ExpressionInterface parentExpressor)
                          throws SystemException
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:
SystemException

runThing

public java.lang.String runThing(java.lang.String name,
                                 ExpressionInterface parentExpressor,
                                 ThingsPropertyView properties)
                          throws SystemException
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:
SystemException

getLocalProperties

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

Returns:
a property view
Throws:
SystemException

getConfigProperties

public ThingsPropertyViewReader getConfigProperties()
                                             throws SystemException
Get the read only properties for this for the caller only.

Returns:
a property view reader
Throws:
SystemException

getProcessList

public 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

public 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.

Parameters:
id - String id of the process.

NO CLEARANCE REQUIRED.

Returns:
The state.
Throws:
SystemException
See Also:
ProcessInterface

getProcessInterface

public 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

public 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

requestSuperSystemInterface

public 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.

For KernelBasic, anything at or above CLEARANCE.PRIVILEGED can have the supersystem interface, which is most services.

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

getUniverse

public 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

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

Returns:
The ID.
Throws:
SystemException

getLocalPropertiesImplementation

public 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.