bsh
Class NameSpace

java.lang.Object
  |
  +--bsh.NameSpace

All Implemented Interfaces:

BshClassManager.Listener, NameSource, java.io.Serializable

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 inherited from class bsh.NameSource

NameSource.Listener

Field Summary

boolean	isMethod Note that the namespace is a method body namespace.
static NameSpace	JAVACODE
java.lang.String	nsName

Constructor Summary

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

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

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

Method Summary

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
static java.lang.Object	getAssignableForm(java.lang.Object rhs, java.lang.Class lhsType) Determine if the RHS object can be assigned to the LHS type: 1) As in a legal Java assignment (as determined by Reflect.isJavaAssignable()) through widening or promotion 2) Via special BeanShell extensions like interface generation or (gag) numeric-style promotion of primitive wrappers (e.g.
java.lang.Class	getClass(java.lang.String name) Load a class through this namespace taking into account imports.
BshClassManager	getClassManager()
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.
NameSpace	getGlobal()
int	getInvocationLine()
java.lang.String	getInvocationText()
BshMethod	getMethod(java.lang.String name, java.lang.Class[] sig) 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 defined in this namespace.
BshMethod[]	getMethods() Get the methods defined in this namespace.
java.lang.String	getName()
NameSpace	getParent() Get the parent namespace.
NameSpace	getSuper()
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 bsh.NameSpace.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	importPackage(java.lang.String name) subsequent imports override earlier ones
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, 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	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) Declare a variable in the local scope and set its initial 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(bsh.NameSpace.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

nsName

public java.lang.String nsName

isMethod

public boolean isMethod

Note that the namespace is a method body namespace. This is used for printing stack traces in exceptions.

Constructor Detail

NameSpace

public NameSpace(NameSpace parent,
                 java.lang.String 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()

get

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

Resolve name to an object through this namespace.

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.

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 defined in this namespace. (This does not show methods in parent namespaces).

getMethods

public BshMethod[] getMethods()

Get the methods defined in this namespace. (This does not show methods in parent namespaces).

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 NameSpace getSuper()

getGlobal

public NameSpace getGlobal()

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)

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.

See Also:

Primitive.unwrap( Object )

getVariable

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

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.

See Also:

Primitive.unwrap( Object )

getVariableImpl

protected bsh.NameSpace.Variable getVariableImpl(java.lang.String name,
                                                 boolean recurse)

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

Returns:

the Variable value or null if it is not defined

unwrapVariable

protected java.lang.Object unwrapVariable(bsh.NameSpace.Variable var)

Unwrap a variable to its value.

Returns:

return the variable value. A null var is mapped to Primitive.VOID

setTypedVariable

public void setTypedVariable(java.lang.String name,
                             java.lang.Class type,
                             java.lang.Object value,
                             boolean isFinal)
                      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 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

UtilEvalError

See Also:

Primitive

setMethod

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

Note: this is primarily for internal use.

See Also:

Interpreter.source( String ), Interpreter.eval( String )

getMethod

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

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.

Returns:

the BshMethod or null if not found

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

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.

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.

UtilEvalError

getAssignableForm

public static java.lang.Object getAssignableForm(java.lang.Object rhs,
                                                 java.lang.Class lhsType)
                                          throws UtilEvalError

Determine if the RHS object can be assigned to the LHS type:

1) As in a legal Java assignment (as determined by Reflect.isJavaAssignable()) through widening or promotion

2) Via special BeanShell extensions like interface generation or (gag) numeric-style promotion of primitive wrappers (e.g. Short to Integer).

If the assignment is legal in BeanShell return the assignable form of the RHS.

This method is used in many places throughout bsh including assignment operations and method selection.

In normal cases this functions as a simple check for assignability and the value is returned unchanged. e.g. a String is assignable to an Object, but no conversion is necessary. Similarly an int is assignable to a long, so no conversion is done. In this sense assignability is in terms of what the Java reflection API will allow since the reflection api will do widening conversions in the case of sets on fields and arrays. (CLARIFY: what about method args?)

The primary purpose of the "returning the assignable form" abstraction is to allow non-standard Java assignment conversions. e.g. wrapper conversion for boxing and unboxing. Some of this will be considered standard in Java 1.5.

Parameters:

lhsType - lhsType is a real Java class type or Java primitive TYPE

rhs - is a value, bsh.Primitive wrapper, or Primitive.NULL. If it is a Primitive wrapper it will be unwrapped and compared using Reflect.isJavaAssignableFrom(). If it is Primtive.VOID an error will occur.

Returns:

an assignable form of the rhs, usually the original rhs if assignable. If the rhs was a Primitive and it was assignable the Primitive will be returned. If the Primitive needed to be auto-boxed to a wrapper type, the wrapper type will be returned.

Throws:

UtilEvalError - if the assignment cannot be made legally

UtilEvalError - on rhs of Primitive.VOID (void assignment)

See Also:

BSHCastExpression#castObject( java.lang.Object, java.lang.Class )

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.

EvalError

See Also:

bsh.This.invokeMethod( String methodName, Object [] args, Interpreter interpreter, CallStack callstack, SimpleNode callerInfo )

invokeMethod

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

This method simply delegates to This.invokeMethod();

EvalError

See Also:

bsh.This.invokeMethod( String methodName, Object [] args, Interpreter interpreter, CallStack callstack, SimpleNode callerInfo )

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("bsh.EvalError");
                        importClass("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");
                        importCommands("/bsh/commands");
                

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()