FileDocCategorySizeDatePackage
Context.javaAPI DocJava SE 5 API10005Fri Aug 26 14:58:28 BST 2005org.omg.CORBA

Context

public abstract class Context extends Object
An object used in Request operations to specify the context object in which context strings must be resolved before being sent along with the request invocation. A Context object contains a list of properties in the form of NamedValue 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.

A Context object is created by first calling the ORB method get_default_context and then calling the method create_child on the default context.

Each property in a Context object is represented by a NamedValue object. The property name is contained in the NamedValue object's name field, and the value associated with the name is contained in the Any object that was assigned to the NamedValue object's value field.

Context 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 Context object for these properties using the method get_values.

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 Context object to be provided in the Context object parameter to the invoked method.

Context 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.

Property name patterns are used in the context clause of an operation definition and as a parameter for the method Context.get_values.

Context objects may be "chained" together to achieve a particular defaulting behavior. A Context object created with the method create_child will be chained to its parent (the Context object that created it), and that means that the parent will be searched after the child in a search for property names.

Properties defined in a particular Context 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 CTX_RESTRICT_SCOPE when invoking the method get_values.

A Context object may be named for purposes of specifying a starting search scope.

version
1.11, 09/09/97
since
JDK1.2

Fields Summary
Constructors Summary
Methods Summary
public abstract java.lang.Stringcontext_name()
Retrieves the name of this Context object.

return
the name of this Context object

public abstract org.omg.CORBA.Contextcreate_child(java.lang.String child_ctx_name)
Creates a Context object with the given string as its name and with this Context object set as its parent.

The new Context object is chained into its parent Context 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 String object to be set as the name of the new Context object
return
the newly-created child Context object initialized with the specified name

public abstract voiddelete_values(java.lang.String propname)
Deletes from this Context object the NamedValue object(s) whose name field matches the given property name. If the String object supplied for propname has a trailing wildcard character ("*"), then all NamedValue objects whose name fields match will be deleted. The search scope is always limited to this Context object.

If no matching property is found, an exception is returned.

param
propname name of the property to be deleted

public abstract org.omg.CORBA.NVListget_values(java.lang.String start_scope, int op_flags, java.lang.String pattern)
Retrieves the NamedValue objects whose name 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 Context objects in the chain have been exhausted.

If no match is found, an error is returned and no property list is returned.

param
start_scope a String 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 CTX_RESTRICT_SCOPE. If this flag is specified, searching is limited to the specified start_scope or this Context object.
param
pattern the property name whose values are to be retrieved. pattern may be a name or a name with a trailing wildcard character ("*").
return
an NVList containing all the property values (in the form of NamedValue objects) whose associated property name matches the given name or name pattern
see
#set_values
see
org.omg.CORBA.NamedValue

public abstract org.omg.CORBA.Contextparent()
Retrieves the parent of this Context object.

return
the Context object that is the parent of this Context object

public abstract voidset_one_value(java.lang.String propname, org.omg.CORBA.Any propvalue)
Creates a NamedValue object and adds it to this Context object. The name field of the new NamedValue object is set to the given string, the value field is set to the given Any object, and the flags field is set to zero.

param
propname the name of the property to be set
param
propvalue the Any object to which the value of the property will be set. The Any object's value field contains the value to be associated with the given propname; the kind field must be set to TCKind.tk_string.

public abstract voidset_values(org.omg.CORBA.NVList values)
I Sets one or more property values in this Context object. The NVList supplied to this method contains one or more NamedValue objects. In each NamedValue object, the name field holds the name of the property, and the flags field must be set to zero. The NamedValue object's value field contains an Any object, which, in turn, contains the value for the property. Since the value is always a string, the Any object must have the kind field of its TypeCode set to TCKind.tk_string.

param
values an NVList containing the property names and associated values to be set
see
#get_values
see
org.omg.CORBA.NamedValue
see
org.omg.CORBA.Any