/*
 * @(#)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);
};