/*
* Copyright (c) 1996, 2000, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package org.omg.CORBA;
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
/**
* An object used in <code>Request</code> operations
* to specify the context object in which context strings
* must be resolved before being sent along with the request invocation.
* A <code>Context</code> object
* contains a list of properties in the form of <code>NamedValue</code>
* 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.
* <P>
* A <code>Context</code> object is created by first calling the
* <code>ORB</code> method <code>get_default_context</code>
* and then calling the method <code>create_child</code> on the
* default context.
* <P>
* Each property in a <code>Context</code> object is represented by
* a <code>NamedValue</code> object. The property name is contained
* in the <code>NamedValue</code> object's <code>name</code> field, and
* the value associated with the name is contained in the <code>Any</code>
* object that was assigned to the <code>NamedValue</code> object's
* <code>value</code> field.
* <P>
* <code>Context</code> 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 <code>Context</code> object
* for these properties using the method <code>get_values</code>.
*
*<P>
* 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 <code>Context</code> object
* to be provided in the <code>Context</code> object parameter to
* the invoked method.
* <P>
* <code>Context</code> 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.
* <P>
* Property name patterns are used in the context clause of
* an operation definition and as a parameter for the
* method <code>Context.get_values</code>.
* <P>
* <code>Context</code> objects may be "chained" together to achieve a
* particular defaulting behavior. A <code>Context</code>
* object created with the method <code>create_child</code> will
* be chained to its parent (the <code>Context</code> object
* that created it), and that means that the parent will be searched
* after the child in a search for property names.
*<P>
* Properties defined in a particular <code>Context</code> 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 <code>CTX_RESTRICT_SCOPE</code>
* when invoking the method <code>get_values</code>.
* <P>
* A <code>Context</code> object may be named for purposes of specifying
* a starting search scope.
*
* @since JDK1.2
*/
public abstract class Context {
Retrieves the name of this Context object.
Returns: the name of this Context object
/**
* Retrieves the name of this <code>Context</code> object.
*
* @return the name of this <code>Context</code> object
*/
public abstract String context_name();
Retrieves the parent of this Context object.
Returns: the Context object that is the
parent of this Context object
/**
* Retrieves the parent of this <code>Context</code> object.
*
* @return the <code>Context</code> object that is the
* parent of this <code>Context</code> object
*/
public abstract Context parent();
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.
Params: - 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
/**
* Creates a <code>Context</code> object with the given string as its
* name and with this <code>Context</code> object set as its parent.
* <P>
* The new <code>Context</code> object is chained into its parent
* <code>Context</code> 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 <code>String</code> object to be set as
* the name of the new <code>Context</code> object
* @return the newly-created child <code>Context</code> object
* initialized with the specified name
*/
public abstract Context create_child(String child_ctx_name);
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.
Params: - 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.
/**
* Creates a <code>NamedValue</code> object and adds it to this
* <code>Context</code> object. The <code>name</code> field of the
* new <code>NamedValue</code> object is set to the given string,
* the <code>value</code> field is set to the given <code>Any</code>
* object, and the <code>flags</code> field is set to zero.
*
* @param propname the name of the property to be set
* @param propvalue the <code>Any</code> object to which the
* value of the property will be set. The
* <code>Any</code> object's <code>value</code>
* field contains the value to be associated
* with the given propname; the
* <code>kind</code> field must be set to
* <code>TCKind.tk_string</code>.
*/
public abstract void set_one_value(String propname, Any propvalue);
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.
Params: - values – an NVList containing the property
names and associated values to be set
See Also:
/**
I Sets one or more property values in this <code>Context</code>
* object. The <code>NVList</code> supplied to this method
* contains one or more <code>NamedValue</code> objects.
* In each <code>NamedValue</code> object,
* the <code>name</code> field holds the name of the property, and
* the <code>flags</code> field must be set to zero.
* The <code>NamedValue</code> object's <code>value</code> field
* contains an <code>Any</code> object, which, in turn, contains the value
* for the property. Since the value is always a string,
* the <code>Any</code> object must have the <code>kind</code>
* field of its <code>TypeCode</code> set to <code>TCKind.tk_string</code>.
*
* @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
*/
public abstract void set_values(NVList values);
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.
Params: - propname – name of the property to be deleted
/**
* Deletes from this <code>Context</code> object the
* <code>NamedValue</code> object(s) whose
* <code>name</code> field matches the given property name.
* If the <code>String</code> object supplied for
* <code>propname</code> has a
* trailing wildcard character ("*"), then
* all <code>NamedValue</code> objects whose <code>name</code>
* fields match will be deleted. The search scope is always
* limited to this <code>Context</code> object.
* <P>
* If no matching property is found, an exception is returned.
*
* @param propname name of the property to be deleted
*/
public abstract void delete_values(String propname);
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.
Params: - 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 ("*").
See Also: 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
/**
* Retrieves the <code>NamedValue</code> objects whose
* <code>name</code> 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 <code>Context</code> objects in the chain have been exhausted.
* <P>
* If no match is found, an error is returned and no property list
* is returned.
*
* @param start_scope a <code>String</code> 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 <code>CTX_RESTRICT_SCOPE</code>.
* If this flag is specified, searching is limited to the
* specified <code>start_scope</code> or this
* <code>Context</code> object.
* @param pattern the property name whose values are to
* be retrieved. <code>pattern</code> may be a
* name or a name with a
* trailing wildcard character ("*").
*
* @return an <code>NVList</code> containing all the property values
* (in the form of <code>NamedValue</code> objects)
* whose associated property name matches the given name or
* name pattern
* @see #set_values
* @see org.omg.CORBA.NamedValue
*/
abstract public NVList get_values(String start_scope, int op_flags,
String pattern);
};