Context.java revision 608:7e06bf1dcb09
1/* 2 * Copyright (c) 1996, 2000, 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 26package org.omg.CORBA; 27 28/** 29 * An object used in <code>Request</code> operations 30 * to specify the context object in which context strings 31 * must be resolved before being sent along with the request invocation. 32 * A <code>Context</code> object 33 * contains a list of properties in the form of <code>NamedValue</code> 34 * objects. These properties represent information 35 * about the client, the environment, or the circumstances of a request 36 * and generally are properties that might be inconvenient 37 * to pass as parameters. 38 * <P> 39 * A <code>Context</code> object is created by first calling the 40 * <code>ORB</code> method <code>get_default_context</code> 41 * and then calling the method <code>create_child</code> on the 42 * default context. 43 * <P> 44 * Each property in a <code>Context</code> object is represented by 45 * a <code>NamedValue</code> object. The property name is contained 46 * in the <code>NamedValue</code> object's <code>name</code> field, and 47 * the value associated with the name is contained in the <code>Any</code> 48 * object that was assigned to the <code>NamedValue</code> object's 49 * <code>value</code> field. 50 * <P> 51 * <code>Context</code> properties can represent a portion of a client's 52 * or application's environment that is meant to be propagated to 53 * (and made implicitly part of) a server's environment. 54 * (Examples might be a window identifier or user preference information). 55 * Once a server has been invoked (that is, after the properties are 56 * propagated), the server may query its <code>Context</code> object 57 * for these properties using the method <code>get_values</code>. 58 * 59 *<P> 60 * When an operation declaration includes a context clause, 61 * the stubs and skeletons will have an additional argument 62 * added for the context. When an operation invocation occurs, 63 * the ORB causes the properties that were named in the operation 64 * definition in IDL and 65 * that are present in the client's <code>Context</code> object 66 * to be provided in the <code>Context</code> object parameter to 67 * the invoked method. 68 * <P> 69 * <code>Context</code> property names (which are strings) 70 * typically have the form of an OMG IDL identifier or 71 * a series of OMG IDL identifiers separated by periods. 72 * A context property name pattern is either a property name 73 * or a property name followed by a single "*". A property 74 * name pattern without a trailing "*" is said to match only 75 * itself. A property name pattern of the form "<name>*" matches any 76 * property name that starts with <name> and continues with zero 77 * or more additional characters. 78 * <P> 79 * Property name patterns are used in the context clause of 80 * an operation definition and as a parameter for the 81 * method <code>Context.get_values</code>. 82 * <P> 83 * <code>Context</code> objects may be "chained" together to achieve a 84 * particular defaulting behavior. A <code>Context</code> 85 * object created with the method <code>create_child</code> will 86 * be chained to its parent (the <code>Context</code> object 87 * that created it), and that means that the parent will be searched 88 * after the child in a search for property names. 89 *<P> 90 * Properties defined in a particular <code>Context</code> object 91 * effectively override those properties in the next higher level. 92 * The scope used in a search for properties may be restricted by specifying a 93 * starting scope and by using the flag <code>CTX_RESTRICT_SCOPE</code> 94 * when invoking the method <code>get_values</code>. 95 * <P> 96 * A <code>Context</code> object may be named for purposes of specifying 97 * a starting search scope. 98 * 99 * @since JDK1.2 100 */ 101 102public abstract class Context { 103 104 /** 105 * Retrieves the name of this <code>Context</code> object. 106 * 107 * @return the name of this <code>Context</code> object 108 */ 109 110 public abstract String context_name(); 111 112 113 /** 114 * Retrieves the parent of this <code>Context</code> object. 115 * 116 * @return the <code>Context</code> object that is the 117 * parent of this <code>Context</code> object 118 */ 119 120 public abstract Context parent(); 121 122 /** 123 * Creates a <code>Context</code> object with the given string as its 124 * name and with this <code>Context</code> object set as its parent. 125 * <P> 126 * The new <code>Context</code> object is chained into its parent 127 * <code>Context</code> object. This means that in a search for 128 * matching property names, if a match is not found in this context, 129 * the search will continue in the parent. If that is not successful, 130 * the search will continue in the grandparent, if there is one, and 131 * so on. 132 * 133 * 134 * @param child_ctx_name the <code>String</code> object to be set as 135 * the name of the new <code>Context</code> object 136 * @return the newly-created child <code>Context</code> object 137 * initialized with the specified name 138 */ 139 140 public abstract Context create_child(String child_ctx_name); 141 142 /** 143 * Creates a <code>NamedValue</code> object and adds it to this 144 * <code>Context</code> object. The <code>name</code> field of the 145 * new <code>NamedValue</code> object is set to the given string, 146 * the <code>value</code> field is set to the given <code>Any</code> 147 * object, and the <code>flags</code> field is set to zero. 148 * 149 * @param propname the name of the property to be set 150 * @param propvalue the <code>Any</code> object to which the 151 * value of the property will be set. The 152 * <code>Any</code> object's <code>value</code> 153 * field contains the value to be associated 154 * with the given propname; the 155 * <code>kind</code> field must be set to 156 * <code>TCKind.tk_string</code>. 157 */ 158 159 public abstract void set_one_value(String propname, Any propvalue); 160 161 /** 162 I Sets one or more property values in this <code>Context</code> 163 * object. The <code>NVList</code> supplied to this method 164 * contains one or more <code>NamedValue</code> objects. 165 * In each <code>NamedValue</code> object, 166 * the <code>name</code> field holds the name of the property, and 167 * the <code>flags</code> field must be set to zero. 168 * The <code>NamedValue</code> object's <code>value</code> field 169 * contains an <code>Any</code> object, which, in turn, contains the value 170 * for the property. Since the value is always a string, 171 * the <code>Any</code> object must have the <code>kind</code> 172 * field of its <code>TypeCode</code> set to <code>TCKind.tk_string</code>. 173 * 174 * @param values an NVList containing the property 175 * names and associated values to be set 176 * 177 * @see #get_values 178 * @see org.omg.CORBA.NamedValue 179 * @see org.omg.CORBA.Any 180 */ 181 182 public abstract void set_values(NVList values); 183 184 /** 185 * Deletes from this <code>Context</code> object the 186 * <code>NamedValue</code> object(s) whose 187 * <code>name</code> field matches the given property name. 188 * If the <code>String</code> object supplied for 189 * <code>propname</code> has a 190 * trailing wildcard character ("*"), then 191 * all <code>NamedValue</code> objects whose <code>name</code> 192 * fields match will be deleted. The search scope is always 193 * limited to this <code>Context</code> object. 194 * <P> 195 * If no matching property is found, an exception is returned. 196 * 197 * @param propname name of the property to be deleted 198 */ 199 200 public abstract void delete_values(String propname); 201 202 /** 203 * Retrieves the <code>NamedValue</code> objects whose 204 * <code>name</code> field matches the given name or name 205 * pattern. This method allows for wildcard searches, 206 * which means that there can be multiple matches and 207 * therefore multiple values returned. If the 208 * property is not found at the indicated level, the search 209 * continues up the context object tree until a match is found or 210 * all <code>Context</code> objects in the chain have been exhausted. 211 * <P> 212 * If no match is found, an error is returned and no property list 213 * is returned. 214 * 215 * @param start_scope a <code>String</code> object indicating the 216 * context object level at which to initiate the 217 * search for the specified properties 218 * (for example, "_USER", "_GROUP", "_SYSTEM"). Valid scope 219 * names are implementation-specific. If a 220 * scope name is omitted, the search 221 * begins with the specified context 222 * object. If the specified scope name is 223 * not found, an exception is returned. 224 * @param op_flags an operation flag. The one flag 225 * that may be specified is <code>CTX_RESTRICT_SCOPE</code>. 226 * If this flag is specified, searching is limited to the 227 * specified <code>start_scope</code> or this 228 * <code>Context</code> object. 229 * @param pattern the property name whose values are to 230 * be retrieved. <code>pattern</code> may be a 231 * name or a name with a 232 * trailing wildcard character ("*"). 233 * 234 * @return an <code>NVList</code> containing all the property values 235 * (in the form of <code>NamedValue</code> objects) 236 * whose associated property name matches the given name or 237 * name pattern 238 * @see #set_values 239 * @see org.omg.CORBA.NamedValue 240 */ 241 242 abstract public NVList get_values(String start_scope, int op_flags, 243 String pattern); 244}; 245