001: /*
002: * Copyright 1996-2000 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package org.omg.CORBA;
027:
028: /**
029: * An object used in <code>Request</code> operations
030: * to specify the context object in which context strings
031: * must be resolved before being sent along with the request invocation.
032: * A <code>Context</code> object
033: * contains a list of properties in the form of <code>NamedValue</code>
034: * objects. These properties represent information
035: * about the client, the environment, or the circumstances of a request
036: * and generally are properties that might be inconvenient
037: * to pass as parameters.
038: * <P>
039: * A <code>Context</code> object is created by first calling the
040: * <code>ORB</code> method <code>get_default_context</code>
041: * and then calling the method <code>create_child</code> on the
042: * default context.
043: * <P>
044: * Each property in a <code>Context</code> object is represented by
045: * a <code>NamedValue</code> object. The property name is contained
046: * in the <code>NamedValue</code> object's <code>name</code> field, and
047: * the value associated with the name is contained in the <code>Any</code>
048: * object that was assigned to the <code>NamedValue</code> object's
049: * <code>value</code> field.
050: * <P>
051: * <code>Context</code> properties can represent a portion of a client's
052: * or application's environment that is meant to be propagated to
053: * (and made implicitly part of) a server's environment.
054: * (Examples might be a window identifier or user preference information).
055: * Once a server has been invoked (that is, after the properties are
056: * propagated), the server may query its <code>Context</code> object
057: * for these properties using the method <code>get_values</code>.
058: *
059: *<P>
060: * When an operation declaration includes a context clause,
061: * the stubs and skeletons will have an additional argument
062: * added for the context. When an operation invocation occurs,
063: * the ORB causes the properties that were named in the operation
064: * definition in IDL and
065: * that are present in the client's <code>Context</code> object
066: * to be provided in the <code>Context</code> object parameter to
067: * the invoked method.
068: * <P>
069: * <code>Context</code> property names (which are strings)
070: * typically have the form of an OMG IDL identifier or
071: * a series of OMG IDL identifiers separated by periods.
072: * A context property name pattern is either a property name
073: * or a property name followed by a single "*". A property
074: * name pattern without a trailing "*" is said to match only
075: * itself. A property name pattern of the form "<name>*" matches any
076: * property name that starts with <name> and continues with zero
077: * or more additional characters.
078: * <P>
079: * Property name patterns are used in the context clause of
080: * an operation definition and as a parameter for the
081: * method <code>Context.get_values</code>.
082: * <P>
083: * <code>Context</code> objects may be "chained" together to achieve a
084: * particular defaulting behavior. A <code>Context</code>
085: * object created with the method <code>create_child</code> will
086: * be chained to its parent (the <code>Context</code> object
087: * that created it), and that means that the parent will be searched
088: * after the child in a search for property names.
089: *<P>
090: * Properties defined in a particular <code>Context</code> object
091: * effectively override those properties in the next higher level.
092: * The scope used in a search for properties may be restricted by specifying a
093: * starting scope and by using the flag <code>CTX_RESTRICT_SCOPE</code>
094: * when invoking the method <code>get_values</code>.
095: * <P>
096: * A <code>Context</code> object may be named for purposes of specifying
097: * a starting search scope.
098: *
099: * @version 1.11, 09/09/97
100: * @since JDK1.2
101: */
102:
103: public abstract class Context {
104:
105: /**
106: * Retrieves the name of this <code>Context</code> object.
107: *
108: * @return the name of this <code>Context</code> object
109: */
110:
111: public abstract String context_name();
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: };
|