Package com.scriptbasic.api

Annotation Interface BasicFunction

@Retention(RUNTIME) public @interface BasicFunction
This annotation interface can be used in classes that define static methods to be called from BASIC code.

Each public static method that is supposed to be reachable from BASIC should have the annotation @BasicFunction. The implementation of the interface Interpreter provides method that registers all the such annotated methods of the class specified.

Author:
Peter Verhas date July 22, 2012

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    alias
    The alias name of the function to be used in the BASIC program.
    Class<?>[]
    classification
    The different methods can be classified and the configuration of the actual interpreter registers or denies the registration of certain methods based on the classification.
    long
    requiredVersion
    The interface version of ScriptBasic for Java required for this method to properly function.
    Class<?>
    substituteClass
    It may happen that the you want to register methods that are not in your hands.
    String
    substituteMethod
    Using this parameter you can specify an alternative method instead of the annotated one.

  • Element Details

    • alias

      String alias
      The alias name of the function to be used in the BASIC program. If this is not defined then the name of the method will be used.
      Returns:
      value
      Default:
      ""

    • requiredVersion

      long requiredVersion
      The interface version of ScriptBasic for Java required for this method to properly function.

      The different versions of ScriptBasic may provide different functionality for the methods registered as functions. When a method needs a specific interface version the interpreter may alter its behavior.

      If a method requires an interface version that is higher than the version of the executing interpreter then the interpreter can not work together with the extension and thus will signal error.

      If a method requires a version that is smaller that the actual version of the executing interpreter then the interpreter may decide if it can work with the extension. There may be three different cases foreseen:

      1. The interpreter can work seamless with an extension that was designed for an earlier version.
      2. The interpreter can not support the outdated extension.
      3. The interpreter mimics the interface of an older version of it provided towards the extension.

      The version specified in this annotation is the version of the 'interface' the interpreter provides for the extensions. This 'interface' is not literally a Java interface, rather the collection of all the interfaces and behaviors that the interpreter exhibits towards the extensions.

      If different versions of ScriptBasic for Java share the same behavior regarding the extensions and thus the two versions are 100% compatible regarding extension support and usage then the two different versions of the interpreter will have the same extension interface version. Therefore you should expect this interface version to change rather infrequent.

      A later version of SB4J should not have a smaller interface version.

      Note that the time I write this documentation the interpreter is in infancy and has a pre-version of 1.

      The actual value of the actual version is defined as a constant: ExtensionInterfaceVersion.EXTENSION_INTERFACE_VERSION.

      Returns:
      value
      Default:
      1L

    • classification

      Class<?>[] classification
      The different methods can be classified and the configuration of the actual interpreter registers or denies the registration of certain methods based on the classification.
      Returns:
      value
      Default:
      {com.scriptbasic.api.BasicFunction.class}

    • substituteClass

      Class<?> substituteClass
      It may happen that the you want to register methods that are not in your hands. In such a case the method can not be instrumented using annotations. Using this annotation parameter you can specify an alternative class where the method you want to register instead of the annotated one is.
      Returns:
      value
      Default:
      com.scriptbasic.api.BasicFunction.class

    • substituteMethod

      String substituteMethod
      Using this parameter you can specify an alternative method instead of the annotated one. See the documentation of substituteClass().
      Returns:
      value
      Default:
      ""