Previous Table of Contents Next


4.6 Context Object

   4.6.1 Introduction

   A context object contains a list of properties, each consisting of a name and a string value associated with that name. By convention, context properties represent information about the client, environment, or circumstances of a request that are passed as a single parameter representing that collection of information.

   Context properties represent a portion of a client's or application's environment that is meant to be propagated to (and made available to) a server's environment (for example, a window identifier, or user preference information). Once an operation has been invoked in the server, the operation implementation may query its context object for these properties.

   An operation definition may contain a context clause that specifies the context properties that may be of interest to a particular operation. These context properties (if present for the actual call) are propagated to the server. A client-side ORB may choose to pass more properties than are specified by an operation's context clause. An example of an operation with a context clause is

   interface Example { void op() context("USER", "X*"); };

   This context clause specifies that the "USER" property is to be made available to the server, as well as all properties with names beginning with "X". Note that there is no obligation on the client to actually pass values for these properties at run time; if the client omits one or more properties, the call proceeds normally and the operation implementation simply will not be able to retrieve the corresponding property values.

   Property names are non-empty strings that cannot contain the character '*'; there are no other syntactic restrictions on property names. Property names that differ only in case are distinct names, so the following is a legal context clause that transmits two distinct properties:

   interface Example2 { void op() context("FOO", "foo"); };

   Context property values are strings. An empty string is a legal property value.

   Property values are modified and accessed via the Context interface. A Context object represents a collection of property values. Context objects may be connected into hierarchies; properties defined in child Context objects lower in the hierarchy override properties in parent Context objects higher in the hierarchy.

   4.6.2 Context Object Operations

   Properties are represented as named value lists.

   module CORBA { interface Context { // PIDL

   void set_one_value( in Identifier prop_name, // property name to set in string value // property value to set

   ); void set_values( in NVList values // property values to set );

    void get_values( in Identifier start_scope, // search scope in Flags op_flags, // operation flags in Identifie prop_name, // name of property(s) to retrieve out NVList values // requested property(s)

   ); void delete_values( in Identifie prop_name // name of property(s) to delete );

    void create_child( in Identifier ctx_name, // name of context object out Context child_ctx // newly created context object

   ); void delete( in Flags del_flags // flags controlling deletion ); }; };

   4.6.2.1 set_one_value

   void set_one_value( in Identifier prop_name, // property name to set in string value // property value to set

   );

   This operation sets a single context object property. If prop_name is the empty string or contains the character '*', the operation raises BAD_PARAM with minor code 35.

   4.6.2.2 set_values

   void set_values( in NVLis values // property values to set );

   This operation sets one or more property values in its context object. If a property name appears more than once in the NVList, the value with higher index (later in the list) overwrites the value with lower index.

   The flags field of each passed NVList element must be zero. A non-zero flag in any of the NVList elements raises INV_FLAGS.

   The property name of each NVList element must be a non-empty string not containing the character '*'; otherwise, the operation raises BAD_PARAM with minor code 35.

   The value of each property of the passed NVList must be a (possibly empty) unbounded string. Property values other than unbounded strings raise BAD_TYPECODE with minor code 3.

   4.6.2.3 get_values

   void get_values( in Identifier start_scope, // search scope in Flags op_flags, // operation flags in Identifier prop_name, // name of property(s) to retrieve out NVList values // requested property(s)

   );

   This operation returns an NVList with those properties that match the prop_name parameter. Legal values for prop_name are:

   • a non-empty string that does not contain the character '*'

   In this case, the values parameter returns the property with the name specified by

   prop_name.

   • a string beginning with one or more characters other than '*', followed by a single '*' at the end, such as "XYZ*"

   In this case, the values parameter contains the properties that have names beginning with "XYZ" (such as "XYZABC" or "XYZ").

   If prop_name is the empty string, the string "*", contains more than one '*' character, or contains a '*' anywhere but at the end of the string, the operation raises BAD_PARAM with minor code 36.

   The start_scope parameter controls the context object level at which to initiate the search for the specified properties as follows:

   •If the context object on which get_values is invoked does not have a name equal to start_scope (and start_scope is not ""), the parent context object is retrieved and its name compared to start_scope; this process repeats until either a starting context object whose name equals start_scope is found, or the search terminates because it runs out of parent objects.

   The name of the root context object created by get_default_context is "RootContext".

   If no starting context object can be found, the operation raises BAD_CONTEXT with minor code 1.

   •If op_flags is zero, get_values searches the starting context and its parent contexts for properties that match prop_name. The property values that are returned are taken from the first context object in which they are found, so properties in child contexts override the values of properties in parent contexts.

   In either case, if no property matches prop_name, the operation raises BAD_CONTEXT with minor code 2.

   4.6.2.4 delete_values

   void delete_values( in Identifie prop_name // name of property(s) to delete );

   This operation deletes the properties that match prop_name. prop_name may have a trailing '*' character, in which case all properties whose name matches the specified prefix are deleted.

   If prop_name is the empty string, the string "*", contains more than one '*' character, or contains a '*' anywhere but at the end of the string, the operation raises BAD_PARAM with minor code 36. The operation only affects the context object on which it is invoked (that is, parent contexts are never affected by delete_values).

   If no property name matches prop_name, the operation raises BAD_CONTEXT with minor code 2.

   4.6.2.5 create_child

   void create_child( in Identifier ctx_name, // name of context object out Context child_ctx // newly created context object );

   This operation creates an empty child context object. The child context has the name ctx_name. ctx_name may not be the empty string or "RootContext"; otherwise, the operation raises BAD_PARAM with minor code 37. Calling create_child more than once with the same name on the same parent context is legal and results in the creation of a new, empty child context for each call.

   4.6.2.6 delete

   void delete( in Flags del_flags // flags controlling deletion

   );

   This operation deletes the context object on which it is invoked:

   If del_flags has a value other than zero or CTX_DELETE_DESCENDANTS, the operation raises INV_FLAGS.