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: };