1 /* 2 * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.script; 27 import java.util.List; 28 import java.io.Writer; 29 import java.io.Reader; 30 31 /** 32 * The interface whose implementing classes are used to connect Script Engines 33 * with objects, such as scoped Bindings, in hosting applications. Each scope is a set 34 * of named attributes whose values can be set and retrieved using the 35 * <code>ScriptContext</code> methods. ScriptContexts also expose Readers and Writers 36 * that can be used by the ScriptEngines for input and output. 37 * 38 * @author Mike Grogan 39 * @since 1.6 40 */ 41 public interface ScriptContext { 42 43 44 /** 45 * EngineScope attributes are visible during the lifetime of a single 46 * <code>ScriptEngine</code> and a set of attributes is maintained for each 47 * engine. 48 */ 49 public static final int ENGINE_SCOPE = 100; 50 51 /** 52 * GlobalScope attributes are visible to all engines created by same ScriptEngineFactory. 53 */ 54 public static final int GLOBAL_SCOPE = 200; 55 56 57 /** 58 * Associates a <code>Bindings</code> instance with a particular scope in this 59 * <code>ScriptContext</code>. Calls to the <code>getAttribute</code> and 60 * <code>setAttribute</code> methods must map to the <code>get</code> and 61 * <code>put</code> methods of the <code>Bindings</code> for the specified scope. 62 * 63 * @param bindings The <code>Bindings</code> to associate with the given scope 64 * @param scope The scope 65 * 66 * @throws IllegalArgumentException If no <code>Bindings</code> is defined for the 67 * specified scope value in ScriptContexts of this type. 68 * @throws NullPointerException if value of scope is <code>ENGINE_SCOPE</code> and 69 * the specified <code>Bindings</code> is null. 70 * 71 */ setBindings(Bindings bindings, int scope)72 public void setBindings(Bindings bindings, int scope); 73 74 /** 75 * Gets the <code>Bindings</code> associated with the given scope in this 76 * <code>ScriptContext</code>. 77 * 78 * @return The associated <code>Bindings</code>. Returns <code>null</code> if it has not 79 * been set. 80 * 81 * @param scope The scope 82 * @throws IllegalArgumentException If no <code>Bindings</code> is defined for the 83 * specified scope value in <code>ScriptContext</code> of this type. 84 */ getBindings(int scope)85 public Bindings getBindings(int scope); 86 87 /** 88 * Sets the value of an attribute in a given scope. If the scope is <code>GLOBAL_SCOPE</code> 89 * and no Bindings is set for <code>GLOBAL_SCOPE</code>, then setAttribute call is a no-op. 90 * 91 * @param name The name of the attribute to set 92 * @param value The value of the attribute 93 * @param scope The scope in which to set the attribute 94 * 95 * @throws IllegalArgumentException 96 * if the name is empty or if the scope is invalid. 97 * @throws NullPointerException if the name is null. 98 */ setAttribute(String name, Object value, int scope)99 public void setAttribute(String name, Object value, int scope); 100 101 /** 102 * Gets the value of an attribute in a given scope. 103 * 104 * @param name The name of the attribute to retrieve. 105 * @param scope The scope in which to retrieve the attribute. 106 * @return The value of the attribute. Returns <code>null</code> is the name 107 * does not exist in the given scope. 108 * 109 * @throws IllegalArgumentException 110 * if the name is empty or if the value of scope is invalid. 111 * @throws NullPointerException if the name is null. 112 */ getAttribute(String name, int scope)113 public Object getAttribute(String name, int scope); 114 115 /** 116 * Remove an attribute in a given scope. 117 * 118 * @param name The name of the attribute to remove 119 * @param scope The scope in which to remove the attribute 120 * 121 * @return The removed value. 122 * @throws IllegalArgumentException 123 * if the name is empty or if the scope is invalid. 124 * @throws NullPointerException if the name is null. 125 */ removeAttribute(String name, int scope)126 public Object removeAttribute(String name, int scope); 127 128 /** 129 * Retrieves the value of the attribute with the given name in 130 * the scope occurring earliest in the search order. The order 131 * is determined by the numeric value of the scope parameter (lowest 132 * scope values first.) 133 * 134 * @param name The name of the attribute to retrieve. 135 * @return The value of the attribute in the lowest scope for 136 * which an attribute with the given name is defined. Returns 137 * null if no attribute with the name exists in any scope. 138 * @throws NullPointerException if the name is null. 139 * @throws IllegalArgumentException if the name is empty. 140 */ getAttribute(String name)141 public Object getAttribute(String name); 142 143 144 /** 145 * Get the lowest scope in which an attribute is defined. 146 * @param name Name of the attribute 147 * . 148 * @return The lowest scope. Returns -1 if no attribute with the given 149 * name is defined in any scope. 150 * @throws NullPointerException if name is null. 151 * @throws IllegalArgumentException if name is empty. 152 */ getAttributesScope(String name)153 public int getAttributesScope(String name); 154 155 /** 156 * Returns the <code>Writer</code> for scripts to use when displaying output. 157 * 158 * @return The <code>Writer</code>. 159 */ getWriter()160 public Writer getWriter(); 161 162 163 /** 164 * Returns the <code>Writer</code> used to display error output. 165 * 166 * @return The <code>Writer</code> 167 */ getErrorWriter()168 public Writer getErrorWriter(); 169 170 /** 171 * Sets the <code>Writer</code> for scripts to use when displaying output. 172 * 173 * @param writer The new <code>Writer</code>. 174 */ setWriter(Writer writer)175 public void setWriter(Writer writer); 176 177 178 /** 179 * Sets the <code>Writer</code> used to display error output. 180 * 181 * @param writer The <code>Writer</code>. 182 */ setErrorWriter(Writer writer)183 public void setErrorWriter(Writer writer); 184 185 /** 186 * Returns a <code>Reader</code> to be used by the script to read 187 * input. 188 * 189 * @return The <code>Reader</code>. 190 */ getReader()191 public Reader getReader(); 192 193 194 /** 195 * Sets the <code>Reader</code> for scripts to read input 196 * . 197 * @param reader The new <code>Reader</code>. 198 */ setReader(Reader reader)199 public void setReader(Reader reader); 200 201 /** 202 * Returns immutable <code>List</code> of all the valid values for 203 * scope in the ScriptContext. 204 * 205 * @return list of scope values 206 */ getScopes()207 public List<Integer> getScopes(); 208 } 209