Package com.scriptbasic.spi

Interface InterpreterHook

All Known Implementing Classes:
NullHook, RunLimitHook, SimpleHook
public interface InterpreterHook
An interpreter hook can be registered into an interpreter and the methods of the hook are called by the interpreter when executing the the BASIC program. Hooks usually are extension means to implement profilers, debuggers and so on.

To implement a hook the class should implement this interface. It is recommended to extend the class SimpleHook instead of implementing a fresh class just implementing this interface. There are a lot of methods in this interface and usually a hook class need functionality only for a subset. The class SimpleHook gives default implementation for the methods and eases hook development providing extended methods.

To make a hook class used by the interpreter the class should be on the classpath during runtime and the configuration key hook.N should contains the FQN of the implementing class. The configuration parameter N should run from 0 ... and the hooks will be registered in the order they are numbered and executed in backward order. To use the hook delivered with jScriptBasic you should configure: 

 hook.0=com.scriptbasic.hooks.RunLimitHook

to have this hook called last (registered first). There are no hooks registered automatically.

The hooks are in a chain and every hook method should call the same hook method on the next hook object on the chain. The hooks are chained backward. The last hook will be called directly by the interpreter and that hook will call the previous and so on. Thus the first hook registered is called last and the last registered will be called first.

A hook method can decide for some good reason to break the chain not invoking the next element in the chain. When implementing a hook class extending the class SimpleHook all methods defined in this interface are implemented. They simply disable hook handling, call the method of the same name with the extra 'Ex' at the end, enable hook handling and then call the next hook. For example the method SimpleHook.beforePop() calls SimpleHook.beforePopEx() and then SimpleHook.beforePop() on the next hook object. During the execution of SimpleHook.beforePopEx() the hook handling is disabled. The methods defined only in SimpleHook are empty and do nothing.

More information about why disabling the hook handling is needed see setReturnValue(RightValue) and Interpreter.disableHook()

Author:
Peter Verhas date Aug 3, 2012

  • Method Summary

    Modifier and Type Method Description
    default java.lang.Object afterCallJavaFunction​(java.lang.reflect.Method method, java.lang.Object result)
    This method is called when the interpreter was calling a Java static method.
    default void afterExecute()
    This method is called after the execution of the whole program has finished.
    default void afterExecute​(Command command)
    This method is called after the interpreter executed a command.
    default void afterPop​(Command command)  
    default void afterPush​(Command command)  
    default void beforeCallJavaFunction​(java.lang.reflect.Method method)  
    default void beforeExecute()
    This method is called before the execution of the program starts.
    default void beforeExecute​(Command command)
    This method is called before the interpreter executes a command.
    default void beforePop()  
    default void beforePush​(Command command)  
    default void beforeRegisteringJavaMethod​(java.lang.String alias, java.lang.Class<?> klass, java.lang.String methodName, java.lang.Class<?>[] argumentTypes)
    This method is called before registering a java method into the interpreter.
    default void beforeSubroutineCall​(java.lang.String subroutineName, LeftValueList arguments, RightValue[] argumentValues)
    This method is called before the interpreter invokes a subroutine.
    default void init()
    This method is called at the end of the hook registering.
    void setInterpreter​(Interpreter interpreter)
    During registration the interpreter calls this method to make the interpreter accessible for the hook objects.
    void setNext​(InterpreterHook next)
    When a hook is registered the registering process calls this method and passes the next element in the hook chain.
    default void setReturnValue​(RightValue returnValue)
    This method is called after a subroutine has set its return value.
    default RightValue variableRead​(java.lang.String variableName, RightValue value)
    This hook is called when the interpreter accesses a variable.

  • Method Details

    • init

      default void init()
      This method is called at the end of the hook registering. When this method is called the hook does have interpreter and the field 'next' already set. The method should do its initialization and then call the same method of the next hook in the chain.

    • setNext

      void setNext​(InterpreterHook next)
      When a hook is registered the registering process calls this method and passes the next element in the hook chain. The hook object should remember this object and call the appropriate methods when that is called not to break the chain.
      Parameters:
      next - the next element in the chain.

    • setInterpreter

      void setInterpreter​(Interpreter interpreter)
      During registration the interpreter calls this method to make the interpreter accessible for the hook objects.
      Parameters:
      interpreter - parameter

    • beforeExecute

      default void beforeExecute​(Command command)
      This method is called before the interpreter executes a command.
      Parameters:
      command - the command object to be executed

    • beforeExecute

      default void beforeExecute()
      This method is called before the execution of the program starts.

    • afterExecute

      default void afterExecute​(Command command)
      This method is called after the interpreter executed a command.
      Parameters:
      command - the command just executed.

    • afterExecute

      default void afterExecute()
      This method is called after the execution of the whole program has finished.

    • beforeRegisteringJavaMethod

      default void beforeRegisteringJavaMethod​(java.lang.String alias, java.lang.Class<?> klass, java.lang.String methodName, java.lang.Class<?>[] argumentTypes)
      This method is called before registering a java method into the interpreter.
      Parameters:
      alias - the name of the function as it will be known to the BASIC program.
      klass - the Java class where the static method is.
      methodName - the Java name of the method
      argumentTypes - the argument types of the methods. This, together with the name of the method and the class identifies the actual method that will be available to the BASIC programs to be called through the name alias.

    • beforePush

      default void beforePush​(Command command)
      Parameters:
      command - parameter

    • afterPush

      default void afterPush​(Command command)
      Parameters:
      command - parameter

    • beforePop

      default void beforePop()

    • afterPop

      default void afterPop​(Command command)
      Parameters:
      command - parameter

    • setReturnValue

      default void setReturnValue​(RightValue returnValue)
      This method is called after a subroutine has set its return value. It is possible to modify the return value calling back to the interpreter but it has to be only invoked together with Interpreter.disableHook() and Interpreter.enableHook().
      Parameters:
      returnValue - parameter
      See Also:
      Interpreter.disableHook()

    • beforeSubroutineCall

      default void beforeSubroutineCall​(java.lang.String subroutineName, LeftValueList arguments, RightValue[] argumentValues)
      This method is called before the interpreter invokes a subroutine. At this point the local variables are those of the subroutine to be called.
      Parameters:
      subroutineName - the symbolic name of the subroutine
      arguments - the argument left values
      argumentValues - the argument evaluated values that were assigned to the local variable table to the arguments

    • beforeCallJavaFunction

      default void beforeCallJavaFunction​(java.lang.reflect.Method method)
      Parameters:
      method - parameter

    • afterCallJavaFunction

      default java.lang.Object afterCallJavaFunction​(java.lang.reflect.Method method, java.lang.Object result)
      This method is called when the interpreter was calling a Java static method. The
      Parameters:
      method - the method that was called
      result - the result that the static method returned
      Returns:
      the modified result or just the same object if the hook does not want to modify the result

    • variableRead

      default RightValue variableRead​(java.lang.String variableName, RightValue value)
      This hook is called when the interpreter accesses a variable.
      Parameters:
      variableName - the name of the variable
      value - the value of the variable when accessed
      Returns:
      the value that will be used. The implementation may decide to alter the value used. Returning a modified value will not, however alterthe value of the variable itself.