You are viewing a plain text version of this content. The canonical link for it is here.
Posted to bsf-dev@jakarta.apache.org by se...@apache.org on 2009/03/25 14:30:08 UTC
svn commit: r758248 -
/jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/
Author: sebb
Date: Wed Mar 25 13:29:59 2009
New Revision: 758248
URL: http://svn.apache.org/viewvc?rev=758248&view=rev
Log:
Javadoc updates
Modified:
jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/AbstractScriptEngine.java
jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/Bindings.java
jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/Compilable.java
jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/CompiledScript.java
jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/Invocable.java
jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/ScriptContext.java
jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/ScriptEngine.java
jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/ScriptEngineFactory.java
jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/ScriptEngineManager.java
jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/SimpleBindings.java
jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/SimpleScriptContext.java
Modified: jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/AbstractScriptEngine.java
URL: http://svn.apache.org/viewvc/jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/AbstractScriptEngine.java?rev=758248&r1=758247&r2=758248&view=diff
==============================================================================
--- jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/AbstractScriptEngine.java (original)
+++ jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/AbstractScriptEngine.java Wed Mar 25 13:29:59 2009
@@ -29,7 +29,7 @@
/**
* Constructs a ScriptEngine using an uninitialized
- * SimpleNamespace.
+ * SimpleScriptContext.
*/
public AbstractScriptEngine() {
this.context = new SimpleScriptContext();
@@ -40,6 +40,8 @@
* ENGINE_SCOPE.
*
* @param bindings the Bindings to be used as the ENGINE_SCOPE
+ *
+ * @throws NullPointerException if the parameter is <tt>null</tt>
*/
public AbstractScriptEngine(Bindings bindings){
this();
@@ -86,15 +88,17 @@
/**
- * Retrieves an instance of ScriptContext with namespaces
- * associated with all the level of scopes and the specified
- * namespace associated with SCRIPT_SCOPE.
+ * Returns a {@link SimpleScriptContext} which:
+ * <ul>
+ * <li>uses the specified {@link Bindings} as the {@link ENGINE_SCOPE}</li>
+ * <li>has the same GLOBAL_SCOPE Bindings as the current context</li>
+ * <li>uses the same Reader, Writer and Error Writer as the current context</li>
+ * </ul>
*
- * @param bindings the bindings to be associated with
- * ENGINE_SCOPE
+ * @param bindings the bindings to be associated with ENGINE_SCOPE
* @return an instance of SimpleScriptContext
*
- * @throws NullPointerException if bindings is null
+ * @throws NullPointerException if bindings is <tt>null</tt>
*/
protected ScriptContext getScriptContext(Bindings bindings){
if (bindings == null) {
Modified: jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/Bindings.java
URL: http://svn.apache.org/viewvc/jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/Bindings.java?rev=758248&r1=758247&r2=758248&view=diff
==============================================================================
--- jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/Bindings.java (original)
+++ jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/Bindings.java Wed Mar 25 13:29:59 2009
@@ -21,6 +21,8 @@
import java.util.Map;
/**
+ * A mapping of key/value pairs, all of whose keys are non-empty Strings.
+ *
* See Javadoc of <a href="http://java.sun.com/javase/6/docs/api/javax/script/package-summary.html">Java Scripting API</a>
*/
public interface Bindings extends Map{
@@ -34,7 +36,9 @@
* object
* @param value the object to be stored.
*
- * @throws NullPointerException if key is null
+ * @return the previous value for the mapping, or <tt>null</tt> if there was none.
+ *
+ * @throws NullPointerException if key is <tt>null</tt>
* @throws ClassCastException if the key is not a String
* @throws IllegalArgumentException if the key is an empty string
*/
@@ -48,7 +52,7 @@
* @param toMerge mappings to be stored in the map.
*
* @throws NullPointerException
- * if toMerge map is null or if some key in the map is null.
+ * if toMerge map is <tt>null</tt> or if some key in the map is <tt>null</tt>.
* @throws IllegalArgumentException
* if some key in the map is an empty String
* @throws ClassCastException if some key in the map is not a String
@@ -61,7 +65,7 @@
* @param key key whose presence in this map is to be tested.
* @return <tt>true</tt> if this map contains a mapping for the specified key.
*
- * @throws NullPointerException if key is null
+ * @throws NullPointerException if key is <tt>null</tt>
* @throws ClassCastException if key is not a String
* @throws IllegalArgumentException if key is empty String
*/
@@ -69,9 +73,9 @@
/**
* Returns the value to which this map maps the specified key.
- * Returns null if the map contains no mapping for this key.
- * A return value of null does not necessarily indicate that the map contains no mapping for the key;
- * it's also possible that the map explicitly maps the key to null.
+ * Returns <tt>null</tt> if the map contains no mapping for this key.
+ * A return value of <tt>null</tt> does not necessarily indicate that the map contains no mapping for the key;
+ * it's also possible that the map explicitly maps the key to <tt>null</tt>.
* The containsKey operation may be used to distinguish these two cases.
*
* @param key key whose presence in this map is to be tested.
@@ -79,7 +83,7 @@
* @return the value to which this map maps the specified key,
* or <tt>null</tt> if the map contains no mapping for this key.
*
- * @throws NullPointerException if key is null
+ * @throws NullPointerException if key is <tt>null</tt>
* @throws ClassCastException if key is not a String
* @throws IllegalArgumentException if key is empty String
*/
@@ -90,10 +94,10 @@
* present (optional operation).
*
* Returns the value to which the map previously associated the
- * key, or null if the map contained no mapping for this key. (A
- * null return can also indicate that the map previously
- * associated null with the specified key if the implementation
- * supports null values.) The map will not contain a mapping for
+ * key, or <tt>null</tt> if the map contained no mapping for this key. (A
+ * <tt>null</tt> return can also indicate that the map previously
+ * associated <tt>null</tt> with the specified key if the implementation
+ * supports <tt>null</tt> values.) The map will not contain a mapping for
* the specified key once the call returns.
*
* @param key key of entry to be removed.
@@ -101,7 +105,7 @@
* @return the previous value associated with the key,
* or <tt>null</tt> if the map contained no mapping for this key.
*
- * @throws NullPointerException if key is null
+ * @throws NullPointerException if key is <tt>null</tt>
* @throws ClassCastException if key is not a String
* @throws IllegalArgumentException if key is empty String
*/
Modified: jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/Compilable.java
URL: http://svn.apache.org/viewvc/jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/Compilable.java?rev=758248&r1=758247&r2=758248&view=diff
==============================================================================
--- jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/Compilable.java (original)
+++ jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/Compilable.java Wed Mar 25 13:29:59 2009
@@ -20,37 +20,34 @@
import java.io.Reader;
/**
+ * Optional interface implemented by script engines which
+ * can compile scripts to a form that can be executed repeatedly.
+ * <p>
* See Javadoc of <a href="http://java.sun.com/javase/6/docs/api/javax/script/package-summary.html">Java Scripting API</a>
*/
public interface Compilable {
/**
- * Returns a CompileScript implementation for the given piece
- * of script which is a abstraction for the intermediate code
- * produced by the compilation.
+ * Compiles the script (sourced from the String) for later execution.
*
* @param script the source of the script represented as String
- * @return an implementation of CompileScript which can be used
- * to re-execute intermediate code produced by the
- * compilation of script
- * @throws ScriptException if the compilation fails due to any
- * reason
- * @throws NullPointerException if script is null
+ * @return an implementation of {@link CompiledScript} to be executed later
+ * using one of its eval() methods.
+ *
+ * @throws ScriptException if the compilation fails for any reason
+ * @throws NullPointerException if script is <tt>null</tt>
*/
public CompiledScript compile(String script) throws ScriptException;
/**
- * Retruns a CompileScript implementation for the script
- * obtained using java.io.Reader as the script source.
+ * Compiles the script (source is read from the Reader) for later execution.
*
- * @param reader the reader form which the script source is
- * obtained
- * @return an implementation of CompileScript which can be used
- * to re-execute intermediate code produced by the
- * compilation of script
- * @throws ScriptException if the compilation fails due to any
- * reason
- * @throws NullPointerException if reader is null
+ * @param reader the reader from which the script source is obtained
+ * @return an implementation of {@link CompiledScript} to be executed later
+ * using one of its eval() methods.
+ *
+ * @throws ScriptException if the compilation fails for any reason
+ * @throws NullPointerException if reader is <tt>null</tt>
*/
public CompiledScript compile(Reader reader) throws ScriptException;
}
\ No newline at end of file
Modified: jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/CompiledScript.java
URL: http://svn.apache.org/viewvc/jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/CompiledScript.java?rev=758248&r1=758247&r2=758248&view=diff
==============================================================================
--- jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/CompiledScript.java (original)
+++ jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/CompiledScript.java Wed Mar 25 13:29:59 2009
@@ -26,34 +26,41 @@
}
/**
- * Re-evaluates the pre-compiled script stored using the
- * ENGINE_SCOPE and the GLOBAL_SCOPE of the associated
- * ScriptEngine and returns the resultant object.
+ * Executes the program stored in the CompiledScript object.
+ * The default ScriptContext of the associated ScriptEngine is used.
+ * The effect of calling this method is same as that of
+ * eval(getEngine().getContext()).
*
- * @return the resultant object after the re-evaluation of the
- * script
- * @throws ScriptException if re-evaluation fails due to any
- * reason
+ * @return the resultant object after the evaluation of the
+ * script (may be <tt>null</tt>)
+ * @throws ScriptException if evaluation fails for any reason
*/
public Object eval() throws ScriptException {
return eval(getEngine().getContext());
}
/**
- * Re-evaluates the pre-compiled script using the specified
- * namespace as the SCRIPT_SCOPE and using ENGINE_SCOPE,
- * GLOBAL_SCOPE of the associated ScriptEngine.
+ * Executes the program stored in the CompiledScript object
+ * using the supplied Bindings of attributes as the ENGINE_SCOPE
+ * of the associated ScriptEngine during script execution.
+ *
+ * If bindings is <tt>null</tt>, then the effect of calling this method is
+ * same as that of eval(getEngine().getContext()).
+ * <br/>
+ * The GLOBAL_SCOPE Bindings, Reader and Writer associated
+ * with the default ScriptContext of the associated ScriptEngine
+ * are used.
*
- * @param bindings the namespace to be used as the SCRIPT_SCOPE
- * @return resultant object after the re-evaluation
- * @throws ScriptException if the re-evaluation fails due to any
- * reason
+ * @param bindings the bindings to be used as the ENGINE_SCOPE
+ * @return resultant object after the re-evaluation (may be <tt>null</tt>)
+ * @throws ScriptException if the evaluation fails for any reason
*/
public Object eval(Bindings bindings) throws ScriptException{
ScriptContext context;
if (bindings == null) {
context = getEngine().getContext();
} else {
+ // same code as ((AbstractScriptEngine) getEngine()).getScriptContext(bindings);
context = new SimpleScriptContext();
context.setBindings(bindings, ScriptContext.ENGINE_SCOPE);
ScriptContext oldContext = getEngine().getContext();
@@ -66,15 +73,14 @@
}
/**
- * Re-evaluates the recompiled script using the specified
- * ScriptContext.
+ * Evaluates the compiled script using the specified
+ * {@link ScriptContext}.
*
- * @param context A ScriptContext to be used in the re-evalution
+ * @param context A ScriptContext to be used in the evalution
* of the script
- * @return resultant object after the re-evaluation
- * @throws ScriptException if the re-evaluation fails due to any
- * reason
- * @throws NullPointerException if context is null
+ * @return resultant object after the evaluation (may be <tt>null</tt>)
+ * @throws ScriptException if the evaluation fails for any reason
+ * @throws NullPointerException if context is <tt>null</tt>
*/
public abstract Object eval(ScriptContext context) throws ScriptException;
Modified: jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/Invocable.java
URL: http://svn.apache.org/viewvc/jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/Invocable.java?rev=758248&r1=758247&r2=758248&view=diff
==============================================================================
--- jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/Invocable.java (original)
+++ jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/Invocable.java Wed Mar 25 13:29:59 2009
@@ -20,6 +20,10 @@
package javax.script;
/**
+ * Optional interface implemented by {@link ScriptEngine}s which
+ * allow the invocation of procedures in scripts that have previously
+ * been executed.
+ * <p>
* See Javadoc of <a href="http://java.sun.com/javase/6/docs/api/javax/script/package-summary.html">Java Scripting API</a>
*/
public interface Invocable {
@@ -35,7 +39,7 @@
* fails
* @throws NoSuchMethodException if method with given name or matching
* argument types cannot be found
- * @throws NullPointerException - if the method name is null.
+ * @throws NullPointerException if the method name is <tt>null</tt>.
*/
public Object invokeFunction(String name, Object[] args)
throws ScriptException, NoSuchMethodException;
@@ -49,20 +53,19 @@
* @param args arguments set for the procedure
* @return resultant object after the execution of the
* procedure
- * @throws ScriptException if the invocation of the procedure
- * fails
+ * @throws ScriptException if the invocation of the procedure fails
* @throws NoSuchMethodException if a method with given name or matching
* argument types cannot be found
- * @throws NullPointerException - if the method name is null.
- * @throws IllegalArgumentException - if the specified thiz
- * is null or the specified Object is does not represent a scripting object.
+ * @throws NullPointerException if the method name is <tt>null</tt>.
+ * @throws IllegalArgumentException if the specified <tt>thiz</tt>
+ * is <tt>null</tt> or the specified Object is does not represent a scripting object.
*/
public Object invokeMethod(Object thiz, String name, Object[] args) throws
ScriptException, NoSuchMethodException;
/**
- * Retrieves an instance of java class whose methods are
- * impleemented using procedures in script which are in the
+ * Retrieves an instance of a java class whose methods are
+ * implemented using procedures in script which are in the
* intermediate code repository in the underlying interpreter.
*
* @param clasz an interface which the returned class must
@@ -70,20 +73,23 @@
* @return an instance of the class which implements the specified
* interface
* @throws IllegalArgumentException
- * if the specified Class object is null or is not an interface
+ * if the specified Class object is <tt>null</tt> or is not an interface
*/
public Object getInterface(Class clasz);
/**
+ * Retrieves an instance of a java class whose methods are
+ * implemented using procedures in script which are in the
+ * intermediate code repository in the underlying interpreter.
*
* @param thiz The scripting object whose member functions are used to implement the methods of the interface.
* @param clasz The Class object of the interface to return.
* @return An instance of requested interface.
- * Will be null if the requested interface is unavailable,
+ * Will be <tt>null</tt> if the requested interface is unavailable,
* i.e. if compiled methods in the ScriptEngine cannot be found matching the ones in the requested interface.
* @throws IllegalArgumentException
- * if the specified Class object is null or is not an interface,
- * or if the specified Object is null or does not represent a scripting object.
+ * if the specified Class object is <tt>null</tt> or is not an interface,
+ * or if the specified Object is <tt>null</tt> or does not represent a scripting object.
*/
public Object getInterface(Object thiz, Class clasz);
}
Modified: jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/ScriptContext.java
URL: http://svn.apache.org/viewvc/jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/ScriptContext.java?rev=758248&r1=758247&r2=758248&view=diff
==============================================================================
--- jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/ScriptContext.java (original)
+++ jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/ScriptContext.java Wed Mar 25 13:29:59 2009
@@ -28,28 +28,28 @@
*/
public interface ScriptContext {
- /** defines an integer for the level of scope, ENGINE_SCOPE */
+ /** defines an integer for the scope, ENGINE_SCOPE */
public static final int ENGINE_SCOPE = 100;
- /** defines an integer for the level of scope, GLOBAL_SCOPE */
+ /** defines an integer for the scope, GLOBAL_SCOPE */
public static final int GLOBAL_SCOPE = 200;
/**
* Retrieves the value of the getAttribute(String, int) for the
* lowest scope in which it returns a non-null value. Returns
- * null if there is no such value exists in any scope.
+ * <tt>null</tt> if there is no such value exists in any scope.
*
*
* @param name the name of the attribute
* @return the associated value with the specified name
* @throws IllegalArgumentException if the name is empty
- * @throws NullPointerException if the name is null
+ * @throws NullPointerException if the name is <tt>null</tt>
*/
public Object getAttribute(String name);
/**
* Retrieves the value of an attribute in the specified scope.
- * Returns null if the no such value exists in the specified
+ * Returns <tt>null</tt> if the no such value exists in the specified
* scope.
*
* @param name the name of the attribute
@@ -57,7 +57,7 @@
* @return the associated value for the specified name
* @throws IllegalArgumentException if the name is empty or the
* scope is invalid
- * @throws NullPointerException if the name is null
+ * @throws NullPointerException if the name is <tt>null</tt>
*/
public Object getAttribute(String name, int scope);
@@ -68,17 +68,17 @@
* @param name the name of attribute
* @return the value corresponding to lowest value of the scope
* or -1 if no associated value exist in any scope
- * @throws NullPointerException if name is null.
+ * @throws NullPointerException if name is <tt>null</tt>.
* @throws IllegalArgumentException if name is empty.
*/
public int getAttributesScope(String name);
/**
- * Retrieves the Bindings instance associated with the gieve
- * scope. Returns null if no namespace is assoicited with
- * specified level of scope.
+ * Retrieves the Bindings instance associated with the given
+ * scope. Returns <tt>null</tt> if no Bindings is associated with
+ * specified scope.
*
- * @param scope the level of the scope
+ * @param scope the scope
* @return the Bindings associated with the specified scope
* @throws IllegalArgumentException
* If no Bindings is defined for the specified scope value in ScriptContext of this type.
@@ -94,7 +94,8 @@
public Writer getWriter();
/**
- * Returns the Writer to be used to display error output.
+ * Returns the Writer to be used to display error output.
+ *
* @return the error writer
*/
public Writer getErrorWriter();
@@ -128,15 +129,15 @@
public void setReader(Reader reader);
/**
- * Removes the given attribute form the specified scope. Returns
- * the removed object or null if no value is associated with the
- * specified key in specified level of scope.
+ * Removes the given attribute from the specified scope. Returns
+ * the removed object or <tt>null</tt> if no value is associated with the
+ * specified key in the specified scope.
*
* @param name the name of the attribute
- * @param scope the level of scope which inherit the attribute
+ * @param scope the scope from which to remove the attribute
* @return previous value associated with specified name
*
- * @throws NullPointerException if the name is null
+ * @throws NullPointerException if the name is <tt>null</tt>
* @throws IllegalArgumentException if the name is empty or if the
* scope is invalid
*/
@@ -148,10 +149,10 @@
*
* @param key the name of the attribute
* @param value the value of the attribute
- * @param scope the level of the scope
- * @throws IllegalArgumentException if the name is null or the
+ * @param scope the scope
+ * @throws IllegalArgumentException if the name is <tt>null</tt> or the
* scope is invalid
- * @throws NullPointerException if the name is null.
+ * @throws NullPointerException if the name is <tt>null</tt>.
*/
public void setAttribute(String key,Object value,int scope);
@@ -159,16 +160,16 @@
* Associates the specified Bindings with the specified scope.
*
* @param bindings the Bindings to be associated with the
- * specified level of scope
+ * specified scope
* @param scope the scope
* @throws IllegalArgumentException if the scope is invalid
- * @throws NullPointerException if the bindings is null and the
+ * @throws NullPointerException if the bindings is <tt>null</tt> and the
* scope is ScriptEngine.ENGINE_SCOPE
*/
public void setBindings(Bindings bindings,int scope);
/**
- * Returns immutable List of all the valid values for scope in the ScriptContext.
+ * Returns an immutable List of all the valid values for scope in the ScriptContext.
*
* @return the list
*/
Modified: jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/ScriptEngine.java
URL: http://svn.apache.org/viewvc/jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/ScriptEngine.java?rev=758248&r1=758247&r2=758248&view=diff
==============================================================================
--- jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/ScriptEngine.java (original)
+++ jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/ScriptEngine.java Wed Mar 25 13:29:59 2009
@@ -69,7 +69,7 @@
public static final String NAME = "javax.script.name";
/**
- * Retrieves an uninitailized Bindings which can be used as the scope of
+ * Retrieves an uninitialized Bindings which can be used as the scope of
* the ScriptEngine.
*
* @return a Bindings which can be used to replace the state
@@ -78,80 +78,84 @@
public Bindings createBindings();
/**
- * Evaluates a piece of script obtained using the specified
- * reader as the script source. Returns null for non-returning
- * scripts.
+ * Evaluates a script obtained using the specified
+ * reader as the script source.
+ * Returns <tt>null</tt> for scripts that don't return a value.
*
* @param reader the source of the script
* @return the value of the evaluated script
* @throws ScriptException if an error occurs
- * @throws NullPointerException if argument is null
+ * @throws NullPointerException if argument is <tt>null</tt>
*/
public Object eval(Reader reader) throws ScriptException;
/**
- * Evaluates a piece of scripts obtained using a reader as the
+ * Evaluates a script obtained using a reader as the
* script source and using the specified namespace as the
- * SCRIPT_SCOPE. Returns null for non-returning scripts.
+ * ENGINE_SCOPE.
+ * Returns <tt>null</tt> for scripts that don't return a value.
*
* @param reader the script source used to obtained the script
- * @param bindings the namespace to be used as SCRIPT_SCOPE
+ * @param bindings the bindings to be used as ENGINE_SCOPE
* @return the value of the evaluated script
* @throws ScriptException if an error occurs
- * @throws NullPointerException if either argument is null
+ * @throws NullPointerException if either argument is <tt>null</tt>
*/
public Object eval(Reader reader, Bindings bindings)
throws ScriptException;
/**
* Evaluates a script obtained using the specified reader as the
- * script source and using the namespaces in the specifed
- * ScriptContext. Returns null for non-returning scripts
+ * script source and using the bindings in the specifed
+ * ScriptContext.
+ * Returns <tt>null</tt> for scripts that don't return a value.
*
* @param reader the script source
- * @param context the context contianing different namespace for
+ * @param context the context contianing different bindings for
* script evaluation
* @return the value of the evaluated script
* @throws ScriptException if an error occurs
- * @throws NullPointerException if either argument is null
+ * @throws NullPointerException if either argument is <tt>null</tt>
*/
public Object eval(Reader reader, ScriptContext context)
throws ScriptException;
/**
- * Evaluates a piece of script and returns the resultant object.
- * Returns null for non-returning scripts.
+ * Evaluates a script contained in a String and returns the resultant object.
+ * Returns <tt>null</tt> for scripts that don't return a value.
*
* @param script the String representation of the script
* @return the value of the evaluated script
* @throws ScriptException if an error occurs
- * @throws NullPointerException if argument is null
+ * @throws NullPointerException if argument is <tt>null</tt>
*/
public Object eval(String script) throws ScriptException;
/**
* Evaluates a piece of script using the specified namespace as
- * the SCRIPT_SCOPE. Retruns null for non-returning scripts.
+ * the ENGINE_SCOPE.
+ * Returns <tt>null</tt> for scripts that don't return a value.
*
* @param script the String representation of the script
- * @param bindings the namespace to be used as the SCRIPT_SCOPE
+ * @param bindings the bindings to be used as the ENGINE_SCOPE
* @return the value of the evaluated script
* @throws ScriptException if an error occurs
- * @throws NullPointerException if either argument is null
+ * @throws NullPointerException if either argument is <tt>null</tt>
*/
public Object eval(String script ,Bindings bindings)
throws ScriptException;
/**
- * Evaluates a script using the namespaces in the specifed
- * ScriptContext. Return null for non-returning scripts.
+ * Evaluates a script using the bindings in the specifed
+ * ScriptContext.
+ * Returns <tt>null</tt> for scripts that don't return a value.
*
* @param script the String representation of the script
- * @param context tbe ScriptContext containing namespaces for the
+ * @param context tbe ScriptContext containing bindings for the
* script evaluation
* @return the value of the evaluated script
* @throws ScriptException if an error occurs
- * @throws NullPointerException if either argument is null
+ * @throws NullPointerException if either argument is <tt>null</tt>
*/
public Object eval(String script, ScriptContext context)
throws ScriptException;
@@ -163,7 +167,7 @@
* @param key the key associated with value.
* @return an object value which is associated with the key
* @throws IllegalArgumentException if argument is empty
- * @throws NullPointerException if argument is null
+ * @throws NullPointerException if argument is <tt>null</tt>
*/
public Object get(String key);
@@ -176,48 +180,45 @@
/**
* Retrieves a reference to the associated bindings for the
- * specified level of scope.
+ * specified scope.
*
* Possible scopes are:
*
* GLOBAL_SCOPE :
* if the ScriptEngine was created by ScriptingEngineManager
- * then GLOBAL_SCOPE of it is returned (or null if there is no
+ * then GLOBAL_SCOPE of it is returned (or <tt>null</tt> if there is no
* GLOBAL_SCOPE stored in the ScriptEngine).
*
* ENGINE_SCOPE :
* the set of key-value pairs stored in the ScriptEngine is
* returned.
*
- * @param scope the specified level of scope
- * @return associated bindings for the specified level of scope
+ * @param scope the specified scope
+ * @return associated bindings for the specified scope
* @throws IllegalArgumentException if the scope is invalid
*/
public Bindings getBindings(int scope);
/**
- * Associates a key and a value in the ScriptEngine namespace.
+ * Associates a key and a value in the ScriptEngine ENGINE_SCOPE bindings.
*
* @param key the specified key associated with the value
* @param value value which is to be associated with the
* specified key
* @throws IllegalArgumentException if the key is empty
- * @throws NullPointerException if key is null
+ * @throws NullPointerException if key is <tt>null</tt>
*/
public void put(String key, Object value);
/**
- * Associates the specified namespace with the specified level of
- * scope.
+ * Associates the specified bindings with the specified scope.
*
- * @param bindings namespace to be associated with the specified
- * level of scope
- * @param scope level of scope for which the namespace should
- * be associated with
+ * @param bindings bindings to be associated with the specified scope
+ * @param scope scope which the bindings should be associated with
* @throws IllegalArgumentException
* if the scope is invalid
* @throws NullPointerException
- * if the bindings is null and the scope is ScriptContext.ENGINE_SCOPE
+ * if the bindings is <tt>null</tt> and the scope is ScriptContext.ENGINE_SCOPE
*/
public void setBindings(Bindings bindings, int scope);
@@ -235,7 +236,7 @@
*
* @param context
* scriptContext that will replace the default ScriptContext in the ScriptEngine.
- * @throws NullPointerException if the context is null
+ * @throws NullPointerException if the context is <tt>null</tt>
*/
public void setContext(ScriptContext context);
Modified: jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/ScriptEngineFactory.java
URL: http://svn.apache.org/viewvc/jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/ScriptEngineFactory.java?rev=758248&r1=758247&r2=758248&view=diff
==============================================================================
--- jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/ScriptEngineFactory.java (original)
+++ jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/ScriptEngineFactory.java Wed Mar 25 13:29:59 2009
@@ -92,7 +92,7 @@
/**
* Retrieves an associated value for the specified key. Returns
- * null if the ScriptEngine does not have an associated value for
+ * <tt>null</tt> if the ScriptEngine does not have an associated value for
* the key.
*
* @return associated value for the specified key
@@ -108,7 +108,7 @@
* String method, String[] args) {
* String ret = objectName;
* ret += "." + method + "(";
- * for (int i = 0; i < args.length; i++) {
+ * for (int i = 0; i < args.length; i++) {
* ret += args[i];
* if (i == args.length - 1) {
* ret += ")";
@@ -149,15 +149,17 @@
* engine might be:
* <pre>
* public String getProgram(String... statements) {
- * $retval = "<?\n";
+ * $retval = "<?\n";
* int len = statements.length;
- * for (int i = 0; i < len; i++) {
+ * for (int i = 0; i < len; i++) {
* $retval += statements[i] + ";\n";
* }
- * $retval += "?>";
+ * $retval += "?>";
* }
* </pre>
- * @param statements
+ *
+ * @param statements the statements to be executed,
+ * e.g. as returned by the {@link #getMethodCallSyntax} or {@link #getOutputStatement} methods
* @return The Program
*/
public String getProgram(String[] statements);
Modified: jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/ScriptEngineManager.java
URL: http://svn.apache.org/viewvc/jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/ScriptEngineManager.java?rev=758248&r1=758247&r2=758248&view=diff
==============================================================================
--- jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/ScriptEngineManager.java (original)
+++ jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/ScriptEngineManager.java Wed Mar 25 13:29:59 2009
@@ -33,37 +33,43 @@
*/
public class ScriptEngineManager {
- /** Stores all instances of classes which implements
+ /**
+ * Stores all instances of classes which implement
* ScriptEngineFactory which are found in resources
* META-INF/services/javax.script.ScriptEngineFactory
*/
private final HashSet engineSpis = new HashSet();
/**
- * Stores language names with an associated
- * ScriptEngineFactory
+ * Maps language names to the associated ScriptEngineFactory
*/
private final HashMap nameAssociations = new HashMap();
/**
- * Stores file extensions with an associated
- * ScriptEngineFactory
+ * Maps file extensions to the associated ScriptEngineFactory
*/
- private final HashMap extensionAssocitions = new HashMap();
+ private final HashMap extensionAssociations = new HashMap();
- /** Stores MIME types with an associated ScriptEngineFactory */
+ /** Maps MIME types to the associated ScriptEngineFactory */
private final HashMap mimeTypeAssociations = new HashMap();
- /** Stores the namespace associated with GLOBAL_SCOPE */
+ /** Stores the bindings associated with GLOBAL_SCOPE */
private Bindings globalscope = new SimpleBindings();
/**
- * Constructs ScriptEngineManager and initializes it.
+ * Constructs a ScriptEngineManager and
+ * initializes it using the current context classloader.
*/
public ScriptEngineManager() {
this(Thread.currentThread().getContextClassLoader());
}
+ /**
+ * Constructs a ScriptEngineManager and
+ * initializes it using the specified classloader.
+ *
+ * @param loader the classloader to use (may be <tt>null</tt>)
+ */
public ScriptEngineManager(ClassLoader loader) {
Iterator iterator = ServiceRegistry.lookupProviders(ScriptEngineFactory.class, loader);
@@ -77,14 +83,14 @@
engineSpis.add(factory);
List data = factory.getNames();
- // gets all descriptinve names for Scripting Engine
+ // gets all descriptive names for Scripting Engine
for (int i=0; i<data.size(); i++) {
nameAssociations.put(data.get(i), factory);
}
// gets all supported extensions
data = factory.getExtensions();
for (int i=0; i<data.size(); i++) {
- extensionAssocitions.put(data.get(i), factory);
+ extensionAssociations.put(data.get(i), factory);
}
// gets all supported MIME types
data = factory.getMimeTypes();
@@ -124,7 +130,7 @@
/**
* Retrieves a new instance of a ScriptingEngine for the
- * specified extension of a scirpt file. Returns null if no
+ * specified extension of a scirpt file. Returns <tt>null</tt> if no
* suitable ScriptingEngine is found.
*
* @param extension the specified extension of a script file
@@ -136,7 +142,7 @@
ScriptEngine engine = null;
ScriptEngineFactory factory =
- (ScriptEngineFactory) extensionAssocitions.get(extension);
+ (ScriptEngineFactory) extensionAssociations.get(extension);
if (factory != null) {
// gets a new instance of the Scripting Engine
@@ -150,7 +156,7 @@
/**
* Retrieves new instance the ScriptingEngine for a specifed MIME
- * type. Returns null if no suitable ScriptingEngine is found.
+ * type. Returns <tt>null</tt> if no suitable ScriptingEngine is found.
*
* @param mimeType the specified MIME type
* @return a new instance of a ScriptingEngine which supports the
@@ -174,7 +180,7 @@
/**
* Retrieves a new instance of a ScriptEngine the specified
- * descriptieve name. Returns null if no suitable ScriptEngine is
+ * descriptieve name. Returns <tt>null</tt> if no suitable ScriptEngine is
* found.
*
* @param name the descriptive name
@@ -251,7 +257,7 @@
* the specified extension
*/
public void registerEngineExtension(String extension, ScriptEngineFactory factory){
- extensionAssocitions.put(extension, factory);
+ extensionAssociations.put(extension, factory);
}
/**
@@ -281,10 +287,10 @@
}
/**
- * Sets the GLOBAL_SCOPE value to the specified namespace.
+ * Sets the GLOBAL_SCOPE value to the specified bindings.
*
- * @param bindings the namespace to be stored in GLOBAL_SCOPE
- * @throws IllegalArgumentException if bindings is null
+ * @param bindings the bindings to be stored in GLOBAL_SCOPE
+ * @throws IllegalArgumentException if bindings is <tt>null</tt>
*/
public void setBindings(Bindings bindings){
if (bindings == null){
Modified: jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/SimpleBindings.java
URL: http://svn.apache.org/viewvc/jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/SimpleBindings.java?rev=758248&r1=758247&r2=758248&view=diff
==============================================================================
--- jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/SimpleBindings.java (original)
+++ jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/SimpleBindings.java Wed Mar 25 13:29:59 2009
@@ -36,18 +36,18 @@
private final Map map;
/**
- * Constructs a SimpleNamespace.
+ * Constructs a SimpleBindings.
*/
public SimpleBindings(){
map = new HashMap();
}
/**
- * Constructs a SimpleNamespace and initializes it using a
+ * Constructs a SimpleBindings and initializes it using a
* specified map.
*
* @param map a map which is used to initialize the
- * SimpleNamespace
+ * SimpleBindings
*/
public SimpleBindings(Map map){
this.map = map;
@@ -57,12 +57,14 @@
/**
* Check the conditions which keys need to satisfy:
- * - String
- * - non-null
- * - non-Empty
+ * <br/>
+ * + String<br/>
+ * + non-null<br/>
+ * + non-empty<br/>
+ *
* @param key key to be checked
*
- * @throws NullPointerException if key is null
+ * @throws NullPointerException if key is <tt>null</tt>
* @throws ClassCastException if key is not String
* @throws llegalArgumentException if key is empty String
*/
@@ -92,7 +94,10 @@
* @param key the String value which uniquely identifies the
* object
* @param value the object to be stored.
- * @throws NullPointerException if the key is null
+ *
+ * @return the previous value for the mapping (may be <tt>null</tt>), or <tt>null</tt> if there was none.
+ *
+ * @throws NullPointerException if the key is <tt>null</tt>
* @throws IllegalArgumentException if the key is empty
*/
public Object put(String key, Object value) {
Modified: jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/SimpleScriptContext.java
URL: http://svn.apache.org/viewvc/jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/SimpleScriptContext.java?rev=758248&r1=758247&r2=758248&view=diff
==============================================================================
--- jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/SimpleScriptContext.java (original)
+++ jakarta/bsf/trunk/bsf3/bsf-api/src/main/java/javax/script/SimpleScriptContext.java Wed Mar 25 13:29:59 2009
@@ -34,7 +34,7 @@
/**
* This is the scope bindings for GLOBAL_SCOPE.
- * By default, a null value (which means no global scope) is used.
+ * By default, a <tt>null</tt> value (which means no global scope) is used.
* */
protected Bindings globalScope = null;
@@ -53,11 +53,16 @@
/** The writer to be used for displaying error output from scripts */
protected Writer errorWriter;
+ /** Immutable list of scopes returned by {@link #getScopes()}*/
private static final List SCOPES =
Collections.unmodifiableList(
Arrays.asList(new Integer[] { new Integer(ENGINE_SCOPE), new Integer(GLOBAL_SCOPE) })
);
+ /**
+ * Create a new instance,
+ * setting the Reader and Writers from the corresponding System streams.
+ */
public SimpleScriptContext() {
reader = new InputStreamReader(System.in);
writer = new PrintWriter(System.out, true);
@@ -65,8 +70,10 @@
}
/**
- * Check if name is null or empty string
+ * Check if name is <tt>null</tt> or empty string
* @param name to be checked
+ * @throws NullPointerException if the name is <tt>null</tt>
+ * @throws IllegalArgumentException if the name is the empty string
*/
private void checkName(String name){
if (name == null){
@@ -171,17 +178,17 @@
}
/** {@inheritDoc} */
- public void setBindings(Bindings namespace, int scope) {
+ public void setBindings(Bindings bindings, int scope) {
switch (scope) {
case ENGINE_SCOPE:
- if (namespace == null) {
+ if (bindings == null) {
throw new NullPointerException("binding is null for ENGINE_SCOPE scope");
}
- engineScope = namespace;
+ engineScope = bindings;
break;
case GLOBAL_SCOPE:
- globalScope = namespace;
+ globalScope = bindings;
break;
default:
throw new IllegalArgumentException("invalid scope");
---------------------------------------------------------------------
To unsubscribe, e-mail: bsf-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: bsf-dev-help@jakarta.apache.org