cox.jmatt.java.MathTools
Class CapCom

java.lang.Object
  extended by cox.jmatt.java.MathTools.CapCom

public class CapCom
extends java.lang.Object

This class, consisting solely of static methods, provides a central logging point and data repository. Its constructor is private and final as CapCom should NEVER be instantiated or subclassed. The other classes in MathTools use CapCom to report log messages and to store and retrieve data used internally. Applications built using MathTools may also use CapCom and are encouraged to do so! It provides several services toward that end that the MathTools classes themselves don't use.

CapCom, from NASA's Capsule Command, serves as a centralized point of communication between MathTools classes and the outside world. This communication is based around a global MathPrinter which is set by the setPrinter() method. The MathPrinter interface itself is lightweight, minimalistic, and flexible enough to suit the needs of all MathTools classes: MathTools has no external dependencies for logging or communication. For apps that do, MathPrinter is very easy to implement and its methods were named to (hopefully) avoid collision with other logging packages. CapCom provides static convenience methods for logging debugging information and errors, as well as a println() method and the mathPrintln() method. Most MathTools methods make use of the error() method to report user-correctible goofs.

NOTE: CapCom implements all MathPrinter methods to allow re-sending to the global printer. It does NOT implement the MathPrinter interface because it should NEVER, NEVER be set as the Global Printer!!!

In addition to logging and communication, CapCom provides a central and somewhat anonymous data repository service. It provides The Shelf for storing, fetching and removing Objects. None of the MathTools classes use this but applications extending them might need such. Finally, CapCom provides facilities for the Global Pizza. The Global Pizza is a java.util.Properties Object that can be set and retrieved via static methods. This is primarily intended for scripting applications built using MathTools. Conceptually, the application sets the Global Pizza before executing a script. The script is then allowed access to the Global Pizza for fetching String parameters or configuration information. MathConsole provides exactly this capability.

For classes that potentially require code outside the MathTools JAR, CapCom provides a place to store and retrieve a ClassLoader. The MathClassLoader is set automatically by ScriptPanel from its URLLoaderPanel, whether or not it uses the ClassLoader for its ScriptEngineFactories. Other MathTools classes that might require such access either use this ClassLoader automatically OR have methods to trigger its use.

To facilitate MathTools scripting, CapCom defines the installStandardObjects() method. This method takes as a parameter a javax.script.ScriptEngine and installs the MathTools classes along with a MathConsole into it. See the ScriptPanel docs for the tools installed and their names.


Field Summary
static boolean allowAccessories
          This field determines whether or not CapCom will create accessories on demand.
static boolean allowConsoleAuthenticatorAccess
          This field controls whether or not a MathConsole instance is allowed to set the Global Authenticator.
 
Method Summary
static boolean authenticate(byte pLevel, java.lang.String pCode)
          Check an authentication code and level using the global Authenticator.
static MathToolsAccessory createAccessory(java.lang.String pAccessory)
          Create a MathToolsAccessory from its full class name.
static void debug(java.lang.String pMesg)
           
static void debug(java.lang.String pMesg, java.lang.Throwable pThr)
           
static void error(java.lang.String pMesg)
           
static void error(java.lang.String pMesg, java.lang.Throwable pThr)
           
static java.lang.String[] generateAuthenticationCodes(byte pLevel, int pNumber, java.lang.Object... pParams)
          If an Authenticator is set this method calls on it to generate an array of authentication codes.
static java.lang.ClassLoader getMathClassLoader()
          The MathTools ClassLoader is maintained by CapCom for MathTools (or application!) classes that might need one.
static javax.naming.Context getNamingContext()
          Use this method to retrieve a JNDI naming Context if one exists.
static java.lang.Object getObject(java.lang.String pKey)
          Fetch a previously-stored Object from the Shelf.
static java.util.Properties getPizza()
          Retrieve a copy of the Global Pizza.
static java.lang.Object getScriptReturnObject()
          Retrieve the script return Object set by MathConsole.
static java.lang.String getStackTrace(java.lang.Throwable pThr)
          Utility method to extract the stack trace from a Throwable and return it as a String.
static long hitCount()
          CapCom maintains a simple counter useful for generating application-unique numbers.
static void info(java.lang.String pMesg)
           
static void info(java.lang.String pMesg, java.lang.Throwable pThr)
           
static void installStandardObjects(javax.script.ScriptEngine pEngine, boolean pAWT, boolean pFiles)
          This method installs the Standard Objects into the ScriptEngine provided.
static boolean isPrinterSet()
          Check to see if a Global Printer is set.
static void mathLog(byte pLevel, java.lang.String pMesg, java.lang.Throwable pThr)
          Echo a log message to the global MathPrinter, if it is set.
static void mathPrintln(java.lang.String pMesg)
          Send a message to the printer's mathPrintln() method, if a printer is set.
static void println(java.lang.String pMesg)
          Convenience method for mathPrintln().
static java.lang.Object processMathObject(java.lang.Object pData)
          This method reflects processMathObject() calls to the global MathPrinter, if such exists.
static java.lang.Object removeObject(java.lang.String pKey)
          Pull something off the Shelf and remove it from storage completely.
static void setMathClassLoader(java.lang.ClassLoader pLoader)
          This method is used to set the MathTools ClassLoader.
static void setMAuthenticator(java.lang.String pAuthClass, java.lang.Object pContext)
          This method sets or clears a global MAuthenticator.
static void setNamingContext(javax.naming.Context pContext)
          This method sets a JNDI naming Context usable by any of the MathTools classes or applications embedding them.
static void setPizza(java.util.Properties pPizza)
          Set in place a Global Pizza.
static void setPrinter(MathPrinter pPrinter)
          Use this method to set a global MathPrinter for all MathTools classes to use.
static void setScriptReturnObject(java.lang.Object pRetObj)
          Set the Object a script returns.
static void storeObject(java.lang.String pKey, java.lang.Object pData)
          This method provides a place for MathTools classes, or applications that use them, to store arbitrary data (The Shelf).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

allowConsoleAuthenticatorAccess

public static boolean allowConsoleAuthenticatorAccess
This field controls whether or not a MathConsole instance is allowed to set the Global Authenticator. By default it is false. If this is not desirable it can be changed from within a MathTools application. ScriptPanel also sets this field; its default value is true but is easily changed via a Config Panel checkbox.


allowAccessories

public static boolean allowAccessories
This field determines whether or not CapCom will create accessories on demand. It is false by default but ScriptPanel resets it to true automatically. Other applications should set it appropriately otherwise accessory classes will not be available.

Method Detail

getMathClassLoader

public static java.lang.ClassLoader getMathClassLoader()

The MathTools ClassLoader is maintained by CapCom for MathTools (or application!) classes that might need one. By default URLLoaderPanel sets it before script execution. If a ClassLoader is set this method returns it, otherwise it returns the loader used by the MathTools package.

NOTE: This method always returns a valid ClassLoader! If no loader is set or it is set to null this method automatically resets it to Class.forName('..CapCom').getClassLoader().


setMathClassLoader

public static void setMathClassLoader(java.lang.ClassLoader pLoader)

This method is used to set the MathTools ClassLoader. If set to null the next call to getClassLoader() sets the loader used by the MathTools package and not the bootstrap loader.

IMPORTANT NOTE: The ClassLoader maintained here is not copied. Set with care!


getNamingContext

public static javax.naming.Context getNamingContext()
Use this method to retrieve a JNDI naming Context if one exists. Although MathDBC is the only class that currently uses it such a thing might be retrofitted into other classes, or user applications may also require it.


setNamingContext

public static void setNamingContext(javax.naming.Context pContext)
This method sets a JNDI naming Context usable by any of the MathTools classes or applications embedding them.

Parameters:
pContext - The javax.naming.Context to be set.

setMAuthenticator

public static void setMAuthenticator(java.lang.String pAuthClass,
                                     java.lang.Object pContext)
This method sets or clears a global MAuthenticator. The fully-qualified class name must be given and the MathTools ClassLoadar is automatically used. If the class is successfully created it is set as the global authenticator. If the supplied String is null or empty the authenticator is cleared. Any errors are reported at Error level.

Parameters:
pAuthClass - The fully-qualified classname of the MAuthenticator implementation to use.
pContext - The context Object sent to initialize the Authenticator.

authenticate

public static boolean authenticate(byte pLevel,
                                   java.lang.String pCode)
Check an authentication code and level using the global Authenticator. If no MAuthenticator instance is set the return value is automatically false. If one is set it is checked and this method returns whatever value it does.

Parameters:
pLevel - The AUTH_ level constant of the code being checked.
pCode - The authentication code actually being checked.
Returns:
false if no MAuthenticator is set, or the value returned by checking the authenticator that IS set.

generateAuthenticationCodes

public static java.lang.String[] generateAuthenticationCodes(byte pLevel,
                                                             int pNumber,
                                                             java.lang.Object... pParams)
If an Authenticator is set this method calls on it to generate an array of authentication codes. If no MAuthenticator is set the return value is an empty array.

Parameters:
pLevel - The AUTH_ level of the codes to generate.
pNumber - The number of codes to generate.
pParams - Implementation-specific Object parameters.
Returns:
Whatever the global authenticator returns, or an empty array if none is set.

createAccessory

public static MathToolsAccessory createAccessory(java.lang.String pAccessory)
Create a MathToolsAccessory from its full class name. If allowAccessories is false or the class cannot be created null is returned. If the name is null or blank the return value is null.

Parameters:
pAccessory - The fully-qualified classname of the accessory to create
Returns:
A new instance of the accessory or null if not allowed or not found.

setPrinter

public static void setPrinter(MathPrinter pPrinter)
Use this method to set a global MathPrinter for all MathTools classes to use. If the parameter is null (default), no MathPrinter is set and any previously-set MathPrinter is removed.


isPrinterSet

public static boolean isPrinterSet()
Check to see if a Global Printer is set.


mathPrintln

public static void mathPrintln(java.lang.String pMesg)
Send a message to the printer's mathPrintln() method, if a printer is set.


println

public static void println(java.lang.String pMesg)
Convenience method for mathPrintln().


processMathObject

public static java.lang.Object processMathObject(java.lang.Object pData)
This method reflects processMathObject() calls to the global MathPrinter, if such exists. If the printer is defined, processMathObject() returns whatever it returns. If not, it returns pData unaltered.

Parameters:
pData - The Object to be processed.
Returns:
Whatever the global printer does, or pData if it does not exist.

mathLog

public static void mathLog(byte pLevel,
                           java.lang.String pMesg,
                           java.lang.Throwable pThr)
Echo a log message to the global MathPrinter, if it is set. In addition to this method, two convenience methods are also defined for each log level: Info, Debug, and Error. The first method accepts a String parameter, the second a String and Throwable. The convenience methods all reflect to this one. This method itself exactly mimics the mathLog() method specified in MathPrinter. If no MathPrinter is set this method returns silently.


error

public static void error(java.lang.String pMesg)

error

public static void error(java.lang.String pMesg,
                         java.lang.Throwable pThr)

debug

public static void debug(java.lang.String pMesg)

debug

public static void debug(java.lang.String pMesg,
                         java.lang.Throwable pThr)

info

public static void info(java.lang.String pMesg)

info

public static void info(java.lang.String pMesg,
                        java.lang.Throwable pThr)

getStackTrace

public static java.lang.String getStackTrace(java.lang.Throwable pThr)
Utility method to extract the stack trace from a Throwable and return it as a String.


setPizza

public static void setPizza(java.util.Properties pPizza)
Set in place a Global Pizza. The Global Pizza is a Properties object useful to scripting applications. Setting the Global Pizza to null clears it. This method does make a copy of pPizza if it is not null, so altering the original will not affect the Global Pizza.


getPizza

public static java.util.Properties getPizza()
Retrieve a copy of the Global Pizza. If it is null, an empty Properties object is returned. If the Global Pizza is set, a copy of it is returned.


hitCount

public static long hitCount()
CapCom maintains a simple counter useful for generating application-unique numbers. It's simply an internal variable that increments each time this method is called.


storeObject

public static void storeObject(java.lang.String pKey,
                               java.lang.Object pData)
This method provides a place for MathTools classes, or applications that use them, to store arbitrary data (The Shelf). If the key is not valid or the data is null both are ignored. It is backed by an internal static Hashtable<String, Object>.

Parameters:
pKey - The String key by which the data is to be stored.
pData - The data Object to be stored.

getObject

public static java.lang.Object getObject(java.lang.String pKey)
Fetch a previously-stored Object from the Shelf. If the key is not valid or the shelf doesn't have the item this method returns null.

Parameters:
pKey - The name of the Object to pull off the Shelf.
Returns:
The Object shelved under pKey, or null if it does not exist.

removeObject

public static java.lang.Object removeObject(java.lang.String pKey)
Pull something off the Shelf and remove it from storage completely. Returns null if the key is not valid or the Object isn't there.

Parameters:
pKey - The key of the Object to remove from the Shelf.
Returns:
The specified Object or null if it's not there.

setScriptReturnObject

public static void setScriptReturnObject(java.lang.Object pRetObj)
Set the Object a script returns. This is the method MathConsole.returns() uses.

Parameters:
pRetObj - The (script return) Object set by the MathConsole method.

getScriptReturnObject

public static java.lang.Object getScriptReturnObject()
Retrieve the script return Object set by MathConsole.


installStandardObjects

public static final void installStandardObjects(javax.script.ScriptEngine pEngine,
                                                boolean pAWT,
                                                boolean pFiles)

This method installs the Standard Objects into the ScriptEngine provided. See the ScriptPanel docs for details. NOTE: The static versions of these objects are the ones installed! Classes with SCROB aliases all have a getSCROB() method to acquire one.

CapCom exposes the following MathTools classes as its Standard Objects:

Classes marked 'SCROB' are the classes with SCROBs. If the standard (static) instances of these classes do not function, each of these classes has a getSCROB() method that returns an instance of its SCROB.

Classes marked 'XML' have a toXML() method to generate MathTools XML tags. Instances of these classes may be created with specific data and written to a file (or String) that MTXProcessor can convert back into their MathTools class instances. MFormatElement, Problem, and Answer also appear as XML tags but these are contained within other classes. Note: The instances exposed to ScriptPanel are default instances; the data within them is not particularly interesting!

The 'pAWT' parameter is present to allow suppression of tools that depend on java.awt.* classes. The 'pFiles' parameter allows suppression of MathFileIO.

CRITICAL NOTE: The name-Object bindings listed here are fragile!! Executing the statement 'Console = null' in a script REMOVES THE CONSOLE OBJECT!! Assign with care! This is done purposefully to allow such code as Arithmetic = Arithmetic.getSCROB() to function properly and allow scripts to be more portable.