Context


1   /*
2    * @(#)Context.java 1.24 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package org.omg.CORBA;
9   
10  /**
11   * An object used in <code>Request</code> operations
12   * to specify the context object in which context strings
13   * must be resolved before being sent along with the request invocation.
14   * A <code>Context</code> object
15   * contains a list of properties in the form of <code>NamedValue</code>
16   * objects. These properties represent information
17   * about the client, the environment, or the circumstances of a request
18   * and generally are properties that might be inconvenient
19   * to pass as parameters.
20   * <P>
21   * A <code>Context</code> object is created by first calling the
22   * <code>ORB</code> method <code>get_default_context</code>
23   * and then calling the method <code>create_child</code> on the
24   * default context.
25   * <P>
26   * Each property in a <code>Context</code> object is represented by
27   * a <code>NamedValue</code> object.  The property name is contained
28   * in the <code>NamedValue</code> object's <code>name</code> field, and
29   * the value associated with the name is contained in the <code>Any</code>
30   * object that was assigned to the <code>NamedValue</code> object's
31   * <code>value</code> field.
32   * <P>
33   * <code>Context</code> properties can represent a portion of a client's
34   * or application's environment that is meant to be propagated to
35   * (and made implicitly part of) a server's environment.
36   * (Examples might be a window identifier or user preference information).
37   * Once a server has been invoked (that is, after the properties are
38   * propagated), the server may query its <code>Context</code> object
39   * for these properties using the method <code>get_values</code>.
40   *
41   *<P>
42   * When an operation declaration includes a context clause,
43   * the stubs and skeletons will have an additional argument
44   * added for the context.  When an operation invocation occurs,
45   * the ORB causes the properties that were named in the operation
46   * definition in IDL and
47   * that are present in the client's <code>Context</code> object
48   * to be provided in the <code>Context</code> object parameter to
49   * the invoked method.
50   * <P>
51   * <code>Context</code> property names (which are strings)
52   * typically have the form of an OMG IDL identifier or
53   * a series of OMG IDL identifiers separated by periods.
54   * A context property name pattern is either a property name
55   * or a property name followed by a single "*".  A property
56   * name pattern without a trailing "*" is said to match only
57   * itself.  A property name pattern of the form "&lt;name&gt;*" matches any
58   * property name that starts with &lt;name&gt; and continues with zero
59   * or more additional characters.
60   * <P>
61   * Property name patterns are used in the context clause of
62   * an operation definition and as a parameter for the
63   * method <code>Context.get_values</code>.
64   * <P>
65   * <code>Context</code> objects may be "chained" together to achieve a
66   * particular defaulting behavior.  A <code>Context</code>
67   * object created with the method <code>create_child</code> will
68   * be chained to its parent (the <code>Context</code> object
69   * that created it), and that means that the parent will be searched
70   * after the child in a search for property names.
71   *<P>
72   * Properties defined in a particular <code>Context</code> object
73   * effectively override those properties in the next higher level.
74   * The scope used in a search for properties may be restricted by specifying a
75   * starting scope and by using the flag <code>CTX_RESTRICT_SCOPE</code>
76   * when invoking the method <code>get_values</code>.
77   * <P>
78   * A <code>Context</code> object may be named for purposes of specifying
79   * a starting search scope.
80   *
81   * @version 1.11, 09/09/97
82   * @since   JDK1.2
83   */
84  
85  public abstract class Context {
86  
87      /**
88       * Retrieves the name of this <code>Context</code> object.
89       *
90       * @return          the name of this <code>Context</code> object
91       */
92  
93      public abstract String   context_name();
94  
95  
96      /**
97       * Retrieves the parent of this <code>Context</code> object.
98       *
99       * @return          the <code>Context</code> object that is the
100      *                    parent of this <code>Context</code> object
101      */
102 
103     public abstract Context   parent();
104 
105     /**
106      * Creates a <code>Context</code> object with the given string as its
107      * name and with this <code>Context</code> object set as its parent.
108      * <P>
109      * The new <code>Context</code> object is chained into its parent
110      * <code>Context</code> object.  This means that in a search for
111      * matching property names, if a match is not found in this context,
112      * the search will continue in the parent.  If that is not successful,
113      * the search will continue in the grandparent, if there is one, and
114      * so on.
115      *
116      *
117      * @param child_ctx_name    the <code>String</code> object to be set as
118      *                        the name of the new <code>Context</code> object
119      * @return          the newly-created child <code>Context</code> object
120      *                    initialized with the specified name
121      */
122 
123     public abstract Context   create_child(String   child_ctx_name);
124 
125     /**
126      * Creates a <code>NamedValue</code> object and adds it to this
127      * <code>Context</code> object.  The <code>name</code> field of the
128      * new <code>NamedValue</code> object is set to the given string,
129      * the <code>value</code> field is set to the given <code>Any</code>
130      * object, and the <code>flags</code> field is set to zero.
131      *
132      * @param propname      the name of the property to be set
133      * @param propvalue     the <code>Any</code> object to which the
134      *                        value of the property will be set.  The
135      *                        <code>Any</code> object's <code>value</code>
136      *                        field contains the value to be associated
137      *                        with the given propname; the
138      *                        <code>kind</code> field must be set to
139      *                        <code>TCKind.tk_string</code>.
140      */
141 
142     public abstract void set_one_value(String   propname, Any   propvalue);
143 
144     /**
145        I Sets one or more property values in this <code>Context</code>
146        * object. The <code>NVList</code> supplied to this method
147        * contains one or more <code>NamedValue</code> objects.
148        * In each <code>NamedValue</code> object,
149        * the <code>name</code> field holds the name of the property, and
150        * the <code>flags</code> field must be set to zero.
151        * The <code>NamedValue</code> object's <code>value</code> field
152        * contains an <code>Any</code> object, which, in turn, contains the value
153        * for the property.  Since the value is always a string,
154        * the <code>Any</code> object must have the <code>kind</code>
155        * field of its <code>TypeCode</code> set to <code>TCKind.tk_string</code>.
156        *
157        * @param values      an NVList containing the property
158        *                    names and associated values to be set
159        *
160        * @see #get_values
161        * @see org.omg.CORBA.NamedValue
162        * @see org.omg.CORBA.Any
163        */
164 
165     public abstract void set_values(NVList   values);
166 
167     /**
168      * Deletes from this <code>Context</code> object the
169      * <code>NamedValue</code> object(s) whose
170      * <code>name</code> field matches the given property name.
171      * If the <code>String</code> object supplied for
172      * <code>propname</code> has a
173      * trailing wildcard character ("*"), then
174      * all <code>NamedValue</code> objects whose <code>name</code>
175      * fields match will be deleted. The search scope is always
176      * limited to this <code>Context</code> object.
177      * <P>
178      * If no matching property is found, an exception is returned.
179      *
180      * @param propname      name of the property to be deleted
181      */
182 
183     public abstract void delete_values(String   propname);
184 
185     /**
186      * Retrieves the <code>NamedValue</code> objects whose
187      * <code>name</code> field matches the given name or name
188      * pattern.   This method allows for wildcard searches,
189      * which means that there can be multiple matches and
190      * therefore multiple values returned. If the
191      * property is not found at the indicated level, the search
192      * continues up the context object tree until a match is found or
193      * all <code>Context</code> objects in the chain have been exhausted.
194      * <P>
195      * If no match is found, an error is returned and no property list
196      * is returned.
197      *
198      * @param start_scope       a <code>String</code> object indicating the
199      *                context object level at which to initiate the
200      *              search for the specified properties
201      *              (for example, "_USER", "_GROUP", "_SYSTEM"). Valid scope
202      *              names are implementation-specific. If a
203      *              scope name is omitted, the search
204      *              begins with the specified context
205      *              object. If the specified scope name is
206      *              not found, an exception is returned.
207      * @param op_flags       an operation flag.  The one flag
208      *                that may be specified is <code>CTX_RESTRICT_SCOPE</code>.
209      *                If this flag is specified, searching is limited to the
210      *              specified <code>start_scope</code> or this
211      *                <code>Context</code> object.
212      * @param pattern       the property name whose values are to
213      *              be retrieved. <code>pattern</code> may be a
214      *                name or a name with a
215      *              trailing wildcard character ("*").
216      *
217      * @return      an <code>NVList</code> containing all the property values
218      *                (in the form of <code>NamedValue</code> objects)
219      *                whose associated property name matches the given name or
220      *                name pattern
221      * @see #set_values
222      * @see org.omg.CORBA.NamedValue
223      */
224 
225     abstract public NVList   get_values(String   start_scope, int op_flags,
226                       String   pattern);
227 };
228 
229
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags