NameSpace (jEdit API Documentation)

Package org.gjt.sp.jedit.bsh

## Class NameSpace

- java.lang.Object
- - org.gjt.sp.jedit.bsh.NameSpace

- All Implemented Interfaces:
    `java.io.Serializable`, `BshClassManager.Listener`, `NameSource`
  Direct Known Subclasses:
    `ExternalNameSpace`

      public class NameSpace
      extends java.lang.Object
      implements java.io.Serializable, BshClassManager.Listener, NameSource

  A namespace in which methods, variables, and imports (class names) live. This is package public because it is used in the implementation of some bsh commands. However for normal use you should be using methods on bsh.Interpreter to interact with your scripts.

  A bsh.This object is a thin layer over a NameSpace that associates it with an Interpreter instance. Together they comprise a Bsh scripted object context.

  Note: I'd really like to use collections here, but we have to keep this compatible with JDK1.1

  See Also:
    Serialized Form

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface org.gjt.sp.jedit.bsh.NameSource

      `NameSource.Listener`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected java.util.Hashtable` | `importedClasses` |
    `static NameSpace` | `JAVACODE` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `NameSpace​(BshClassManager classManager, java.lang.String name)` |
    `NameSpace​(NameSpace parent, java.lang.String name)` |
    `NameSpace​(NameSpace parent, BshClassManager classManager, java.lang.String name)` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addCommandPath​(java.lang.String path, java.lang.Class clas)` | Adds a URL to the command path.
    `void` | `addNameSourceListener​(NameSource.Listener listener)` | Implements NameSource Add a listener who is notified upon changes to names in this space.
    `void` | `classLoaderChanged()` | Clear all cached classes and names
    `void` | `clear()` | Clear all variables, methods, and imports from this namespace.
    `void` | `doSuperImport()` | Perform "import *;" causing the entire classpath to be mapped.
    `java.lang.Object` | `get​(java.lang.String name, Interpreter interpreter)` | Resolve name to an object through this namespace.
    `java.lang.String[]` | `getAllNames()` | Implements NameSource
    `protected void` | `getAllNamesAux​(java.util.Vector vec)` | Helper for implementing NameSource
    `java.lang.Class` | `getClass​(java.lang.String name)` | Load a class through this namespace taking into account imports.
    `BshClassManager` | `getClassManager()` |
    `java.io.InputStream` | `getCommand​(java.lang.String name)` | Looks up a command.
    `java.lang.Object` | `getCommand​(java.lang.String name, java.lang.Class[] argTypes, Interpreter interpreter)` | A command is a scripted method or compiled command class implementing a specified method signature.
    `Variable[]` | `getDeclaredVariables()` |
    `This` | `getGlobal​(Interpreter declaringInterpreter)` | Get the top level namespace or this namespace if we are the top.
    `protected BshMethod` | `getImportedMethod​(java.lang.String name, java.lang.Class[] sig)` |
    `protected Variable` | `getImportedVar​(java.lang.String name)` |
    `int` | `getInvocationLine()` |
    `java.lang.String` | `getInvocationText()` |
    `BshMethod` | `getMethod​(java.lang.String name, java.lang.Class[] sig)` |
    `BshMethod` | `getMethod​(java.lang.String name, java.lang.Class[] sig, boolean declaredOnly)` | Get the bsh method matching the specified signature declared in this name space or a parent.
    `java.lang.String[]` | `getMethodNames()` | Get the names of methods declared in this namespace.
    `BshMethod[]` | `getMethods()` | Get the methods defined in this namespace.
    `java.lang.String` | `getName()` | The name of this namespace.
    `NameSpace` | `getParent()` | Get the parent namespace.
    `This` | `getSuper​(Interpreter declaringInterpreter)` | Get the parent namespace' This reference or this namespace' This reference if we are the top.
    `java.lang.Object` | `getVariable​(java.lang.String name)` | Get the specified variable in this namespace or a parent namespace.
    `java.lang.Object` | `getVariable​(java.lang.String name, boolean recurse)` | Get the specified variable in this namespace.
    `protected Variable` | `getVariableImpl​(java.lang.String name, boolean recurse)` | Locate a variable and return the Variable object with optional recursion through parent name spaces.
    `java.lang.String[]` | `getVariableNames()` | Get the names of variables defined in this namespace.
    `static java.lang.Class` | `identifierToClass​(ClassIdentifier ci)` | This is a helper method for working inside of bsh scripts and commands.
    `void` | `importClass​(java.lang.String name)` | Import a class name.
    `void` | `importCommands​(java.lang.String name)` | Import scripted or compiled BeanShell commands in the following package in the classpath.
    `void` | `importObject​(java.lang.Object obj)` | Import a compiled Java object's methods and variables into this namespace.
    `void` | `importPackage​(java.lang.String name)` | subsequent imports override earlier ones
    `void` | `importStatic​(java.lang.Class clas)` |
    `java.lang.Object` | `invokeMethod​(java.lang.String methodName, java.lang.Object[] args, Interpreter interpreter)` | Invoke a method in this namespace with the specified args and interpreter reference.
    `java.lang.Object` | `invokeMethod​(java.lang.String methodName, java.lang.Object[] args, Interpreter interpreter, CallStack callstack, org.gjt.sp.jedit.bsh.SimpleNode callerInfo)` | This method simply delegates to This.invokeMethod();
    `void` | `loadDefaultImports()` | Import standard packages.
    `void` | `nameSpaceChanged()` | Clear all cached classes and names
    `void` | `prune()` | Used for serialization
    `void` | `removeCommandPath​(java.lang.String path, java.lang.Class clas)` | Remove a URLfrom the command path.
    `void` | `setMethod​(java.lang.String name, BshMethod method)` | Note: this is primarily for internal use.
    `void` | `setName​(java.lang.String name)` |
    `void` | `setParent​(NameSpace parent)` |
    `void` | `setTypedVariable​(java.lang.String name, java.lang.Class type, java.lang.Object value, boolean isFinal)` | Deprecated. See #setTypedVariable( String, Class, Object, Modifiers )
    `void` | `setTypedVariable​(java.lang.String name, java.lang.Class type, java.lang.Object value, Modifiers modifiers)` | Declare a variable in the local scope and set its initial value.
    `void` | `setVariable​(java.lang.String name, java.lang.Object value)` |
    `void` | `setVariable​(java.lang.String name, java.lang.Object value, boolean strictJava)` | Set the variable through this namespace.
    `java.lang.String` | `toString()` |
    `void` | `unsetVariable​(java.lang.String name)` | Remove the variable from the namespace.
    `protected java.lang.Object` | `unwrapVariable​(Variable var)` | Unwrap a variable to its value.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### JAVACODE

          public static final NameSpace JAVACODE

    - #### importedClasses

          protected java.util.Hashtable importedClasses

  - ### Constructor Detail

    - #### NameSpace

          public NameSpace​(NameSpace parent,
                           java.lang.String name)

      Parameters:
        `parent` - the parent namespace of this namespace. Child namespaces inherit all variables and methods of their parent and can (of course) override / shadow them.
        `name` - a name

    - #### NameSpace

          public NameSpace​(BshClassManager classManager,
                           java.lang.String name)

    - #### NameSpace

          public NameSpace​(NameSpace parent,
                           BshClassManager classManager,
                           java.lang.String name)

  - ### Method Detail

    - #### setName

          public void setName​(java.lang.String name)

    - #### getName

          public java.lang.String getName()

      The name of this namespace. If the namespace is a method body namespace then this is the name of the method. If it's a class or class instance then it's the name of the class.

    - #### get

          public java.lang.Object get​(java.lang.String name,
                                      Interpreter interpreter)
                               throws UtilEvalError

      Resolve name to an object through this namespace.
      Throws:
        `UtilEvalError`

    - #### setVariable

          public void setVariable​(java.lang.String name,
                                  java.lang.Object value,
                                  boolean strictJava)
                           throws UtilEvalError

      Set the variable through this namespace. This method obeys the LOCALSCOPING property to determine how variables are set.

      Note: this method is primarily intended for use internally. If you use this method outside of the bsh package and wish to set variables with primitive values you will have to wrap them using bsh.Primitive.

      Parameters:
        `strictJava` - specifies whether strict java rules are applied.
      Throws:
        `UtilEvalError`
      See Also:
        `Setting a new variable (which didn't exist before) or removing a variable causes a namespace change.`

    - #### unsetVariable

          public void unsetVariable​(java.lang.String name)

      Remove the variable from the namespace.

    - #### getVariableNames

          public java.lang.String[] getVariableNames()

      Get the names of variables defined in this namespace. (This does not show variables in parent namespaces).

    - #### getMethodNames

          public java.lang.String[] getMethodNames()

      Get the names of methods declared in this namespace. (This does not include methods in parent namespaces).

    - #### getMethods

          public BshMethod[] getMethods()

      Get the methods defined in this namespace. (This does not show methods in parent namespaces). Note: This will probably be renamed getDeclaredMethods()

    - #### getParent

          public NameSpace getParent()

      Get the parent namespace. Note: this isn't quite the same as getSuper(). getSuper() returns 'this' if we are at the root namespace.

    - #### getSuper

          public This getSuper​(Interpreter declaringInterpreter)

      Get the parent namespace' This reference or this namespace' This reference if we are the top.

    - #### getGlobal

          public This getGlobal​(Interpreter declaringInterpreter)

      Get the top level namespace or this namespace if we are the top. Note: this method should probably return type bsh.This to be consistent with getThis();

    - #### getClassManager

          public BshClassManager getClassManager()

    - #### prune

          public void prune()

      Used for serialization

    - #### setParent

          public void setParent​(NameSpace parent)

    - #### getVariable

          public java.lang.Object getVariable​(java.lang.String name)
                                       throws UtilEvalError

      Get the specified variable in this namespace or a parent namespace.

      Note: this method is primarily intended for use internally. If you use this method outside of the bsh package you will have to use Primitive.unwrap() to get primitive values.

      Returns:
        The variable value or Primitive.VOID if it is not defined.
      Throws:
        `UtilEvalError`
      See Also:
        `Primitive.unwrap( Object )`

    - #### getVariable

          public java.lang.Object getVariable​(java.lang.String name,
                                              boolean recurse)
                                       throws UtilEvalError

      Get the specified variable in this namespace.
      Parameters:
        `recurse` - If recurse is true then we recursively search through parent namespaces for the variable.

        Note: this method is primarily intended for use internally. If you use this method outside of the bsh package you will have to use Primitive.unwrap() to get primitive values.

      Returns:
        The variable value or Primitive.VOID if it is not defined.
      Throws:
        `UtilEvalError`
      See Also:
        `Primitive.unwrap( Object )`

    - #### getVariableImpl

          protected Variable getVariableImpl​(java.lang.String name,
                                             boolean recurse)
                                      throws UtilEvalError

      Locate a variable and return the Variable object with optional recursion through parent name spaces.

      If this namespace is static, return only static variables.

      Returns:
        the Variable value or null if it is not defined
      Throws:
        `UtilEvalError`

    - #### getDeclaredVariables

          public Variable[] getDeclaredVariables()

    - #### unwrapVariable

          protected java.lang.Object unwrapVariable​(Variable var)
                                             throws UtilEvalError

      Unwrap a variable to its value.
      Returns:
        return the variable value. A null var is mapped to Primitive.VOID
      Throws:
        `UtilEvalError`

    - #### setTypedVariable

          @Deprecated
          public void setTypedVariable​(java.lang.String name,
                                       java.lang.Class type,
                                       java.lang.Object value,
                                       boolean isFinal)
                                throws UtilEvalError

      Deprecated.
      See #setTypedVariable( String, Class, Object, Modifiers )
      Throws:
        `UtilEvalError`

    - #### setTypedVariable

          public void setTypedVariable​(java.lang.String name,
                                       java.lang.Class type,
                                       java.lang.Object value,
                                       Modifiers modifiers)
                                throws UtilEvalError

      Declare a variable in the local scope and set its initial value. Value may be null to indicate that we would like the default value for the variable type. (e.g. 0 for integer types, null for object types). An existing typed variable may only be set to the same type. If an untyped variable of the same name exists it will be overridden with the new typed var. The set will perform a Types.getAssignableForm() on the value if necessary.

      Note: this method is primarily intended for use internally. If you use this method outside of the bsh package and wish to set variables with primitive values you will have to wrap them using bsh.Primitive.

      Parameters:
        `value` - If value is null, you'll get the default value for the type
        `modifiers` - may be null
      Throws:
        `UtilEvalError`
      See Also:
        `Primitive`

    - #### setMethod

          public void setMethod​(java.lang.String name,
                                BshMethod method)
                         throws UtilEvalError

      Note: this is primarily for internal use.
      Throws:
        `UtilEvalError`
      See Also:
        `Interpreter.source( String )`, `Interpreter.eval( String )`

    - #### getMethod

          public BshMethod getMethod​(java.lang.String name,
                                     java.lang.Class[] sig)
                              throws UtilEvalError

      Throws:
        `UtilEvalError`
      See Also:
        `getMethod( String, Class [], boolean )`, `getMethod( String, Class [] )`

    - #### getMethod

          public BshMethod getMethod​(java.lang.String name,
                                     java.lang.Class[] sig,
                                     boolean declaredOnly)
                              throws UtilEvalError

      Get the bsh method matching the specified signature declared in this name space or a parent.

      Note: this method is primarily intended for use internally. If you use this method outside of the bsh package you will have to be familiar with BeanShell's use of the Primitive wrapper class.

      Parameters:
        `declaredOnly` - if true then only methods declared directly in this namespace will be found and no inherited or imported methods will be visible.
      Returns:
        the BshMethod or null if not found
      Throws:
        `UtilEvalError`
      See Also:
        `Primitive`

    - #### importClass

          public void importClass​(java.lang.String name)

      Import a class name. Subsequent imports override earlier ones

    - #### importPackage

          public void importPackage​(java.lang.String name)

      subsequent imports override earlier ones

    - #### importCommands

          public void importCommands​(java.lang.String name)

      Import scripted or compiled BeanShell commands in the following package in the classpath. You may use either "/" path or "." package notation. e.g. importCommands("/bsh/commands") or importCommands("bsh.commands") are equivalent. If a relative path style specifier is used then it is made into an absolute path by prepending "/".

    - #### getCommand

          public java.lang.Object getCommand​(java.lang.String name,
                                             java.lang.Class[] argTypes,
                                             Interpreter interpreter)
                                      throws UtilEvalError

      A command is a scripted method or compiled command class implementing a specified method signature. Commands are loaded from the classpath and may be imported using the importCommands() method.

      This method searches the imported commands packages for a script or command object corresponding to the name of the method. If it is a script the script is sourced into this namespace and the BshMethod for the requested signature is returned. If it is a compiled class the class is returned. (Compiled command classes implement static invoke() methods).

      The imported packages are searched in reverse order, so that later imports take priority. Currently only the first object (script or class) with the appropriate name is checked. If another, overloaded form, is located in another package it will not currently be found. This could be fixed.

      Parameters:
        `name` - is the name of the desired command method
        `argTypes` - is the signature of the desired command method.
      Returns:
        a BshMethod, Class, or null if no such command is found.
      Throws:
        `UtilEvalError` - if loadScriptedCommand throws UtilEvalError i.e. on errors loading a script that was found

    - #### getImportedMethod

          protected BshMethod getImportedMethod​(java.lang.String name,
                                                java.lang.Class[] sig)
                                         throws UtilEvalError

      Throws:
        `UtilEvalError`

    - #### getImportedVar

          protected Variable getImportedVar​(java.lang.String name)
                                     throws UtilEvalError

      Throws:
        `UtilEvalError`

    - #### getClass

          public java.lang.Class getClass​(java.lang.String name)
                                   throws UtilEvalError

      Load a class through this namespace taking into account imports. The class search will proceed through the parent namespaces if necessary.
      Returns:
        null if not found.
      Throws:
        `UtilEvalError`

    - #### getAllNames

          public java.lang.String[] getAllNames()

      Implements NameSource
      Specified by:
        `getAllNames` in interface `NameSource`
      Returns:
        all variable and method names in this and all parent namespaces

    - #### getAllNamesAux

          protected void getAllNamesAux​(java.util.Vector vec)

      Helper for implementing NameSource

    - #### addNameSourceListener

          public void addNameSourceListener​(NameSource.Listener listener)

      Implements NameSource Add a listener who is notified upon changes to names in this space.
      Specified by:
        `addNameSourceListener` in interface `NameSource`

    - #### doSuperImport

          public void doSuperImport()
                             throws UtilEvalError

      Perform "import *;" causing the entire classpath to be mapped. This can take a while.
      Throws:
        `UtilEvalError`

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### invokeMethod

          public java.lang.Object invokeMethod​(java.lang.String methodName,
                                               java.lang.Object[] args,
                                               Interpreter interpreter)
                                        throws EvalError

      Invoke a method in this namespace with the specified args and interpreter reference. No caller information or call stack is required. The method will appear as if called externally from Java.

      Throws:
        `EvalError`
      See Also:
        `invokeMethod`

    - #### invokeMethod

          public java.lang.Object invokeMethod​(java.lang.String methodName,
                                               java.lang.Object[] args,
                                               Interpreter interpreter,
                                               CallStack callstack,
                                               org.gjt.sp.jedit.bsh.SimpleNode callerInfo)
                                        throws EvalError

      This method simply delegates to This.invokeMethod();

      Throws:
        `EvalError`
      See Also:
        `invokeMethod`

    - #### classLoaderChanged

          public void classLoaderChanged()

      Clear all cached classes and names
      Specified by:
        `classLoaderChanged` in interface `BshClassManager.Listener`

    - #### nameSpaceChanged

          public void nameSpaceChanged()

      Clear all cached classes and names

    - #### loadDefaultImports

          public void loadDefaultImports()

      Import standard packages. Currently:

                      importClass("org.gjt.sp.jedit.bsh.EvalError");
                      importClass("org.gjt.sp.jedit.bsh.Interpreter");
                      importPackage("javax.swing.event");
                      importPackage("javax.swing");
                      importPackage("java.awt.event");
                      importPackage("java.awt");
                      importPackage("java.net");
                      importPackage("java.util");
                      importPackage("java.io");
                      importPackage("java.lang");
                      addCommandPath("/org/gjt/sp/jedit/bsh/commands",getClass());

    - #### getInvocationLine

          public int getInvocationLine()

    - #### getInvocationText

          public java.lang.String getInvocationText()

    - #### identifierToClass

          public static java.lang.Class identifierToClass​(ClassIdentifier ci)

      This is a helper method for working inside of bsh scripts and commands. In that context it is impossible to see a ClassIdentifier object for what it is. Attempting to access a method on a ClassIdentifier will look like a static method invocation. This method is in NameSpace for convenience (you don't have to import bsh.ClassIdentifier to use it );

    - #### clear

          public void clear()

      Clear all variables, methods, and imports from this namespace. If this namespace is the root, it will be reset to the default imports.
      See Also:
        `loadDefaultImports()`

    - #### importObject

          public void importObject​(java.lang.Object obj)

      Import a compiled Java object's methods and variables into this namespace. When no scripted method / command or variable is found locally in this namespace method / fields of the object will be checked. Objects are checked in the order of import with later imports taking precedence.

    - #### importStatic

          public void importStatic​(java.lang.Class clas)

    - #### setVariable

          public void setVariable​(java.lang.String name,
                                  java.lang.Object value)
                           throws UtilEvalError

      Throws:
        `UtilEvalError`

    - #### addCommandPath

          public void addCommandPath​(java.lang.String path,
                                     java.lang.Class clas)

      Adds a URL to the command path.

    - #### removeCommandPath

          public void removeCommandPath​(java.lang.String path,
                                        java.lang.Class clas)

      Remove a URLfrom the command path.

    - #### getCommand

          public java.io.InputStream getCommand​(java.lang.String name)

      Looks up a command.