Sat, 07 Jun 2014 10:09:30 +0100
8042789: org.omg.CORBA.ORBSingletonClass loading no longer uses context class loader
Reviewed-by: alanb, lancea
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 */
26 package org.omg.CORBA;
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 */
102 public abstract class Context {
104 /**
105 * Retrieves the name of this <code>Context</code> object.
106 *
107 * @return the name of this <code>Context</code> object
108 */
110 public abstract String context_name();
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 */
120 public abstract Context parent();
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 */
140 public abstract Context create_child(String child_ctx_name);
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 */
159 public abstract void set_one_value(String propname, Any propvalue);
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 */
182 public abstract void set_values(NVList values);
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 */
200 public abstract void delete_values(String propname);
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 */
242 abstract public NVList get_values(String start_scope, int op_flags,
243 String pattern);
244 };