1 /*
   2  * Copyright (c) 1996, 2000, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package org.omg.CORBA;
  27 
  28 /**
  29  * An object used in <code>Request</code> operations
  30  * to specify the context object in which context strings
  31  * must be resolved before being sent along with the request invocation.
  32  * A <code>Context</code> object
  33  * contains a list of properties in the form of <code>NamedValue</code>
  34  * objects. These properties represent information
  35  * about the client, the environment, or the circumstances of a request
  36  * and generally are properties that might be inconvenient
  37  * to pass as parameters.
  38  * <P>
  39  * A <code>Context</code> object is created by first calling the
  40  * <code>ORB</code> method <code>get_default_context</code>
  41  * and then calling the method <code>create_child</code> on the
  42  * default context.
  43  * <P>
  44  * Each property in a <code>Context</code> object is represented by
  45  * a <code>NamedValue</code> object.  The property name is contained
  46  * in the <code>NamedValue</code> object's <code>name</code> field, and
  47  * the value associated with the name is contained in the <code>Any</code>
  48  * object that was assigned to the <code>NamedValue</code> object's
  49  * <code>value</code> field.
  50  * <P>
  51  * <code>Context</code> properties can represent a portion of a client's
  52  * or application's environment that is meant to be propagated to
  53  * (and made implicitly part of) a server's environment.
  54  * (Examples might be a window identifier or user preference information).
  55  * Once a server has been invoked (that is, after the properties are
  56  * propagated), the server may query its <code>Context</code> object
  57  * for these properties using the method <code>get_values</code>.
  58  *
  59  *<P>
  60  * When an operation declaration includes a context clause,
  61  * the stubs and skeletons will have an additional argument
  62  * added for the context.  When an operation invocation occurs,
  63  * the ORB causes the properties that were named in the operation
  64  * definition in IDL and
  65  * that are present in the client's <code>Context</code> object
  66  * to be provided in the <code>Context</code> object parameter to
  67  * the invoked method.
  68  * <P>
  69  * <code>Context</code> property names (which are strings)
  70  * typically have the form of an OMG IDL identifier or
  71  * a series of OMG IDL identifiers separated by periods.
  72  * A context property name pattern is either a property name
  73  * or a property name followed by a single "*".  A property
  74  * name pattern without a trailing "*" is said to match only
  75  * itself.  A property name pattern of the form "&lt;name&gt;*" matches any
  76  * property name that starts with &lt;name&gt; and continues with zero
  77  * or more additional characters.
  78  * <P>
  79  * Property name patterns are used in the context clause of
  80  * an operation definition and as a parameter for the
  81  * method <code>Context.get_values</code>.
  82  * <P>
  83  * <code>Context</code> objects may be "chained" together to achieve a
  84  * particular defaulting behavior.  A <code>Context</code>
  85  * object created with the method <code>create_child</code> will
  86  * be chained to its parent (the <code>Context</code> object
  87  * that created it), and that means that the parent will be searched
  88  * after the child in a search for property names.
  89  *<P>
  90  * Properties defined in a particular <code>Context</code> object
  91  * effectively override those properties in the next higher level.
  92  * The scope used in a search for properties may be restricted by specifying a
  93  * starting scope and by using the flag <code>CTX_RESTRICT_SCOPE</code>
  94  * when invoking the method <code>get_values</code>.
  95  * <P>
  96  * A <code>Context</code> object may be named for purposes of specifying
  97  * a starting search scope.
  98  *
  99  * @since   JDK1.2
 100  */
 101 
 102 public abstract class Context {
 103 
 104     /**
 105      * Retrieves the name of this <code>Context</code> object.
 106      *
 107      * @return                  the name of this <code>Context</code> object
 108      */
 109 
 110     public abstract String context_name();
 111 
 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 };