- /*
- * @(#)Context.java 1.19 00/02/02
- *
- * Copyright 1996-2000 Sun Microsystems, Inc. All Rights Reserved.
- *
- * This software is the proprietary information of Sun Microsystems, Inc.
- * 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 "<name>*" matches any
- * property name that starts with <name> 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 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 org.omg.CORBA.NamedValue
- */
-
- abstract public NVList get_values(String start_scope, int op_flags,
- String pattern);
- };
-