Module java.corba
Package org.omg.CORBA

## Class Context

- java.lang.Object
- - org.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.

  Since:
    JDK1.2

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Context​()` |

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `abstract String` | `context_name​()` | Retrieves the name of this `Context` object.
    `abstract Context` | `create_child​(String child_ctx_name)` | Creates a `Context` object with the given string as its name and with this `Context` object set as its parent.
    `abstract void` | `delete_values​(String propname)` | Deletes from this `Context` object the `NamedValue` object(s) whose `name` field matches the given property name.
    `abstract NVList` | `get_values​(String start_scope, int op_flags, String pattern)` | Retrieves the `NamedValue` objects whose `name` field matches the given name or name pattern.
    `abstract Context` | `parent​()` | Retrieves the parent of this `Context` object.
    `abstract void` | `set_one_value​(String propname, Any propvalue)` | Creates a `NamedValue` object and adds it to this `Context` object.
    `abstract void` | `set_values​(NVList values)` | I Sets one or more property values in this `Context` object.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### Context

          public Context​()

  - ### Method Detail

    - #### context_name

          public abstract String context_name​()

      Retrieves the name of this `Context` object.
      Returns:
        the name of this `Context` object

    - #### parent

          public abstract Context parent​()

      Retrieves the parent of this `Context` object.
      Returns:
        the `Context` object that is the parent of this `Context` object

    - #### create_child

          public abstract Context create_child​(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.

      Parameters:
        `child_ctx_name` - the `String` object to be set as the name of the new `Context` object
      Returns:
        the newly-created child `Context` object initialized with the specified name

    - #### set_one_value

          public abstract void set_one_value​(String propname,
                                             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.
      Parameters:
        `propname` - the name of the property to be set
        `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`.

    - #### set_values

          public abstract void set_values​(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`.
      Parameters:
        `values` - an NVList containing the property names and associated values to be set
      See Also:
        `get_values(java.lang.String, int, java.lang.String)`, `NamedValue`, `Any`

    - #### delete_values

          public abstract void delete_values​(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.

      Parameters:
        `propname` - name of the property to be deleted

    - #### get_values

          public abstract NVList get_values​(String start_scope,
                                            int op_flags,
                                            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.

      Parameters:
        `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.
        `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.
        `pattern` - the property name whose values are to be retrieved. `pattern` may be a name or a name with a trailing wildcard character ("*").
      Returns:
        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 Also:
        `set_values(org.omg.CORBA.NVList)`, `NamedValue`