bsh
Class NameSpace

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

All Implemented Interfaces:

BshClassManager.Listener, NameSource, java.io.Serializable

Direct Known Subclasses:

BlockNameSpace

public class NameSpace

extends java.lang.Object

implements java.io.Serializable, BshClassManager.Listener, NameSource

A namespace in which methods and variables 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. 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

(package private) static class

NameSpace.TypedVariable

Nested classes inherited from class bsh.NameSource

NameSource.Listener

Field Summary

(package private) SimpleNode	callerInfoNode
private java.util.Hashtable	classCache Local class cache for classes resolved through this namespace using getClass() (taking into account imports).
private java.util.Hashtable	importedClasses
private java.util.Vector	importedPackages
static NameSpace	JAVACODE
private java.util.Hashtable	methods
java.lang.String	name
(package private) java.util.Vector	nameSourceListeners
private NameSpace	parent
private static boolean	superImport "import *;" operation has been performed
private This	thisReference
private java.util.Hashtable	variables

Constructor Summary

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

NameSpace(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.
private static void	assignmentError(java.lang.Class lhs, java.lang.Class rhs)
private void	cacheClass(java.lang.Class c) Helper that caches class.
static java.lang.Object	checkAssignableFrom(java.lang.Object rhs, java.lang.Class lhsType) Deprecated. name changed.
private java.lang.Class	classForName(java.lang.String name)
void	classLoaderChanged() Clear all cached classes and names
void	clear() Clear all variables, methods, and imports from this namespace.
static void	doSuperImport() Perform "import *;" causing the entire classpath to be mapped.
private java.lang.String[]	enumerationToStringArray(java.util.Enumeration e)
private BshMethod[]	flattenMethodCollection(java.util.Enumeration e) Support for friendly getMethods();
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 (as is, through widening, promotion, etc) and if so, return the assignable form of the RHS.
java.lang.Class	getClass(java.lang.String name) Load a class through this namespace taking into account imports.
private java.lang.Class	getClassImpl(java.lang.String name) Implementation of getClass() Load a class through this namespace taking into account imports.
NameSpace	getGlobal()
private java.lang.Class	getImportedClassImpl(java.lang.String name) Try to make the name into an imported class.
java.lang.String[]	getImportedPackages() Deprecated.
java.util.Vector	getImportedPackages(boolean recurse) Get a list of all imported packages in the order in which they were imported...
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()
(package private) Name	getNameResolver(java.lang.String name) This is the factory for Name objects which resolve names within this namespace (e.g.
(package private) SimpleNode	getNode()
NameSpace	getParent() Get the parent namespace.
NameSpace	getSuper()
(package private) This	getThis(Interpreter declaringInterpreter) A This object is a thin layer over a namespace, comprising a bsh object context.
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 java.lang.Object	getVariableImpl(java.lang.String name, boolean recurse) Return the raw variable retrieval (TypedVariable object or for untyped the simple value) with optional recursion.
java.lang.String[]	getVariableNames() Get the names of variables defined in this namespace.
static java.lang.Class	identifierToClass(Name.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	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, SimpleNode callerInfo) invoke a method in this namespace with the specified args, interpreter reference, and callstack This is a convenience for users outside of this package.
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)
(package private) void	setNode(SimpleNode node) Set the node associated with the creation of this namespace.
void	setParent(NameSpace parent)
void	setTypedVariable(java.lang.String name, java.lang.Class type, java.lang.Object value, boolean isFinal) Set the typed variable with the value.
void	setVariable(java.lang.String name, java.lang.Object value) Set a variable in this namespace.
java.lang.String	toString()
protected java.lang.Object	unwrapVariable(java.lang.Object val) Unwrap a typed variable to its value.
private void	writeObject(java.io.ObjectOutputStream s)

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

name

public java.lang.String name

parent

private NameSpace parent

variables

private java.util.Hashtable variables

methods

private java.util.Hashtable methods

importedClasses

private java.util.Hashtable importedClasses

thisReference

private This thisReference

importedPackages

private java.util.Vector importedPackages

superImport

private static transient boolean superImport

"import *;" operation has been performed

classCache

private transient java.util.Hashtable classCache

Local class cache for classes resolved through this namespace using getClass() (taking into account imports). Only unqualified class names are cached here (those which might be imported). Qualified names are always absolute and are cached by BshClassManager.

callerInfoNode

SimpleNode callerInfoNode

nameSourceListeners

java.util.Vector nameSourceListeners

Constructor Detail

NameSpace

public NameSpace(java.lang.String name)

NameSpace

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

Method Detail

setName

public void setName(java.lang.String name)

getName

public java.lang.String getName()

setNode

void setNode(SimpleNode node)

Set the node associated with the creation of this namespace. This is used in debugging.

getNode

SimpleNode getNode()

get

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

Resolve name to an object through this namespace.

EvalError

setVariable

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

Set a variable in this namespace.

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 - a value of null will remove the variable definition.

EvalError

See Also:

Primitive

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

enumerationToStringArray

private java.lang.String[] enumerationToStringArray(java.util.Enumeration e)

flattenMethodCollection

private BshMethod[] flattenMethodCollection(java.util.Enumeration e)

Support for friendly getMethods();

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

getThis

This getThis(Interpreter declaringInterpreter)

A This object is a thin layer over a namespace, comprising a bsh object context. We create it here only if needed for the namespace. Note: that This is factoried for different capabilities. When we add classpath modification we'll have to have a listener here to uncache the This reference and allow it to be refactoried.

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. If recurse is true extend search through parent namespaces.

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 )

unwrapVariable

protected java.lang.Object unwrapVariable(java.lang.Object val)

Unwrap a typed variable to its value. Turn null into Primitive.VOID

getVariableImpl

protected java.lang.Object getVariableImpl(java.lang.String name,
                                           boolean recurse)

Return the raw variable retrieval (TypedVariable object or for untyped the simple value) with optional recursion.

Returns:

the raw variable value or null if it is not defined

setTypedVariable

public void setTypedVariable(java.lang.String name,
                             java.lang.Class type,
                             java.lang.Object value,
                             boolean isFinal)
                      throws EvalError

Set the typed variable with the value. An existing typed variable may only be set to the same type. If an untyped variable 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

EvalError

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.

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

getImportedPackages

public java.lang.String[] getImportedPackages()

Deprecated.

Get a list of all imported packages including parents. in the order in which they were imported... Note that the resolver may use them in the reverse order for precedece reasons.

getImportedPackages

public java.util.Vector getImportedPackages(boolean recurse)

Get a list of all imported packages in the order in which they were imported... If recurse is true, also include the parent's.

cacheClass

private void cacheClass(java.lang.Class c)

Helper that caches class.

getClass

public java.lang.Class getClass(java.lang.String name)
                         throws ClassPathException

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.

ClassPathException

getClassImpl

private java.lang.Class getClassImpl(java.lang.String name)
                              throws ClassPathException

Implementation of getClass() Load a class through this namespace taking into account imports.

Check the cache first. If an unqualified name look for imported class or package. Else try to load absolute name.

This method implements caching of unqualified names (normally imports). Qualified names are cached by BshClassManager. Unqualified absolute class names (e.g. unpackaged Foo) are cached too so that we don't go searching through the imports for them each time.

Returns:

null if not found.

ClassPathException

getImportedClassImpl

private java.lang.Class getImportedClassImpl(java.lang.String name)
                                      throws ClassPathException

Try to make the name into an imported class. This method takes into account only imports (class or package) found directly in this NameSpace (no parent chain).

ClassPathException

classForName

private java.lang.Class classForName(java.lang.String name)

getAllNames

public java.lang.String[] getAllNames()

Implements NameSource

Specified by:

getAllNames in interface NameSource

Returns:

all class and variable 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 static void doSuperImport()
                          throws EvalError

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

EvalError

checkAssignableFrom

public static java.lang.Object checkAssignableFrom(java.lang.Object rhs,
                                                   java.lang.Class lhsType)
                                            throws EvalError

Deprecated. name changed.

EvalError

See Also:

getAssignableForm( Object, Class )

getAssignableForm

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

Determine if the RHS object can be assigned to the LHS type (as is, through widening, promotion, etc) and if so, return the assignable form of the RHS. Note that this is *not* a cast operation. Only assignments which are always legal (upcasts, promotion) are passed.

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.

The primary purpose of the abstraction "returning the assignable form" abstraction is to allow non standard bsh assignment conversions. e.g. the wrapper stuff. I'm still not sure how much of that we should be doing.

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

Returns:

an assignable form of the RHS or throws EvalError

Throws:

EvalError - on non assignable

See Also:

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

assignmentError

private static void assignmentError(java.lang.Class lhs,
                                    java.lang.Class rhs)
                             throws EvalError

EvalError

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

writeObject

private void writeObject(java.io.ObjectOutputStream s)
                  throws java.io.IOException

java.io.IOException

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. The caller namespace is set to this namespace. This is a convenience for users outside of this package.

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

EvalError

See Also:

Primitive

invokeMethod

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

invoke a method in this namespace with the specified args, interpreter reference, and callstack This is a convenience for users outside of this package.

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

EvalError

See Also:

Primitive

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");
                        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");
                

getNameResolver

Name getNameResolver(java.lang.String name)

This is the factory for Name objects which resolve names within this namespace (e.g. toObject(), toClass(), toLHS()). This supports name resolver caching, allowing Name objects to cache info about the resolution of names for performance reasons. (This would be called getName() if it weren't already used for the simple name of the NameSpace)

getInvocationLine

public int getInvocationLine()

getInvocationText

public java.lang.String getInvocationText()

identifierToClass

public static java.lang.Class identifierToClass(Name.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 it will look like a static method invocation.

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