001: /*
002: * %W% %E% %U%
003: *
004: * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
005: * SUN PROPRIETARY/CONFIDENTAIL. Use is subject to license terms.
006: */
007:
008: package javax.script;
009:
010: import java.util.List;
011: import java.io.Writer;
012: import java.io.Reader;
013:
014: /**
015: * The interface whose implementing classes are used to connect Script Engines
016: * with objects, such as scoped Bindings, in hosting applications. Each scope is a set
017: * of named attributes whose values can be set and retrieved using the
018: * <code>ScriptContext</code> methods. ScriptContexts also expose Readers and Writers
019: * that can be used by the ScriptEngines for input and output.
020: *
021: * @author Mike Grogan
022: * @version 1.0
023: * @since 1.6
024: */
025: public interface ScriptContext {
026:
027: /**
028: * EngineScope attributes are visible during the lifetime of a single
029: * <code>ScriptEngine</code> and a set of attributes is maintained for each
030: * engine.
031: */
032: public static final int ENGINE_SCOPE = 100;
033:
034: /**
035: * GlobalScope attributes are visible to all engines created by same ScriptEngineFactory.
036: */
037: public static final int GLOBAL_SCOPE = 200;
038:
039: /**
040: * Associates a <code>Bindings</code> instance with a particular scope in this
041: * <code>ScriptContext</code>. Calls to the <code>getAttribute</code> and
042: * <code>setAttribute</code> methods must map to the <code>put</code> and
043: * <code>get</code> methods of the <code>Bindings</code> for the specified scope.
044: *
045: * @param bindings The <code>Bindings</code> to associate with the given scope
046: * @param scope The scope
047: *
048: * @throws <code>IllegalArgumentException</code> If no <code>Bindings</code> is defined for the
049: * specified scope value in ScriptContexts of this type.
050: * @throws <code>NullPointerException</code> if value of scope is <code>ENGINE_SCOPE</code> and
051: * the specified <code>Bindings</code> is null.
052: *
053: */
054: public void setBindings(Bindings bindings, int scope);
055:
056: /**
057: * Gets the <code>Bindings</code> associated with the given scope in this
058: * <code>ScriptContext</code>.
059: *
060: * @return The associated <code>Bindings</code>. Returns <code>null</code> if it has not
061: * been set.
062: *
063: * @throws IllegalArgumentException If no <code>Bindings</code> is defined for the
064: * specified scope value in <code>ScriptContext</code> of this type.
065: */
066: public Bindings getBindings(int scope);
067:
068: /**
069: * Sets the value of an attribute in a given scope.
070: *
071: * @param name The name of the attribute to set.
072: * @param scope The scope in which to set the attribute
073: *
074: * @throws <code>IllegalArgumentException</code> if the scope
075: * is invalid.
076: * @throws <code>NullPointerException</code> if the name is null.
077: * @throws <code>ClassCastException</code> if the name is not a String.
078: */
079: public void setAttribute(String name, Object value, int scope);
080:
081: /**
082: * Gets the value of an attribute in a given scope.
083: *
084: * @param name The name of the attribute to retrieve.
085: * @param scope The scope in which to retrieve the attribute.
086: * @return The value of the attribute. Returns <code>null</code> is the name
087: * does not exist in the given scope.
088: *
089: * @throws <code>IllegalArgumentException</code> if the value of scope is invalid.
090: * @throws <code>NullPointerException</code> if the name is null.
091: *
092: */
093: public Object getAttribute(String name, int scope);
094:
095: /**
096: * Remove an attribute in a given scope.
097: *
098: * @param name The name of the attribute to remove
099: * @param scope The scope in which to remove the attribute
100: *
101: * @return The removed value.
102: * @throws <code>IllegalArgumentException</code> if the scope is invalid.
103: * @throws <code>NullPointerException</code> if the name is null.
104: */
105: public Object removeAttribute(String name, int scope);
106:
107: /**
108: * Retrieves the value of the attribute with the given name in
109: * the scope occurring earliest in the search order. The order
110: * is determined by the numeric value of the scope parameter (lowest
111: * scope values first.)
112: *
113: * @param name The name of the the attribute to retrieve.
114: * @return The value of the attribute in the lowest scope for
115: * which an attribute with the given name is defined. Returns
116: * null if no attribute with the name exists in any scope.
117: * @throws <code>NullPointerException</code> if the name is null.
118: */
119: public Object getAttribute(String name);
120:
121: /**
122: * Get the lowest scope in which an attribute is defined.
123: * @param name Name of the attribute
124: * .
125: * @return The lowest scope. Returns -1 if no attribute with the given
126: * name is defined in any scope.
127: */
128: public int getAttributesScope(String name);
129:
130: /**
131: * Returns the <code>Writer</code> for scripts to use when displaying output.
132: *
133: * @return The <code>Writer</code>.
134: */
135: public Writer getWriter();
136:
137: /**
138: * Returns the <code>Writer</code> used to display error output.
139: *
140: * @return The <code>Writer</code>
141: */
142: public Writer getErrorWriter();
143:
144: /**
145: * Sets the <code>Writer</code> for scripts to use when displaying output.
146: *
147: * @param writer The new <code>Writer</code>.
148: */
149: public void setWriter(Writer writer);
150:
151: /**
152: * Sets the <code>Writer</code> used to display error output.
153: *
154: * @param writer The <code>Writer</code>.
155: */
156: public void setErrorWriter(Writer writer);
157:
158: /**
159: * Returns a <code>Reader</code> to be used by the script to read
160: * input.
161: *
162: * @return The <code>Reader</code>.
163: */
164: public Reader getReader();
165:
166: /**
167: * Sets the <code>Reader</code> for scripts to read input
168: * .
169: * @param reader The new <code>Reader</code>.
170: */
171: public void setReader(Reader reader);
172:
173: /**
174: * Returns immutable <code>List</code> of all the valid values for
175: * scope in the ScriptContext.
176: *
177: * @return list of scope values
178: */
179: public List<Integer> getScopes();
180: }
|