duke@1: /* ohair@158: * Copyright (c) 1996, 2000, Oracle and/or its affiliates. All rights reserved. duke@1: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. duke@1: * duke@1: * This code is free software; you can redistribute it and/or modify it duke@1: * under the terms of the GNU General Public License version 2 only, as ohair@158: * published by the Free Software Foundation. Oracle designates this duke@1: * particular file as subject to the "Classpath" exception as provided ohair@158: * by Oracle in the LICENSE file that accompanied this code. duke@1: * duke@1: * This code is distributed in the hope that it will be useful, but WITHOUT duke@1: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or duke@1: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License duke@1: * version 2 for more details (a copy is included in the LICENSE file that duke@1: * accompanied this code). duke@1: * duke@1: * You should have received a copy of the GNU General Public License version duke@1: * 2 along with this work; if not, write to the Free Software Foundation, duke@1: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. duke@1: * ohair@158: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA ohair@158: * or visit www.oracle.com if you need additional information or have any ohair@158: * questions. duke@1: */ duke@1: duke@1: package org.omg.CORBA; duke@1: duke@1: /** duke@1: * An object used in Request operations duke@1: * to specify the context object in which context strings duke@1: * must be resolved before being sent along with the request invocation. duke@1: * A Context object duke@1: * contains a list of properties in the form of NamedValue duke@1: * objects. These properties represent information duke@1: * about the client, the environment, or the circumstances of a request duke@1: * and generally are properties that might be inconvenient duke@1: * to pass as parameters. duke@1: *

duke@1: * A Context object is created by first calling the duke@1: * ORB method get_default_context duke@1: * and then calling the method create_child on the duke@1: * default context. duke@1: *

duke@1: * Each property in a Context object is represented by duke@1: * a NamedValue object. The property name is contained duke@1: * in the NamedValue object's name field, and duke@1: * the value associated with the name is contained in the Any duke@1: * object that was assigned to the NamedValue object's duke@1: * value field. duke@1: *

duke@1: * Context properties can represent a portion of a client's duke@1: * or application's environment that is meant to be propagated to duke@1: * (and made implicitly part of) a server's environment. duke@1: * (Examples might be a window identifier or user preference information). duke@1: * Once a server has been invoked (that is, after the properties are duke@1: * propagated), the server may query its Context object duke@1: * for these properties using the method get_values. duke@1: * duke@1: *

duke@1: * When an operation declaration includes a context clause, duke@1: * the stubs and skeletons will have an additional argument duke@1: * added for the context. When an operation invocation occurs, duke@1: * the ORB causes the properties that were named in the operation duke@1: * definition in IDL and duke@1: * that are present in the client's Context object duke@1: * to be provided in the Context object parameter to duke@1: * the invoked method. duke@1: *

duke@1: * Context property names (which are strings) duke@1: * typically have the form of an OMG IDL identifier or duke@1: * a series of OMG IDL identifiers separated by periods. duke@1: * A context property name pattern is either a property name duke@1: * or a property name followed by a single "*". A property duke@1: * name pattern without a trailing "*" is said to match only duke@1: * itself. A property name pattern of the form "<name>*" matches any duke@1: * property name that starts with <name> and continues with zero duke@1: * or more additional characters. duke@1: *

duke@1: * Property name patterns are used in the context clause of duke@1: * an operation definition and as a parameter for the duke@1: * method Context.get_values. duke@1: *

duke@1: * Context objects may be "chained" together to achieve a duke@1: * particular defaulting behavior. A Context duke@1: * object created with the method create_child will duke@1: * be chained to its parent (the Context object duke@1: * that created it), and that means that the parent will be searched duke@1: * after the child in a search for property names. duke@1: *

duke@1: * Properties defined in a particular Context object duke@1: * effectively override those properties in the next higher level. duke@1: * The scope used in a search for properties may be restricted by specifying a duke@1: * starting scope and by using the flag CTX_RESTRICT_SCOPE duke@1: * when invoking the method get_values. duke@1: *

duke@1: * A Context object may be named for purposes of specifying duke@1: * a starting search scope. duke@1: * duke@1: * @since JDK1.2 duke@1: */ duke@1: duke@1: public abstract class Context { duke@1: duke@1: /** duke@1: * Retrieves the name of this Context object. duke@1: * duke@1: * @return the name of this Context object duke@1: */ duke@1: duke@1: public abstract String context_name(); duke@1: duke@1: duke@1: /** duke@1: * Retrieves the parent of this Context object. duke@1: * duke@1: * @return the Context object that is the duke@1: * parent of this Context object duke@1: */ duke@1: duke@1: public abstract Context parent(); duke@1: duke@1: /** duke@1: * Creates a Context object with the given string as its duke@1: * name and with this Context object set as its parent. duke@1: *

duke@1: * The new Context object is chained into its parent duke@1: * Context object. This means that in a search for duke@1: * matching property names, if a match is not found in this context, duke@1: * the search will continue in the parent. If that is not successful, duke@1: * the search will continue in the grandparent, if there is one, and duke@1: * so on. duke@1: * duke@1: * duke@1: * @param child_ctx_name the String object to be set as duke@1: * the name of the new Context object duke@1: * @return the newly-created child Context object duke@1: * initialized with the specified name duke@1: */ duke@1: duke@1: public abstract Context create_child(String child_ctx_name); duke@1: duke@1: /** duke@1: * Creates a NamedValue object and adds it to this duke@1: * Context object. The name field of the duke@1: * new NamedValue object is set to the given string, duke@1: * the value field is set to the given Any duke@1: * object, and the flags field is set to zero. duke@1: * duke@1: * @param propname the name of the property to be set duke@1: * @param propvalue the Any object to which the duke@1: * value of the property will be set. The duke@1: * Any object's value duke@1: * field contains the value to be associated duke@1: * with the given propname; the duke@1: * kind field must be set to duke@1: * TCKind.tk_string. duke@1: */ duke@1: duke@1: public abstract void set_one_value(String propname, Any propvalue); duke@1: duke@1: /** duke@1: I Sets one or more property values in this Context duke@1: * object. The NVList supplied to this method duke@1: * contains one or more NamedValue objects. duke@1: * In each NamedValue object, duke@1: * the name field holds the name of the property, and duke@1: * the flags field must be set to zero. duke@1: * The NamedValue object's value field duke@1: * contains an Any object, which, in turn, contains the value duke@1: * for the property. Since the value is always a string, duke@1: * the Any object must have the kind duke@1: * field of its TypeCode set to TCKind.tk_string. duke@1: * duke@1: * @param values an NVList containing the property duke@1: * names and associated values to be set duke@1: * duke@1: * @see #get_values duke@1: * @see org.omg.CORBA.NamedValue duke@1: * @see org.omg.CORBA.Any duke@1: */ duke@1: duke@1: public abstract void set_values(NVList values); duke@1: duke@1: /** duke@1: * Deletes from this Context object the duke@1: * NamedValue object(s) whose duke@1: * name field matches the given property name. duke@1: * If the String object supplied for duke@1: * propname has a duke@1: * trailing wildcard character ("*"), then duke@1: * all NamedValue objects whose name duke@1: * fields match will be deleted. The search scope is always duke@1: * limited to this Context object. duke@1: *

duke@1: * If no matching property is found, an exception is returned. duke@1: * duke@1: * @param propname name of the property to be deleted duke@1: */ duke@1: duke@1: public abstract void delete_values(String propname); duke@1: duke@1: /** duke@1: * Retrieves the NamedValue objects whose duke@1: * name field matches the given name or name duke@1: * pattern. This method allows for wildcard searches, duke@1: * which means that there can be multiple matches and duke@1: * therefore multiple values returned. If the duke@1: * property is not found at the indicated level, the search duke@1: * continues up the context object tree until a match is found or duke@1: * all Context objects in the chain have been exhausted. duke@1: *

duke@1: * If no match is found, an error is returned and no property list duke@1: * is returned. duke@1: * duke@1: * @param start_scope a String object indicating the duke@1: * context object level at which to initiate the duke@1: * search for the specified properties duke@1: * (for example, "_USER", "_GROUP", "_SYSTEM"). Valid scope duke@1: * names are implementation-specific. If a duke@1: * scope name is omitted, the search duke@1: * begins with the specified context duke@1: * object. If the specified scope name is duke@1: * not found, an exception is returned. duke@1: * @param op_flags an operation flag. The one flag duke@1: * that may be specified is CTX_RESTRICT_SCOPE. duke@1: * If this flag is specified, searching is limited to the duke@1: * specified start_scope or this duke@1: * Context object. duke@1: * @param pattern the property name whose values are to duke@1: * be retrieved. pattern may be a duke@1: * name or a name with a duke@1: * trailing wildcard character ("*"). duke@1: * duke@1: * @return an NVList containing all the property values duke@1: * (in the form of NamedValue objects) duke@1: * whose associated property name matches the given name or duke@1: * name pattern duke@1: * @see #set_values duke@1: * @see org.omg.CORBA.NamedValue duke@1: */ duke@1: duke@1: abstract public NVList get_values(String start_scope, int op_flags, duke@1: String pattern); duke@1: };