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 */ 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 */ 85 public Bindings getBindings(int scope); 86 87 /** 88 * Sets the value of an attribute in a given scope. 89 * 90 * @param name The name of the attribute to set 91 * @param value The value of the attribute 92 * @param scope The scope in which to set the attribute 93 * 94 * @throws IllegalArgumentException 95 * if the name is empty or if the scope is invalid. 96 * @throws NullPointerException if the name is null. 97 */ 98 public void setAttribute(String name, Object value, int scope); 99 100 /** 101 * Gets the value of an attribute in a given scope. 102 * 103 * @param name The name of the attribute to retrieve. 104 * @param scope The scope in which to retrieve the attribute. 105 * @return The value of the attribute. Returns <code>null</code> is the name 106 * does not exist in the given scope. 107 * 108 * @throws IllegalArgumentException 109 * if the name is empty or if the value of scope is invalid. 110 * @throws NullPointerException if the name is null. 111 */ 112 public Object getAttribute(String name, int scope); 113 114 /** 115 * Remove an attribute in a given scope. 116 * 117 * @param name The name of the attribute to remove 118 * @param scope The scope in which to remove the attribute 119 * 120 * @return The removed value. 121 * @throws IllegalArgumentException 122 * if the name is empty or if the scope is invalid. 123 * @throws NullPointerException if the name is null. 124 */ 125 public Object removeAttribute(String name, int scope); 126 127 /** 128 * Retrieves the value of the attribute with the given name in 129 * the scope occurring earliest in the search order. The order 130 * is determined by the numeric value of the scope parameter (lowest 131 * scope values first.) 132 * 133 * @param name The name of the attribute to retrieve. 134 * @return The value of the attribute in the lowest scope for 135 * which an attribute with the given name is defined. Returns 136 * null if no attribute with the name exists in any scope. 137 * @throws NullPointerException if the name is null. 138 * @throws IllegalArgumentException if the name is empty. 139 */ 140 public Object getAttribute(String name); 141 142 143 /** 144 * Get the lowest scope in which an attribute is defined. 145 * @param name Name of the attribute 146 * . 147 * @return The lowest scope. Returns -1 if no attribute with the given 148 * name is defined in any scope. 149 * @throws NullPointerException if name is null. 150 * @throws IllegalArgumentException if name is empty. 151 */ 152 public int getAttributesScope(String name); 153 154 /** 155 * Returns the <code>Writer</code> for scripts to use when displaying output. 156 * 157 * @return The <code>Writer</code>. 158 */ 159 public Writer getWriter(); 160 161 162 /** 163 * Returns the <code>Writer</code> used to display error output. 164 * 165 * @return The <code>Writer</code> 166 */ 167 public Writer getErrorWriter(); 168 169 /** 170 * Sets the <code>Writer</code> for scripts to use when displaying output. 171 * 172 * @param writer The new <code>Writer</code>. 173 */ 174 public void setWriter(Writer writer); 175 176 177 /** 178 * Sets the <code>Writer</code> used to display error output. 179 * 180 * @param writer The <code>Writer</code>. 181 */ 182 public void setErrorWriter(Writer writer); 183 184 /** 185 * Returns a <code>Reader</code> to be used by the script to read 186 * input. 187 * 188 * @return The <code>Reader</code>. 189 */ 190 public Reader getReader(); 191 192 193 /** 194 * Sets the <code>Reader</code> for scripts to read input 195 * . 196 * @param reader The new <code>Reader</code>. 197 */ 198 public void setReader(Reader reader); 199 200 /** 201 * Returns immutable <code>List</code> of all the valid values for 202 * scope in the ScriptContext. 203 * 204 * @return list of scope values 205 */ 206 public List<Integer> getScopes(); 207 }