API Overview API Index Package Overview Direct link to this page
JDK 1.6
  org.omg.CORBA. Context View Javadoc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227

/*
 * @(#)Context.java	1.25 05/11/17
 *
 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package org.omg.CORBA;

/**
 * An object used in <code>Request</code> operations
 * to specify the context object in which context strings
 * must be resolved before being sent along with the request invocation.
 * A <code>Context</code> object
 * contains a list of properties in the form of <code>NamedValue</code>
 * objects. These properties represent information
 * about the client, the environment, or the circumstances of a request
 * and generally are properties that might be inconvenient
 * to pass as parameters.
 * <P>
 * A <code>Context</code> object is created by first calling the
 * <code>ORB</code> method <code>get_default_context</code>
 * and then calling the method <code>create_child</code> on the
 * default context.
 * <P>
 * Each property in a <code>Context</code> object is represented by
 * a <code>NamedValue</code> object.  The property name is contained
 * in the <code>NamedValue</code> object's <code>name</code> field, and
 * the value associated with the name is contained in the <code>Any</code>
 * object that was assigned to the <code>NamedValue</code> object's
 * <code>value</code> field.
 * <P>
 * <code>Context</code> properties can represent a portion of a client's
 * or application's environment that is meant to be propagated to
 * (and made implicitly part of) a server's environment.
 * (Examples might be a window identifier or user preference information).
 * Once a server has been invoked (that is, after the properties are
 * propagated), the server may query its <code>Context</code> object
 * for these properties using the method <code>get_values</code>.
 *
 *<P>
 * When an operation declaration includes a context clause,
 * the stubs and skeletons will have an additional argument
 * added for the context.  When an operation invocation occurs,
 * the ORB causes the properties that were named in the operation
 * definition in IDL and
 * that are present in the client's <code>Context</code> object
 * to be provided in the <code>Context</code> object parameter to
 * the invoked method.
 * <P>
 * <code>Context</code> property names (which are strings)
 * typically have the form of an OMG IDL identifier or
 * a series of OMG IDL identifiers separated by periods.
 * A context property name pattern is either a property name
 * or a property name followed by a single "*".  A property
 * name pattern without a trailing "*" is said to match only
 * itself.  A property name pattern of the form "&lt;name&gt;*" matches any
 * property name that starts with &lt;name&gt; and continues with zero
 * or more additional characters.
 * <P>
 * Property name patterns are used in the context clause of
 * an operation definition and as a parameter for the
 * method <code>Context.get_values</code>.
 * <P>
 * <code>Context</code> objects may be "chained" together to achieve a
 * particular defaulting behavior.  A <code>Context</code>
 * object created with the method <code>create_child</code> will
 * be chained to its parent (the <code>Context</code> object
 * that created it), and that means that the parent will be searched
 * after the child in a search for property names.
 *<P>
 * Properties defined in a particular <code>Context</code> object
 * effectively override those properties in the next higher level.
 * The scope used in a search for properties may be restricted by specifying a
 * starting scope and by using the flag <code>CTX_RESTRICT_SCOPE</code>
 * when invoking the method <code>get_values</code>.
 * <P>
 * A <code>Context</code> object may be named for purposes of specifying
 * a starting search scope.
 *
 * @version 1.11, 09/09/97
 * @since   JDK1.2
 */

public abstract class Context {

    /**
     * Retrieves the name of this <code>Context</code> object.
     *
     * @return			the name of this <code>Context</code> object
     */

    public abstract String context_name();


    /**
     * Retrieves the parent of this <code>Context</code> object.
     *
     * @return			the <code>Context</code> object that is the
     *                    parent of this <code>Context</code> object
     */

    public abstract Context parent();

    /**
     * Creates a <code>Context</code> object with the given string as its
     * name and with this <code>Context</code> object set as its parent.
     * <P>
     * The new <code>Context</code> object is chained into its parent
     * <code>Context</code> object.  This means that in a search for
     * matching property names, if a match is not found in this context,
     * the search will continue in the parent.  If that is not successful,
     * the search will continue in the grandparent, if there is one, and
     * so on.
     *
     *
     * @param child_ctx_name	the <code>String</code> object to be set as
     *                        the name of the new <code>Context</code> object
     * @return 			the newly-created child <code>Context</code> object
     *                    initialized with the specified name
     */

    public abstract Context create_child(String child_ctx_name);

    /**
     * Creates a <code>NamedValue</code> object and adds it to this
     * <code>Context</code> object.  The <code>name</code> field of the
     * new <code>NamedValue</code> object is set to the given string,
     * the <code>value</code> field is set to the given <code>Any</code>
     * object, and the <code>flags</code> field is set to zero.
     *
     * @param propname		the name of the property to be set
     * @param propvalue		the <code>Any</code> object to which the
     *                        value of the property will be set.  The
     *                        <code>Any</code> object's <code>value</code>
     *                        field contains the value to be associated
     *                        with the given propname; the
     *                        <code>kind</code> field must be set to
     *                        <code>TCKind.tk_string</code>.
     */

    public abstract void set_one_value(String propname, Any propvalue);

    /**
       I Sets one or more property values in this <code>Context</code>
       * object. The <code>NVList</code> supplied to this method
       * contains one or more <code>NamedValue</code> objects.
       * In each <code>NamedValue</code> object,
       * the <code>name</code> field holds the name of the property, and
       * the <code>flags</code> field must be set to zero.
       * The <code>NamedValue</code> object's <code>value</code> field
       * contains an <code>Any</code> object, which, in turn, contains the value
       * for the property.  Since the value is always a string,
       * the <code>Any</code> object must have the <code>kind</code>
       * field of its <code>TypeCode</code> set to <code>TCKind.tk_string</code>.
       *
       * @param values		an NVList containing the property
       * 				    names and associated values to be set
       *
       * @see #get_values
       * @see org.omg.CORBA.NamedValue
       * @see org.omg.CORBA.Any
       */

    public abstract void set_values(NVList values);

    /**
     * Deletes from this <code>Context</code> object the
     * <code>NamedValue</code> object(s) whose
     * <code>name</code> field matches the given property name.
     * If the <code>String</code> object supplied for
     * <code>propname</code> has a
     * trailing wildcard character ("*"), then
     * all <code>NamedValue</code> objects whose <code>name</code>
     * fields match will be deleted. The search scope is always
     * limited to this <code>Context</code> object.
     * <P>
     * If no matching property is found, an exception is returned.
     *
     * @param propname		name of the property to be deleted
     */

    public abstract void delete_values(String propname);

    /**
     * Retrieves the <code>NamedValue</code> objects whose
     * <code>name</code> field matches the given name or name
     * pattern.   This method allows for wildcard searches,
     * which means that there can be multiple matches and
     * therefore multiple values returned. If the
     * property is not found at the indicated level, the search
     * continues up the context object tree until a match is found or
     * all <code>Context</code> objects in the chain have been exhausted.
     * <P>
     * If no match is found, an error is returned and no property list
     * is returned.
     *
     * @param start_scope		a <code>String</code> object indicating the
     *                context object level at which to initiate the
     *				search for the specified properties
     *				(for example, "_USER", "_GROUP", "_SYSTEM"). Valid scope
     *				names are implementation-specific. If a
     *				scope name is omitted, the search
     *				begins with the specified context
     *				object. If the specified scope name is
     *				not found, an exception is returned.
     * @param op_flags       an operation flag.  The one flag
     *                that may be specified is <code>CTX_RESTRICT_SCOPE</code>.
     *                If this flag is specified, searching is limited to the
     *				specified <code>start_scope</code> or this
     *                <code>Context</code> object.
     * @param pattern		the property name whose values are to
     *				be retrieved. <code>pattern</code> may be a
     *                name or a name with a
     *				trailing wildcard character ("*").
     *
     * @return		an <code>NVList</code> containing all the property values
     *                (in the form of <code>NamedValue</code> objects)
     *                whose associated property name matches the given name or
     *                name pattern
     * @see #set_values
     * @see org.omg.CORBA.NamedValue
     */

    abstract public NVList get_values(String start_scope, int op_flags,
				      String pattern);
};

Generated By: JavaOnTracks Doclet 0.1.4     ©Thibaut Colar