1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/src/share/classes/org/omg/CORBA/Context.java Wed Apr 27 01:21:28 2016 +0800 1.3 @@ -0,0 +1,244 @@ 1.4 +/* 1.5 + * Copyright (c) 1996, 2000, Oracle and/or its affiliates. All rights reserved. 1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 1.7 + * 1.8 + * This code is free software; you can redistribute it and/or modify it 1.9 + * under the terms of the GNU General Public License version 2 only, as 1.10 + * published by the Free Software Foundation. Oracle designates this 1.11 + * particular file as subject to the "Classpath" exception as provided 1.12 + * by Oracle in the LICENSE file that accompanied this code. 1.13 + * 1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT 1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1.17 + * version 2 for more details (a copy is included in the LICENSE file that 1.18 + * accompanied this code). 1.19 + * 1.20 + * You should have received a copy of the GNU General Public License version 1.21 + * 2 along with this work; if not, write to the Free Software Foundation, 1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 1.23 + * 1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 1.25 + * or visit www.oracle.com if you need additional information or have any 1.26 + * questions. 1.27 + */ 1.28 + 1.29 +package org.omg.CORBA; 1.30 + 1.31 +/** 1.32 + * An object used in <code>Request</code> operations 1.33 + * to specify the context object in which context strings 1.34 + * must be resolved before being sent along with the request invocation. 1.35 + * A <code>Context</code> object 1.36 + * contains a list of properties in the form of <code>NamedValue</code> 1.37 + * objects. These properties represent information 1.38 + * about the client, the environment, or the circumstances of a request 1.39 + * and generally are properties that might be inconvenient 1.40 + * to pass as parameters. 1.41 + * <P> 1.42 + * A <code>Context</code> object is created by first calling the 1.43 + * <code>ORB</code> method <code>get_default_context</code> 1.44 + * and then calling the method <code>create_child</code> on the 1.45 + * default context. 1.46 + * <P> 1.47 + * Each property in a <code>Context</code> object is represented by 1.48 + * a <code>NamedValue</code> object. The property name is contained 1.49 + * in the <code>NamedValue</code> object's <code>name</code> field, and 1.50 + * the value associated with the name is contained in the <code>Any</code> 1.51 + * object that was assigned to the <code>NamedValue</code> object's 1.52 + * <code>value</code> field. 1.53 + * <P> 1.54 + * <code>Context</code> properties can represent a portion of a client's 1.55 + * or application's environment that is meant to be propagated to 1.56 + * (and made implicitly part of) a server's environment. 1.57 + * (Examples might be a window identifier or user preference information). 1.58 + * Once a server has been invoked (that is, after the properties are 1.59 + * propagated), the server may query its <code>Context</code> object 1.60 + * for these properties using the method <code>get_values</code>. 1.61 + * 1.62 + *<P> 1.63 + * When an operation declaration includes a context clause, 1.64 + * the stubs and skeletons will have an additional argument 1.65 + * added for the context. When an operation invocation occurs, 1.66 + * the ORB causes the properties that were named in the operation 1.67 + * definition in IDL and 1.68 + * that are present in the client's <code>Context</code> object 1.69 + * to be provided in the <code>Context</code> object parameter to 1.70 + * the invoked method. 1.71 + * <P> 1.72 + * <code>Context</code> property names (which are strings) 1.73 + * typically have the form of an OMG IDL identifier or 1.74 + * a series of OMG IDL identifiers separated by periods. 1.75 + * A context property name pattern is either a property name 1.76 + * or a property name followed by a single "*". A property 1.77 + * name pattern without a trailing "*" is said to match only 1.78 + * itself. A property name pattern of the form "<name>*" matches any 1.79 + * property name that starts with <name> and continues with zero 1.80 + * or more additional characters. 1.81 + * <P> 1.82 + * Property name patterns are used in the context clause of 1.83 + * an operation definition and as a parameter for the 1.84 + * method <code>Context.get_values</code>. 1.85 + * <P> 1.86 + * <code>Context</code> objects may be "chained" together to achieve a 1.87 + * particular defaulting behavior. A <code>Context</code> 1.88 + * object created with the method <code>create_child</code> will 1.89 + * be chained to its parent (the <code>Context</code> object 1.90 + * that created it), and that means that the parent will be searched 1.91 + * after the child in a search for property names. 1.92 + *<P> 1.93 + * Properties defined in a particular <code>Context</code> object 1.94 + * effectively override those properties in the next higher level. 1.95 + * The scope used in a search for properties may be restricted by specifying a 1.96 + * starting scope and by using the flag <code>CTX_RESTRICT_SCOPE</code> 1.97 + * when invoking the method <code>get_values</code>. 1.98 + * <P> 1.99 + * A <code>Context</code> object may be named for purposes of specifying 1.100 + * a starting search scope. 1.101 + * 1.102 + * @since JDK1.2 1.103 + */ 1.104 + 1.105 +public abstract class Context { 1.106 + 1.107 + /** 1.108 + * Retrieves the name of this <code>Context</code> object. 1.109 + * 1.110 + * @return the name of this <code>Context</code> object 1.111 + */ 1.112 + 1.113 + public abstract String context_name(); 1.114 + 1.115 + 1.116 + /** 1.117 + * Retrieves the parent of this <code>Context</code> object. 1.118 + * 1.119 + * @return the <code>Context</code> object that is the 1.120 + * parent of this <code>Context</code> object 1.121 + */ 1.122 + 1.123 + public abstract Context parent(); 1.124 + 1.125 + /** 1.126 + * Creates a <code>Context</code> object with the given string as its 1.127 + * name and with this <code>Context</code> object set as its parent. 1.128 + * <P> 1.129 + * The new <code>Context</code> object is chained into its parent 1.130 + * <code>Context</code> object. This means that in a search for 1.131 + * matching property names, if a match is not found in this context, 1.132 + * the search will continue in the parent. If that is not successful, 1.133 + * the search will continue in the grandparent, if there is one, and 1.134 + * so on. 1.135 + * 1.136 + * 1.137 + * @param child_ctx_name the <code>String</code> object to be set as 1.138 + * the name of the new <code>Context</code> object 1.139 + * @return the newly-created child <code>Context</code> object 1.140 + * initialized with the specified name 1.141 + */ 1.142 + 1.143 + public abstract Context create_child(String child_ctx_name); 1.144 + 1.145 + /** 1.146 + * Creates a <code>NamedValue</code> object and adds it to this 1.147 + * <code>Context</code> object. The <code>name</code> field of the 1.148 + * new <code>NamedValue</code> object is set to the given string, 1.149 + * the <code>value</code> field is set to the given <code>Any</code> 1.150 + * object, and the <code>flags</code> field is set to zero. 1.151 + * 1.152 + * @param propname the name of the property to be set 1.153 + * @param propvalue the <code>Any</code> object to which the 1.154 + * value of the property will be set. The 1.155 + * <code>Any</code> object's <code>value</code> 1.156 + * field contains the value to be associated 1.157 + * with the given propname; the 1.158 + * <code>kind</code> field must be set to 1.159 + * <code>TCKind.tk_string</code>. 1.160 + */ 1.161 + 1.162 + public abstract void set_one_value(String propname, Any propvalue); 1.163 + 1.164 + /** 1.165 + I Sets one or more property values in this <code>Context</code> 1.166 + * object. The <code>NVList</code> supplied to this method 1.167 + * contains one or more <code>NamedValue</code> objects. 1.168 + * In each <code>NamedValue</code> object, 1.169 + * the <code>name</code> field holds the name of the property, and 1.170 + * the <code>flags</code> field must be set to zero. 1.171 + * The <code>NamedValue</code> object's <code>value</code> field 1.172 + * contains an <code>Any</code> object, which, in turn, contains the value 1.173 + * for the property. Since the value is always a string, 1.174 + * the <code>Any</code> object must have the <code>kind</code> 1.175 + * field of its <code>TypeCode</code> set to <code>TCKind.tk_string</code>. 1.176 + * 1.177 + * @param values an NVList containing the property 1.178 + * names and associated values to be set 1.179 + * 1.180 + * @see #get_values 1.181 + * @see org.omg.CORBA.NamedValue 1.182 + * @see org.omg.CORBA.Any 1.183 + */ 1.184 + 1.185 + public abstract void set_values(NVList values); 1.186 + 1.187 + /** 1.188 + * Deletes from this <code>Context</code> object the 1.189 + * <code>NamedValue</code> object(s) whose 1.190 + * <code>name</code> field matches the given property name. 1.191 + * If the <code>String</code> object supplied for 1.192 + * <code>propname</code> has a 1.193 + * trailing wildcard character ("*"), then 1.194 + * all <code>NamedValue</code> objects whose <code>name</code> 1.195 + * fields match will be deleted. The search scope is always 1.196 + * limited to this <code>Context</code> object. 1.197 + * <P> 1.198 + * If no matching property is found, an exception is returned. 1.199 + * 1.200 + * @param propname name of the property to be deleted 1.201 + */ 1.202 + 1.203 + public abstract void delete_values(String propname); 1.204 + 1.205 + /** 1.206 + * Retrieves the <code>NamedValue</code> objects whose 1.207 + * <code>name</code> field matches the given name or name 1.208 + * pattern. This method allows for wildcard searches, 1.209 + * which means that there can be multiple matches and 1.210 + * therefore multiple values returned. If the 1.211 + * property is not found at the indicated level, the search 1.212 + * continues up the context object tree until a match is found or 1.213 + * all <code>Context</code> objects in the chain have been exhausted. 1.214 + * <P> 1.215 + * If no match is found, an error is returned and no property list 1.216 + * is returned. 1.217 + * 1.218 + * @param start_scope a <code>String</code> object indicating the 1.219 + * context object level at which to initiate the 1.220 + * search for the specified properties 1.221 + * (for example, "_USER", "_GROUP", "_SYSTEM"). Valid scope 1.222 + * names are implementation-specific. If a 1.223 + * scope name is omitted, the search 1.224 + * begins with the specified context 1.225 + * object. If the specified scope name is 1.226 + * not found, an exception is returned. 1.227 + * @param op_flags an operation flag. The one flag 1.228 + * that may be specified is <code>CTX_RESTRICT_SCOPE</code>. 1.229 + * If this flag is specified, searching is limited to the 1.230 + * specified <code>start_scope</code> or this 1.231 + * <code>Context</code> object. 1.232 + * @param pattern the property name whose values are to 1.233 + * be retrieved. <code>pattern</code> may be a 1.234 + * name or a name with a 1.235 + * trailing wildcard character ("*"). 1.236 + * 1.237 + * @return an <code>NVList</code> containing all the property values 1.238 + * (in the form of <code>NamedValue</code> objects) 1.239 + * whose associated property name matches the given name or 1.240 + * name pattern 1.241 + * @see #set_values 1.242 + * @see org.omg.CORBA.NamedValue 1.243 + */ 1.244 + 1.245 + abstract public NVList get_values(String start_scope, int op_flags, 1.246 + String pattern); 1.247 +};