Previous | Table of Contents | Next |
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:
•The start_scope parameter specifies the name of the context object in which the search for properties is to start.
• If the context object on which get_values is invoked has a name equal to start_scope, that context object becomes the starting context object for the search.
•If start_scope is "", the context object on which get_values is invoked becomes the starting context object for the search.
•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.
• Once a starting context object is found, get_values searches for properties in the matching context object.
• If op_flags is CORBA::CTX_RESTRICT_SCOPE, get_values searches only the starting context object for properties that match prop_name. (The value of CTX_RESTRICT_SCOPE is 15.)
•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 is zero, the context object is deleted only if it has no child contexts; otherwise, if del_flags is zero and the context object has child contexts, the operation raises BAD_PARAM with minor code 38.
•If del_flags is CORBA::CTX_DELETE_DESCENDANTS, the context object on which delete is invoked is destroyed, together with (recursively) its child contexts. The value of CTX_DELETE_DESCENDANTS is 1.
If del_flags has a value other than zero or CTX_DELETE_DESCENDANTS, the operation raises INV_FLAGS.