![]() ![]() ![]() ![]() ![]() ![]() ![]() |
This chapter describes the Oracle Tuxedo implementation of the CORBA core member functions in C++ and their extensions. It also describes pseudo-objects and their relationship to C++ classes. Pseudo-objects are object references that cannot be transmitted across the network. Pseudo-objects are similar to other objects; however, because the ORB owns them, they cannot be extended.
Notes: | Some of the information in this chapter is taken from the Common Object Request Broker: Architecture and Specification. Revision 2.4.2, February 2001, published by the Object Management Group (OMG). Used with permission of the OMG. |
Note: | The Oracle Tuxedo CORBA Java client and Oracle Tuxedo CORBA Java client ORB were deprecated in Tuxedo 8.1 and are no longer supported in Tuxedo 9.x. All Oracle Tuxedo CORBA Java client and Oracle Tuxedo CORBA Java client ORB text references, associated code samples, etc. should only be used: |
Note: | Technical support for third party CORBA Java ORBs should be provided by their respective vendors. Oracle Tuxedo does not provide any technical support or documentation for third party CORBA Java ORBs. |
The following Oracle Tuxedo classes are global in scope:
These classes contain the predefined types, classes, and functions used in Oracle Tuxedo development.
The CORBA class contains the classes, data types, and member functions essential to using an Object Request Broker (ORB) as defined by CORBA. The Oracle Tuxedo extensions to CORBA are contained in the Tobj C++ class. The Tobj class contains data types, nested classes, and member functions that Oracle Tuxedo provides as an extension to CORBA.
Using CORBA data types and member functions in the Oracle Tuxedo product requires the CORBA::
prefix. For example, a Long
is a CORBA::Long
. Likewise, to use Tobj nested classes and member functions in the Oracle Tuxedo product, you need the Tobj::
prefix. For example, FactoryFinder is Tobj::FactoryFinder
.
Pseudo-objects are represented as local classes, which reside in the CORBA class. A pseudo-object and its corresponding member functions are named using a nested class structure. For example, an ORB object is a CORBA::ORB
and a Current object is a CORBA::Current
.
This section describes the member functions of the Any
class.
The mapping of these member functions to C++ is as follows:
class CORBA
{
class Any
{
public:
Any ();
Any (const Any&);
Any (TypeCode_ptr tc, void *value, Boolean release =
CORBA_ FALSE);
~Any ();
Any & operator=(const Any&);
void operator<<=(Short);
void operator<<=(UShort);
void operator<<=(Long);
void operator<<=(ULong);
void operator<<=(Float);
void operator<<=(Double);
void operator<<=(const Any&);
void operator<<=(const char*);
void operator<<=(Object_ptr);
void operator<<=(from_boolean);
void operator<<=(from_char);
void operator<<=(from_octet);
void operator<<=(from_string);
Boolean operator>>=(Short&) const;
Boolean operator>>=(UShort&) const;
Boolean operator>>=(Long&) const;
Boolean operator>>=(ULong&) const;
Boolean operator>>=(Float&) const;
Boolean operator>>=(Double&) const;
Boolean operator>>=(Any&) const;
Boolean operator>>=(char*&) const;
Boolean operator>>=(Object_ptr&) const;
Boolean operator>>=(to_boolean) const;
Boolean operator>>=(to_char) const;
Boolean operator>>=(to_octet) const;
Boolean operator>>=(to_object) const;
Boolean operator>>=(to_string) const;
TypeCode_ptr type()const;
void replace(TypeCode_ptr, void *, Boolean);
void replace(TypeCode_ptr, void *);
const void * value() const;
};
}; //CORBA
CORBA::Any::Any()
This is the default constructor for the CORBA::Any
class. It creates an Any object with a TypeCode of type tc_null
and a value of 0 (zero).
Constructs the Any object that is a copy of another Any object.
CORBA::Any::Any(const CORBA::Any & InitAny)
InitAny
This is the copy constructor for the CORBA::Any
class. This constructor duplicates the TypeCode reference of the Any that is passed in.
The type of copying to be performed is determined by the release
flag of the Any object to be copied. If release
evaluates as CORBA_TRUE
, the constructor deep-copies the parameter’s value; if release
evaluates as CORBA_FALSE
, the constructor shallow-copies the parameter’s value. Using a shallow copy gives you more control to optimize memory allocation, but the caller must ensure the Any does not use memory that has been freed.
Creates the Any object using a TypeCode and a value.
CORBA::Any::Any(TypeCode_ptr TC, void * Value, Boolean Release)
TC
Value
Release
Any
assumes ownership of the memory specified by the Value
argument. If Release
is CORBA_TRUE
, the Any
assumes ownership. If Release
is CORBA_FALSE
, the Any
does not assume ownership; the data pointed to by the Value
argument is not released upon assignment or destruction.
This constructor is used with the nontype-safe Any
interface. It duplicates the specified TypeCode object reference and then inserts the data pointed to by value inside the Any
object.
CORBA::Any::~Any()
This destructor frees the memory that the CORBA::Any
holds (if the Release
flag is specified as CORBA_TRUE
), and releases the TypeCode pseudo-object reference contained in the Any
.
CORBA::Any & CORBA::Any::operator=(const CORBA::Any & InitAny)
InitAny
Value
. If Release
is CORBA_TRUE
, the
Any assumes ownership and deep-copies the InitAny
argument’s value; if Release is CORBA_FALSE
, the Any shallow-copies the InitAny
argument’s value.
This is the assignment operator for the Any class. Memory management of this member function is determined by the current value of the Release
flag. The current value of the Release
flag determines whether the current memory is released before the assignment. If the current Release
flag is CORBA_TRUE
, the Any releases any value previously held; if the current Release flag is CORBA_FALSE
, the Any does not release any value previously held.
InitAny
.
Type safe Any insertion operators.
void CORBA::Any::operator<<=(CORBA::Short Value)
void CORBA::Any::operator<<=(CORBA::UShort Value)
void CORBA::Any::operator<<=(CORBA::Long Value)
void CORBA::Any::operator<<=(CORBA::Ulong Value)
void CORBA::Any::operator<<=(CORBA::Float Value)
void CORBA::Any::operator<<=(CORBA::Double Value)
void CORBA::Any::operator<<=(const CORBA::Any & Value)
void CORBA::Any::operator<<=(const char * Value)
void CORBA::Any::operator<<=(Object_ptr Value)
Value
This insertion member function performs type-safe insertions. If the Any had a previous value, and the Release
flag is CORBA_TRUE
, the memory is deallocated and the previous TypeCode object reference is freed. The new value is inserted into the Any by copying the value passed in using the Value
parameter. The appropriate TypeCode reference is duplicated.
Type safe Any extraction operators.
CORBA::Boolean CORBA::Any::operator>>=(
CORBA::Short & Value) const
CORBA::Boolean CORBA::Any::operator>>=(
CORBA::UShort & Value) const
CORBA::Boolean CORBA::Any::operator>>=(
CORBA::Long & Value) const
CORBA::Boolean CORBA::Any::operator>>=(
CORBA::Ulong & Value) const
CORBA::Boolean CORBA::Any::operator>>=(
CORBA::Float & Value) const
CORBA::Boolean CORBA::Any::operator>>=(
CORBA::Double & Value) const
CORBA::Boolean CORBA::Any::operator>>=(CORBA::Any & Value) const
CORBA::Boolean CORBA::Any::operator>>=(char * & Value) const
CORBA::Boolean CORBA::Any::operator>>=(Object_ptr & Value) const
The Value
argument is a reference to the relevant object that receives the output of the value contained in the Any object.
This extraction member function performs type-safe extractions. If the Any object contains the specified type, this member function assigns the pointer of the Any to the output reference value, Value
, and CORBA_TRUE
is returned. If the Any does not contain the appropriate type, CORBA_FALSE
is returned. The caller must not attempt to release or delete the storage because it is owned and managed by the Any object. The Value
argument is a reference to the relevant object that receives the output of the value contained in the Any object. If the Any object does not contain the appropriate type, the value remains unchanged.
CORBA_TRUE
if the Any contained a value of the specific type. CORBA_FALSE
if the Any did not contain a value of the specific type.
Type safe insertion operators for Any.
void CORBA::Any::operator<<=(from_boolean Value)
void CORBA::Any::operator<<=(from_char Value)
void CORBA::Any::operator<<=(from_octet Value)
void CORBA::Any::operator<<=(from_string Value)
Value
These insertion member functions perform a type-safe insertion of a CORBA::Boolean
, a CORBA::Char,
or a CORBA::Octet
reference into an Any. If the Any had a previous value, and its Release
flag is CORBA_TRUE
, the memory is deallocated and the previous TypeCode object reference is freed. The new value is inserted into the Any object by copying the value passed in using the Value
parameter. The appropriate TypeCode reference is duplicated.
Type-safe extraction operators for Any.
CORBA::Boolean CORBA::Any::operator>>=(to_boolean Value) const
CORBA::Boolean CORBA::Any::operator>>=(to_char Value) const
CORBA::Boolean CORBA::Any::operator>>=(to_octet Value) const
CORBA::Boolean CORBA::Any::operator>>=(to_object Value) const
CORBA::Boolean CORBA::Any::operator>>=(to_string Value) const
Value
These extraction member functions perform a type-safe extraction of a CORBA::Boolean
, a CORBA::Char
, a CORBA::Octet
, a CORBA::Object
, or
a String
reference from an Any. These member functions are helpers nested in the Any class. Their purpose is to distinguish extractions of the OMG IDL types: Boolean, char, and octet (C++ does not require these to be distinct types).
If the Any contains the specified type, this member function assigns the value in the Any object reference to the output variable, Value
, and returns CORBA_TRUE
. If the Any object does not contain the appropriate type, CORBA_FALSE
is returned.
CORBA::TypeCode_ptr CORBA::Any::type();
This function returns the TypeCode_ptr
pseudo-object reference of the TypeCode object associated with the Any. The TypeCode_ptr
pseudo-object reference must be released by the CORBA::release
member function or must be assigned to a TypeCode_var
to be automatically released.
TypeCode_ptr
contained in the Any.
void CORBA::Any::replace(TypeCode_ptr TC, void * Value,
Boolean Release = CORBA_FALSE);
TC
Value
Release
Release
is CORBA_TRUE
, the Any assumes ownership. If Release
is CORBA_FALSE
, the Any does not assume ownership and the data pointed to by the Value
parameter is not released upon assignment or destruction.
These member functions replace the data and TypeCode value currently contained in the Any with the value of the TC and Value
arguments passed in. The functions perform a nontype-safe replacement, which means that the caller is responsible for consistency between the TypeCode value and the data type of the storage pointed to by the Value
argument.
If the value of Release is CORBA_TRUE
, this function releases the existing TypeCode pseudo-object in the Any object and frees the storage pointed to be the Any object reference.
A Context supplies optional context information associated with a method invocation.
The mapping of these member functions to C++ is as follows:
class CORBA
{
class Context
{
public:
const char *context_name() const;
Context_ptr parent() const;
void create_child(const char *, Context_out);
void set_one_value(const char *, const Any &);
void set_values(NVList_ptr);
void delete_values(const char *);
void get_values(
const char *,
Flags,
const char *,
NVList_out
);
}; // Context
}// CORBA
Context has the following special memory management rule:
This section describes Context member functions.
Returns the name of a given Context object.
Const char * CORBA::Context::context_name () const;
This member function returns the name of a given Context object. The Context object reference owns the memory for the returned
char *. Users should not modify this memory.
If the member function succeeds, it returns the name of the Context object. The value may be empty if the Context object is not a child Context created by a call to CORBA::Context::create_child
.
If the Context object has no name, this is an empty string.
Creates a child of the Context object.
void CORBA::Context::create_child (
const char * CtxName,
CORBA::Context_out CtxObject);
CtxName
CtxObject
This member function creates a child of the Context object. That is, searches on the child Context object will look for matching property names in the parent context (and so on, up the context tree), if necessary.
CORBA::ORB::get_default_context
CORBA::release
Deletes the values for a specified attribute in the Context object.
void CORBA::Context::delete_values (
const char * AttrName);
AttrName
CORBA::BAD_PARAM
if attribute is an empty string.CORBA::BAD_CONTEXT
if no matching attributes to be deleted were found.
This member function deletes named values for an attribute in the Context object. Note that it does not recursively do the same to its parents, if any.
CORBA::Context::create_child
CORBA::ORB::get_default_context
Retrieves the values for a given attribute in the Context object within the specified scope.
void CORBA::Context::get_values (
const char * StartScope,
CORBA::Flags OpFlags,
const char * AttrName,
CORBA::NVList_out AttrValues);
StartScope
parent
, at which the search is started. If the value is 0 (zero), the search begins with the current Context object.
OpFlags
CORBA::CTX_RESTRICT_SCOPE
. If you specify this flag, the object implementation restricts the property search to the current scope only (that is, the property search is not executed recursively up the chain of the parent context); otherwise, the search continues to a wider scope until a match has been found or until all wider levels have been searched.
AttrName
AttrValues
NVList
object) where each item in the list is a NamedValue
.
CORBA::BAD_PARAM
if attribute is an empty string.CORBA::BAD_CONTEXT
if no matching attributes were found.CORBA::NO_MEMORY
if dynamic memory allocation failed.
This member function retrieves the values for a specified attribute in the Context object. These values are returned as an NVList object, which must be freed when no longer needed using the CORBA::release
member function.
CORBA::Context::create_child
CORBA::ORB::get_default_context
Returns the parent context of the Context object.
CORBA::Context_ptr CORBA::Context::parent () const;
This member function returns the parent context of the Context object. The parent of the Context object is an attribute owned by the Context and should not be modified or freed by the caller. This parent is nil unless the Context object was created using the CORBA::Context::create_child
member function.
If the member function succeeds, the parent context of the Context object is returned. The parent context may be nil. Use the CORBA::is_nil
member function to test for a nil object reference.
If the member function does not succeed, an exception is thrown. Use the CORBA::is_nil
member function to test for a nil object reference.
Sets the value for a given attribute in the Context object.
void CORBA::Context::set_one_value (
const char * AttrName,
const CORBA::Any & AttrValue);
AttrName
AttrValue
CORBA::Any
object with a string inside.
CORBA::BAD_PARAM
if AttrName
is an empty string or AttrValue
does not contain a string type.CORBA::NO_MEMORY
if dynamic memory allocation failed.
This member function sets the value for a given attribute in the Context object. Currently, only string values are supported by the Context object. If the Context object already has an attribute with the given name, it is deleted first.
CORBA::Context::get_values
CORBA::Context::set_values
Sets the values for given attributes in the Context object.
void CORBA::Context::set_values (
CORBA::NVList_ptr AttrValue);
AttrValues
CORBA::Any
objects with a string inside.
CORBA::BAD_PARAM
if any of the attribute values has a value that is not a string type.CORBA::NO_MEMORY
if dynamic memory allocation failed.
This member function sets the values for given attributes in the Context object. The CORBA::NVList
member function contains the property name and value pairs to be set.
CORBA::Context::get_values
CORBA::Context::set_one_value
The ContextList allows a client or server application to provide a list of context strings that must be supplied with Request invocation. For a description of the Request member functions, see the section Request Member Functions on page 14-95.
The ContextList differs from the Context in that the former supplies only the context strings whose values are to be looked up and sent with the request invocation (if applicable), while the latter is where those values are obtained. For a description of the Context member functions, see the section Context Member Functions.
The mapping of these member functions to C++ is as follows:
class CORBA
{
class ContextList
{
public:
Ulong count ();
void add(const char* ctxt);
void add_consume(char* ctxt);
const char* item(Ulong index);
Status remove(Ulong index);
}; // ContextList
}// CORBA
Retrieves the current number of items in the list.
Ulong count ();
If the function does not succeed, an exception is thrown.
This member function retrieves the current number of items in the list.
If the function succeeds, the returned value is the number of items in the list. If the list has just been created, and no ContextList objects have been added, this function returns 0 (zero).
CORBA::ContextList::add
CORBA::ContextList::add_consume
CORBA::ContextList::item
CORBA::ContextList::remove
Constructs a ContextList object with an unnamed item, setting only the flags
attribute.
void add(const char* ctxt);
ctxt
If the member function does not succeed, a CORBA::NO_MEMORY
exception is thrown.
This member function constructs a ContextList object with an unnamed item, setting only the flags attribute.
The ContextList object grows dynamically; your application does not need to track its size.
If the function succeeds, the return value is a pointer to the newly created ContextList object.
CORBA::ContextList::add_consume
CORBA::ContextList::count
CORBA::ContextList::item
CORBA::ContextList::remove
Constructs a ContextList object.
void add_consume(const char* ctxt);
If the member function does not succeed, an exception is raised.
This member function constructs a ContextList object.
The ContextList object grows dynamically; your application does not need to track its size.
If the function succeeds, the return value is a pointer to the newly created ContextList object.
CORBA::ContextList::add
CORBA::ContextList::count
CORBA::ContextList::item
CORBA::ContextList::remove
Retrieves a pointer to the ContextList object, based on the index passed in.
const char* item(ULong index);
index
If this function does not succeed, the BAD_PARAM
exception is thrown.
This member function retrieves a pointer to a ContextList object, based on the index passed in. The function uses zero-based indexing.
If the function succeeds, the return value is a pointer to the ContextList object.
CORBA::ContextList::add
CORBA::ContextList::add_consume
CORBA::ContextList::count
CORBA::ContextList::remove
Removes the item at the specified index, frees any associated memory, and reorders the remaining items on the list.
Status remove(ULong index);
Index
If this function does not succeed, the BAD_PARAM
exception is thrown.
This member function removes the item at the specified index, frees any associated memory, and reorders the remaining items on the list.
CORBA::ContextList::add
CORBA::ContextList::add_consume
CORBA::ContextList::count
CORBA::ContextList::item
NamedValue is used only as an element of NVList, especially in the DII. NamedValue maintains an (optional) name, an any
value, and labelling flags. Legal flag values are CORBA::ARG_IN
, CORBA::ARG_OUT
, and CORBA::ARG_INOUT
.
The value in a NamedValue may be manipulated via standard operations on any
.
The mapping of these member functions to C++ is as follows:
// C++
class NamedValue
{
public:
Flags flags() const;
const char * name() const;
Any * value() const;
};
NamedValue has the following special memory management rule:
The following sections describe NamedValue member functions.
Retrieves the flags attribute of the NamedValue object.
CORBA::Flags CORBA::NamedValue::flags () const;
This member function retrieves the flags attribute of the NamedValue object.
If the function succeeds, the return value is the flags attribute of the NamedValue object.
If the function does not succeed, an exception is thrown.
Retrieves the name attribute of the NamedValue object.
const char * CORBA::NamedValue::name () const;
This member function retrieves the name attribute of the NamedValue object. The name returned by this member function is owned by the NamedValue object and should not be modified or released.
If the function succeeds, the value returned is a constant Identifier object representing the name attribute of the NamedValue object.
If the function does not succeed, an exception is thrown.
Retrieves a pointer to the value attribute of the NamedValue object.
CORBA::Any * CORBA::NamedValue::value () const;
This member function retrieves a pointer to the Any object that represents the value attribute of the NamedValue object. This attribute is owned by the NamedValue object, and should not be modified or released.
If the function succeeds, the return value is a pointer to the
Any object contained in the NamedValue object.
If the function does not succeed, an exception is thrown.
NVList is a list of NamedValues. A new NVList is constructed using the ORB::create_list
operation (see CORBA::ORB::create_exception_list). New NamedValues may be constructed as part of an NVList, in any of following ways:
Each of these operations returns the new item.
Elements may be accessed and deleted via zero-based indexing. The add
, add_item
, add_value
, add_item_consume
, and add_value_consume
functions lengthen the NVList
to hold the new element each time they are called. The item
function can be used to access existing elements.
// C++
class NVList
{
public:
ULong count() const;
NamedValue_ptr add(Flags);
NamedValue_ptr add_item(const char*, Flags);
NamedValue_ptr add_value(const char*, const Any&, Flags);
NamedValue_ptr item(ULong);
void remove(ULong);
};
NVList has the following special memory management rules:
add
, add_item
, add_value
, add_item_consume
, add_value_consume
, and item
functions is maintained by the NVList; these return values must not be freed by the caller. char*
parameters to the add_item_consume
and add_value_consume
functions and the Any*
parameter to the add_value_consume
function are consumed by the NVList. The caller may not access these data after they have been passed to these functions because the NVList may copy them and destroy the originals immediately. The caller should use the NamedValue::value()
operation to modify the value
attribute of the underlying NamedValue, if desired.remove
function also calls CORBA::release
on the removed NamedValue.The following sections describe NVList member functions.
Constructs a NamedValue object with an unnamed item, setting only the flags
attribute.
CORBA::NamedValue_ptr CORBA::NVList::add (
CORBA::Flags Flags);
Flags
CORBA::ARG_IN
CORBA::ARG_INOUT
CORBA::ARG_OUT
This member function constructs a NamedValue object with an unnamed item, setting only the flags attribute. The NamedValue object is added to the NVList object that the call was invoked upon.
The NVList object grows dynamically; your application does not need to track its size.
If the function succeeds, the return value is a pointer to the newly created NamedValue object. The returned NamedValue object reference is owned by the NVList and should not be released.
If the member function does not succeed, a CORBA::NO_MEMORY
exception is thrown.
CORBA::NVList::add
CORBA::NVList::add_item
CORBA::NVList::add_value
CORBA::NVList::count
CORBA::NVList::remove
Constructs a NamedValue object, creating an empty value attribute and initializing the name and flags attributes.
CORBA::NamedValue_ptr CORBA::NVList::add_item (
const char * Name,
CORBA::Flags Flags);
Name
Flags
CORBA::ARG_IN
CORBA::ARG_INOUT
CORBA::ARG_OUT
This member function constructs a NamedValue object, creating an empty value attribute and initializing the name and flags attributes that pass in as parameters. The NamedValue object is added to the NVList object that the call was invoked upon.
The NVList object grows dynamically; your application does not need to track its size.
If the function succeeds, the return value is a pointer to the newly created NamedValue object. The returned NamedValue object reference is owned by the NVList and should not be released.
If the member function does not succeed, an exception is thrown.
CORBA::NVList::add
CORBA::NVList::add_value
CORBA::NVList::count
CORBA::NVList::item
CORBA::NVList::remove
Constructs a NamedValue object, initializing the name, value, and flags attribute.
CORBA::NamedValue_ptr CORBA::NVList::add_value (
const char * Name,
const CORBA::Any & Value,
CORBA::Flags Flags);
Name
Value
Flags
CORBA::ARG_IN
CORBA::ARG_INOUT
CORBA::ARG_OUT
This member function constructs a NamedValue object, initializing the name, value, and flags attributes. The NamedValue object is added to the NVList object that the call was invoked upon.
The NVList object grows dynamically; your application does not need to track its size.
If the function succeeds, the return value is a pointer to the newly created NamedValue object. The returned NamedValue object reference is owned by the NVList and should not be released.
If the member function does not succeed, an exception is raised.
CORBA::NVList::add
CORBA::NVList::add_item
CORBA::NVList::count
CORBA::NVList::item
CORBA::NVList::remove
Retrieves the current number of items in the list.
CORBA::ULong CORBA::NVList::count () const;
This member function retrieves the current number of items in the list.
If the function succeeds, the returned value is the number of items in the list. If the list has just been created, and no NamedValue objects have been added, this function returns 0 (zero).
If the function does not succeed, an exception is thrown.
CORBA::NVList::add
CORBA::NVList::add_item
CORBA::NVList::add_value
CORBA::NVList::item
CORBA::NVList::remove
Retrieves a pointer to the NamedValue object, based on the index passed in.
CORBA::NamedValue_ptr CORBA::NVList::item (
CORBA::ULong Index);
Index
If this function does not succeed, the BAD_PARAM
exception is thrown.
This member function retrieves a pointer to a NamedValue object, based on the index passed in. The function uses zero-based indexing.
If the function succeeds, the return value is a pointer to the NamedValue object. The returned NamedValue object reference is owned by the NVList and should not be released.
CORBA::NVList::add
CORBA::NVList::add_item
CORBA::NVList::add_value
CORBA::NVList::count
CORBA::NVList::remove
Removes the item at the specified index, frees any associated memory, and reorders the remaining items on the list.
void CORBA::NVList::remove (
CORBA::ULong Index);
Index
If this function does not succeed, the BAD_PARAM
exception is thrown.
This member function removes the item at the specified index, frees any associated memory, and reorders the remaining items on the list.
CORBA::NVList::add
CORBA::NVList::add_item
CORBA::NVList::add_value
CORBA::NVList::count
CORBA::NVList::item
The rules in this section apply to the OMG IDL interface Object, which is the base of the OMG IDL interface hierarchy. Interface Object defines a normal CORBA object, not a pseudo-object. However, it is included here because it references other pseudo-objects.
In addition to other rules, all operation names in interface Object have leading underscores in the mapped C++ class. Also, the mapping for create_request
is divided into three forms, corresponding to the usage styles described in the section Request Member Functions. The is_nil
and release
functions are provided in the CORBA namespace, as described in Object Member Functions.
The Oracle Tuxedo software uses object reference operations that are defined by CORBA Revision 2.2. These operations depend only on type Object
, so they can be expressed as regular functions within the CORBA namespace.
Note: | Because the Oracle Tuxedo software uses the POA and not the BOA, the deprecated get_implementation() member function is not visible; you will get a compile error if you attempt to reference it. |
The mapping of these member functions to C++ is as follows:
class CORBA
ExceptionList_ptr Except_list,
{
class Object
{
public:
CORBA::Boolean _is_a(const char *)
CORBA::Boolean _is_equivalent();
CORBA::Boolean _nonexistent(Object_ptr);
static Object_ptr _duplicate(Object_ptr obj);
static Object_ptr _nil();
InterfaceDef_ptr _get_interface();
CORBA::ULong _hass(CORBA::ULong);
void _create_request(
Context_ptr ctx,
const char *operation,
NVList_ptr arg_list,
NamedValue_ptr result,
Request_out request,
Flags req_flags
);
Status _create_request(
Context_ptr ctx,
const char * operation,
NVList_ptr arg_list,
NamedValue_ptr result,
ContextList_ptr Context_list,Request_out request,
Flags req_flags
);
Request_ptr _request(const char* operation);
}; //Object
}; // CORBA
The following sections describe the Object
member functions.
Creates a request with user-specified information.
Void CORBA::Object::_create_request (
CORBA::Context_ptr Ctx,
const char * Operation,
CORBA::NVList_ptr Arg_list,
CORBA::NamedValue_ptr Result,
CORBA::ExceptionList_ptr Except_list,
CORBA::ContextList_ptr Context_list,
CORBA::Request_out Request,
CORBA::Flags Req_flags,);
Ctx
Operation
Arg_list
Result
Except_list
Context_list
Request
Req_flags
This member function creates a request that provides information on context, operation name, and other values (long form). To create a request with just the operation name supplied at the time of the call (short form), use the CORBA::Object::_request
member function. The remainder of the information provided in the long form eventually needs to be supplied.
Duplicates the Object object reference.
CORBA::Object_ptr CORBA::Object::_duplicate(
Object_ptr Obj);
obj
This member function duplicates the specified Object object reference (Obj
). If the given object reference is nil, the _duplicate
function returns a nil object reference. The object returned by this call should be freed using CORBA::release
, or should be assigned to CORBA::Object_var
for automatic destruction.
This function can throw CORBA system exceptions.
Returns the duplicate object reference. If the specified object reference is nil, a nil object reference is returned.
CORBA::Object_ptr op = TP::create_object_reference(
"IDL:Teller:1.0","MyTeller");
CORBA::Object_ptr dop = CORBA::Object::_duplicate(op);
Returns an interface definition for the Repository object.
CORBA::InterfaceDef_ptr CORBA::Object::_get_interface ();
Returns an interface definition for the Repository object.
Note: | To use the Repository Interface API, define a macro before CORBA.h is included. For information about how to define a macro, see Creating CORBA Server Applications. |
Determines whether an object is of a certain interface.
CORBA::Boolean CORBA::Object::_is_a(const char * interface_id);
interface_id
This member function is used to determine if an object is an instance of the interface that you specify in the interface_id
parameter. It facilitates maintaining type-safety for object references over the scope of an ORB.
Returns TRUE
if the object is an instance of the specified type, or if the object is an ancestor of the “most derived” type of that object.
CORBA::Object_ptr op = TP::create_object_reference(
"IDL:Teller:1.0", "MyTeller");
CORBA::Boolean b = op->_is_a("IDL:Teller:1.0");
Determines if two object references are equivalent.
CORBA::Boolean CORBA::Object::_is_equivalent (
CORBA::Object_ptr other_obj);
other_obj
Can throw a standard CORBA exception.
This member function is used to determine if two object references are equivalent, so far as the ORB can easily determine. It returns TRUE
if your object reference is equivalent to the object reference you pass as a parameter. If two object references are identical, they are equivalent. Two different object references that refer to the same object are also equivalent.
Returns TRUE
if the target object reference is known to be equivalent to the other object reference passed as a parameter; otherwise, it returns FALSE
.
CORBA::Object_ptr op = TP::create_object_reference(
"IDL:Teller:1.0", "MyTeller");
CORBA::Object_ptr dop = CORBA::Object::_duplicate(op);
CORBA::Boolean b = op->_is_equivalent(dop);
Returns a reference to a nil object.
CORBA::Object_ptr CORBA::Object::_nil();
This member function returns a nil object reference. To test whether a given object is nil, use the appropriate CORBA::is_nil
member function (see the section CORBA::release). Calling the CORBA:is_nil
routine on any _nil
member function always yields CORBA_TRUE
.
Returns a nil object reference.
CORBA::Object_ptr op = CORBA::Object::_nil();
May be used to determine if an object has been destroyed.
CORBA::Boolean CORBA::Object::_non_existent();
This member function may be used to determine if an object has been destroyed. It does this without invoking any application-level operation on the object, and so will never affect the object itself.
Returns CORBA_TRUE
(rather than raising CORBA::OBJECT_NOT_EXIST
) if the ORB knows authoritatively that the object does not exist; otherwise, it returns CORBA_FALSE
.
Creates a request specifying the operation name.
CORBA::Request_ptr CORBA::Object::_request (
const char * Operation);
Operation
This member function creates a request specifying the operation name. All other information, such as arguments and results, must be populated using CORBA::Request
member functions.
If the member function succeeds, the return value is a pointer to the newly created request.
If the member function does not succeed, an exception is thrown.
CORBA::Object::_create_request
This section describes the Object and Pseudo-Object Reference member functions.
The mapping of these member functions to C++ is as follows:
class CORBA {
void release(Object_ptr);
void release(Environment_ptr);
void release(NamedValue_ptr);
void release(NVList_ptr);
void release(Request_ptr);
void release(Context_ptr);
void release(TypeCode_ptr);
void release(POA_ptr);
void release(ORB_ptr);
void release(ExceptionList_ptr);
void release(ContextList_ptr);
Boolean is_nil(Object_ptr);
Boolean is_nil(Environment_ptr);
Boolean is_nil(NamedValue_ptr);
Boolean is_nil(NVList_ptr);
Boolean is_nil(Request_ptr);
Boolean is_nil(Context_ptr);
Boolean is_nil(TypeCode_ptr);
Boolean is_nil(POA_ptr);
Boolean is_nil(ORB_ptr);
Boolean is_nil(ExceptionList_ptr);
Boolean is_nil(ContextList_ptr);
hash(maximum);
resolve_initial_references(identifier);
...
};
Allows allocated resources to be released for the specified object type.
void CORBA::release(spec_object_type obj);
obj
This member function indicates that the caller will no longer access the reference so that associated resources may be deallocated. If the specified object reference is nil, the release operation does nothing. If the ORB instance release is the last reference to the ORB, then the ORB will be shut down prior to its destruction. This is the same as calling ORB_shutdown
prior to calling CORBA::release
. This only applies to the release
member function called on the ORB.
This member function may not throw CORBA exceptions.
CORBA::Object_ptr op = TP::create_object_reference(
"IDL:Teller:1.0", "MyTeller");
CORBA::release(op);
Determines if an object exists for the specified object type.
CORBA::Boolean CORBA::is_nil(spec_object_type obj);
obj
This member function is used to determine if a specified object reference is nil. It returns TRUE if the object reference contains the special value for a nil object reference as defined by the ORB.
This operation may not throw CORBA exceptions.
Returns TRUE
if the specified object is nil; otherwise, returns FALSE
.
CORBA::Object_ptr op = TP::create_object_reference(
"IDL:Teller:1.0", "MyTeller");
CORBA::Boolean b = CORBA::is_nil(op);
Provides indirect access to object references using identifiers internal to the ORB.
CORBA::hash(CORBA::ULong maximum);
maximum
Object references are associated with ORB-internal identifiers that may indirectly be accessed by applications using the hash() operation. The value of this identifier does not change during the lifetime of the object reference, and so neither will any hash function of that identifier.
The value of this operation is not guaranteed to be unique; that is, another object reference may return the same hash value. However, if two object references hash differently, applications can determine that the two object references are not identical.
The maximum parameter to the hash operation specifies an upper bound on the hash value returned by the ORB. The lower bound of that value is zero. Since a typical use of this feature is to construct and access a collision-chained hash table of object references, the more randomly distributed the values are within that range, and the less expensive those values are to compute, the better.
Returns an initial object reference corresponding to an identifier
string.
CORBA::Object_ptr CORBA::resolve_initial_references(
const CORBA::char *identifier);
identifier
Returns an initial object reference corresponding to an identifier
string. Valid identifiers are “RootPOA”
and “POACurrent”
.
Note: | This function is supported only for a joint client/server. |
CORBA::ORB_ptr orb = CORBA::ORB_init(argc, argv);
CORBA::Object_ptr pfobj =
orb->resolve_initial_references("RootPOA");
PortableServer::POA_ptr rootPOA;
rootPOA = PortableServer::POA::narrow(pfobj);
The ORB member functions constitute the programming interface to the Object Request Broker.
The mapping of the ORB member functions to C++ is as follows:
class CORBA
{
class ORB
{
public:
char *object_to_string(Object_ptr);
Object_ptr string_to_object(const char *);
void create_list(Long, NVList_out);
void create_operation_list(operationDef_ptr, NVList_out);
void create_named_value(NamedValue_out);
void create_exception_list(ExceptionList_out);
void create_context_list(ContextList_out);
void get_default_context(Context_out);
void create_environment(Environment_out);
void send_multiple_requests_oneway(const requestSeq&);
void send_multiple_requests_deferred(const requestSeq&);
Boolean poll_next_response();
void get_next_response(Request_out);
Boolean work_pending();
void perform_work();
void create_policy (in PolicyType type, in any val);
// Extension
void destroy();
// Extensions to support sharing context between threads
void Ctx get_ctx() = 0;
void set_ctx(Ctx) = 0;
void clear_ctx() = 0;
// Thread extensions
void inform_thread_exit(TID) = 0;
}; //ORB
}; // CORBA
To support single-threaded ORBs, as well as multithreaded ORBs that run multithread-unaware code, two operations (perform_work
and work_pending
) are included in the ORB interface. These operations can be used by single-threaded and multithreaded applications. An application that is a pure ORB client would not need to use these operations.
To support multithreaded server applications, four operations (get_ctx
, set_ctx
, clear_ctx
, and inform_thread_exit)
are included as extensions to the ORB interface.
The following sections describe the ORB member functions.
Indicates that a context is no longer required by this thread. This method supports the development of a multithreaded server application.
void clear_ctx()
This method is called by an application-managed thread after the thread has finished using the context. The method removes the association between that thread and a context.
Note: | Do not call the clear_ctx method from within a thread that is managed by the Oracle Tuxedo system. The Oracle Tuxedo system performs the appropriate context propagation and cleanup automatically for the threads it manages. If this method is called on a thread managed by the Oracle Tuxedo system, the BAD_PARAM exception is thrown. |
CORBA::ORB::get_ctx
CORBA::ORB::set_ctx
Creates and returns a list of contexts.
void CORBA::ORB::create_context_list(
CORBA::ContextList_out List);
List
This member function creates and returns a list of context strings that must be supplied with the Request operation in a form that may be used in the Dynamic Invocation Interface (DII). When no longer needed, this list must be freed using the CORBA::release
member function.
void CORBA::ORB::create_environment (
CORBA::Environment_out New_env);
This member function creates an environment.
CORBA::NVList::add
CORBA::NVList::add_item
CORBA::NVList::add_value
CORBA::release
void CORBA::ORB::create_exception_list(
CORBA::ExceptionList_out List);
List
This member function creates and returns a list of exceptions in a form that may be used in the Dynamic Invocation Interface (DII). When no longer needed, this list must be freed using the CORBA::release
member function.
Creates and returns an NVList object reference.
void CORBA::ORB::create_list (
CORBA::Long NumItem,
CORBA::NVList_out List);
NumItem
List
This member function creates a list, preallocating a specified number of items. List items may be sequentially added to the list using the CORBA::NVList_add_item
member function. When no longer needed, this list must be freed using the CORBA::release
member function.
CORBA::NVList::add
CORBA::NVList::add_item
CORBA::NVList::add_value
CORBA::release
Creates a NamedValue object reference.
void CORBA::ORB::create_named_value (
NameValue_out NewNamedVal);
NewNamedVal
This member function creates a NamedValue object. Its intended use is for the result argument of a request that needs a NamedValue object. The extra steps of creating an NVList object are avoided by calling this member function.
When no longer needed, the NamedValue object must be freed using the CORBA::release
member function.
CORBA::NVList::add
CORBA::NVList::add_item
CORBA::NVList::add_value
CORBA::release
Creates and returns a list of the arguments of a specified operation.
void CORBA::ORB::create_operation_list (
CORBA::OperationDef_ptr Oper,
CORBA::NVList_out List);
Oper
List
This member function creates and returns a list of the arguments of a specified operation, in a form that may be used with the Dynamic Invocation Interface (DII). When no longer needed, this list must be freed using the CORBA::release
member function.
CORBA::OBB::create_list
CORBA::NVList::add
CORBA::NVList::add_item
CORBA::NVList::add_value
CORBA::release
Creates new instances of policy objects of a specific type with specified initial state.
void CORBA::ORB::create_policy (
in PolicyType type,
in any val);
type
BiDirPolicy::BIDIRECTIONAL_POLICY_TYPE
is the only PolicyType
value supported for Oracle WebLogic Enterprise version 4.2.
val
val
value supported for Oracle WebLogic Enterprise V4.2 is BiDirPolicy::BidirectionalPolicyValue
.
PolicyError
ORB::create_policy
operation. The specific exception and reasons are as follows:
This operation can be invoked to create new instances of policy objects of a specific type with specified initial state. If create_policy
fails to instantiate a new Policy object due to its inability to interpret the requested type and content of the policy, it raises the Policy Error exception with the appropriate reason. (See Exceptions below.)
The BidirectionalPolicy
argument is provided for remote clients using callbacks because remote clients use IIOP. It is not used for native clients using callbacks or for Oracle Tuxedo servers because machines inside an Oracle Tuxedo domain communicate differently.
Before GIOP 1.2, bidirectional policy was not available as a choice in IIOP (which uses TCP/IP). Connections in GIOP 1.0 and 1.1 were one way (that is, a request flowed from a client to a server); only responses flowed from the server back to the client. If the server wanted to make a request back to the client machine (say for a callback), the server machine had to establish another one-way connection. (Be advised that “connections” in this sense mean operating system resources, not physically different wires or communication paths. A connection uses resources, so minimizing connections is desirable.)
Since this release of the Oracle Tuxedo C++ software supports GIOP 1.2, it supports reuse of the TCP/IP connection for both incoming and outgoing requests. Reusing connections saves resources when a remote client sends callback references to an Oracle Tuxedo domain. The joint client/server uses a connection to send a request to an Oracle Tuxedo domain; that connection can be reused for the callback request. If the connection is not reused, the callback request must establish another connection.
Allowing reuse of a connection is a choice of the ORB/POA that creates callback object references. The server for those object references (usually the creator of the references, especially in the callback case) might choose not to allow reuse for security considerations (that is, the outgoing connection [a client request from this machine to a remote server] may not need security because the remote server does not require it, but the callback server on this machine might require security). Since security is established partly on a connection basis, the incoming security can be established only if a separate connection is used. If the remote server requires security, and if that security involves a mutual authentication, the local server usually feels safe in allowing reuse of the connection.
Since the choice of connection reuse is at the server end, whenever a process acts as a server—in this case a joint client/server—and creates object references, it must inform the ORB that it is willing to reuse connections. The process does this by setting a policy on the POA that creates the object references. The default policy is to not allow reuse (that is, if you do not supply a policy object for reuse, the POA does not allow reuse).
This default allows for backward compatibility with code written before CORBA version 2.3. Such code did not know that reuse was possible so it did not have to take into consideration the security implications of reuse. Thus, that unchanged code should continue to disallow reuse until the user considers security and explicitly makes a decision to the contrary.
To allow reuse, you use the create_policy
operation to create a policy object that allows reuse, and use that policy object as part of the list of policies for POA creation.
#include <BiDirPolicy_c.h>
BiDirPolicy::BidirectionalPolicy_var bd_policy;
CORBA::Any allow_reuse;
allow_reuse <<= BiDirPolicy::BOTH;
CORBA::Policy_var generic_policy =
orb->create_policy( BiDirPolicy::BIDIRECTIONAL_POLICY_TYPE,
allow_reuse );
bd_policy = BiDirPolicy::BidirectionalPolicy::_narrow(
generic_policy );
In the above example, the bd_policy
would then be placed in the PolicyList passed to the create_poa
operation.
void destroy();
Use this method to destroy an ORB so that the resources associated with that ORB can be reclaimed. Once an ORB has been destroyed, another invocation on the ORB_init
method with the same ORB ID returns a reference to a newly constructed ORB. If an application invokes the ORB::destroy
method from a thread that is currently servicing an invocation, the Oracle Tuxedo system raises the BAD_INV_ORDER
system exception with the OMG minor code 3, because blocking would result in a deadlock.
Retrieves the context associated with the current thread. This method supports the development of a multithreaded server application.
CORBA::ORB::Ctx get_ctx()
CORBA::ORB::Ctx
Use this method to retrieve the context associated with the current thread. This context can then be used to initialize other threads that the application creates and manages.
When an object creates a thread, the object invokes this operation on the ORB to obtain system context information that the object can pass on to the thread. This operation must be called from a thread that already has a context. For example, the thread in which a method was dispatched will already have a content.
thread.context = TP::orb()->get_ctx();
CORBA::ORB::set_ctx
CORBA::ORB::clear_ctx
Returns a reference to the default context.
void CORBA::ORB::get_default_context
(
CORBA::Context_out
ContextObj);
ContextObj
This member function returns a reference to the default context. When no longer needed, this context reference must be freed using the CORBA::release
member function.
CORBA::Context::get_one_value
CORBA::Context::get_values
Determines and reports the next deferred synchronous request that completes.
void CORBA::ORB::get_next_response (
CORBA::Request_out RequestObj);
RequestObj
This member function returns a reference to the next request that completes. If no requests have completed, the function waits for a request to complete. This member function returns the next request on the queue, in contrast to the CORBA::Request::get_response
member function, which waits for a particular request to complete. When no longer needed, this request must be freed using the CORBA::release
member function.
CORBA::ORB::poll_next_response
CORBA::Request::get_reponse
Informs the Oracle Tuxedo system that resources associated with an application-managed thread can be released. This method supports the development of a multithreaded server application.
void CORBA::ORB::inform_thread_exit(CORBA::TID threadId
)
threadId
This method informs the Oracle Tuxedo system about the following conditions:
Note: | You should only call this operation on threads that the application creates and manages. Do not invoke this method when specifying a dispatch thread that is managed by the Oracle Tuxedo system. |
pOrb->inform_thread_exit(thread.threadId);
Determines which objects have references available via the initial references mechanism.
typedef string ObjectId;
typedef sequence ObjectId
ObjectIdList;
ObjectIdList list_initial_services ();
ObjectId
list_initial_services ()
This operation is used by applications to determine which objects have references available via the initial references mechanism. This operation returns an ObjectIdList
, which is a sequence of ObjectIds
. ObjectIds
are typed as strings.
Each object, which may need to be made available at initialization time, is allocated a string value to represent it. In addition to defining the ID, the type of object being returned must be defined, that is, InterfaceRepository
returns an object of type Repository
, and NameService
returns a CosNamingContext
object.
CORBA::ORB::resolve_initial_references
Produces a string representation of an object reference.
char * CORBA::ORB::object_to_string (
CORBA::Object_ptr ObjRef);
ObjRef
This member function produces a string representation of an object reference. The calling program must use the CORBA::string_free
member function to free the string memory after it is no longer needed.
The string representing the specified object reference.
CORBA::Object_ptr op = TP::create_object_reference(
"IDL:Teller:1.0", "MyTeller");
char* objstr = TP::orb()->object_to_string(op);
CORBA::ORB::string_to_object
CORBA::string_free
Allows the ORB to perform server-related work.
void CORBA::ORB::perform_work ();
None.
Once the ORB has shut down, a call to work_pending
and perform_work()
raises the BAD_INV_ORDER
exception. An application can detect this exception to determine when to terminate a polling loop.
If called by the main thread, this operation allows the ORB to perform server-related work. Otherwise, it does nothing.
The work_pending()
and perform_work()
operations can be used to write a simple polling loop that multiplexes the main thread among the ORB and other activities. Such a loop would most likely be needed in a single-threaded server. A multithreaded server would need a polling loop only if there were both ORB and other code that required use of the main thread. See the example below for such a polling loop.
The following is an example of a polling loop:
// C++
for (;;) {
if (orb->work_pending()) {
orb->perform_work();
}
// do other things
// sleep?
}
Determines whether a completed request is outstanding.
CORBA::Boolean CORBA::ORB::poll_next_response ();
This member function reports on whether there is an outstanding (pending) completed request; it does not remove the request. If a completed request is outstanding, the next call to the CORBA::ORB::get_next_response
member function is guaranteed to return a request without waiting. If there are no completed requests outstanding, the CORBA::ORB::poll_next_response
member function returns without waiting (blocking).
If a completed request is outstanding, the function returns CORBA_TRUE
.
If no completed request is outstanding, the function returns CORBA_FALSE
.
Obtains object references for initial services.
Object resolve_initial_references ( in ObjectId identifier )
raises (InvalidName);
identifier
This operation is used by applications to obtain object references for initial services. The interface differs from the Naming Service’s resolve in that ObjectId
(a string) replaces the more complex Naming Service construct (a sequence of structures containing string pairs for the components of the name). This simplification reduces the namespace to one context.
ObjectIds
are strings that identify the object whose reference is required. To maintain the simplicity of the interface for obtaining initial references, only a limited set of objects are expected to have their references found via this means. Unlike the ORB identifiers, the ObjectId
name space requires careful management. To achieve this, the OMG may, in the future, define which services are required by applications through this interface and specify names for those services.
Currently, reserved ObjectIds
are RootPOA
, POACurrent
, InterfaceRepository
, NameService
, TradingService
, SecurityCurrent
, TransactionCurrent
, and DynAnyFactory
.
The application is responsible for narrowing the object reference returned from resolve_initial_references
to the type that was requested in the ObjectId
. For example, for InterfaceRepository
the object returned would be narrowed to Repository
type.
Object references for initial services.
CORBA::ORB::list_initial_services
Sends a sequence of deferred synchronous requests.
void CORBA::ORB::send_multiple_requests_deferred (
const CORBA::ORB::RequestSeq & Reqs);
Reqs
CORBA::ORB::RequestSeq
in the section Usage.
This member function sends out a sequence of requests and returns control to the caller without waiting for the operation to complete. The caller uses CORBA::ORB::poll_ next_response
, CORBA::ORB::get_next_response
, or CORBA::Rquest::get_response
or all three to determine if the operation has completed and if the output arguments have been updated.
CORBA::Request::get_response
CORBA::ORB::get_next_response
CORBA::ORB::send_multiple_requests_oneway
Sends a sequence of one-way, deferred synchronous requests.
void CORBA::ORB::send_multiple_requests_oneway (
const CORBA::RequestSeq & Reqs);
Reqs
CORBA::ORB::RequestSeq
in the section Usage.
This member function sends out a sequence of requests and returns control to the caller without waiting for the operation to complete. The caller neither intends to wait for a response nor expects any output arguments to be updated.
CORBA::ORB::send_multiple_requests_deferred
Sets the context for the current thread. This method supports the development of a multithreaded server application.
void set_ctx(CORBA::ORB::Ctx aContext
)
aContext
This method sets the context for the current application-managed thread. The context parameter provided must have been obtained in a previously-executed thread that is managed by the Oracle Tuxedo system or in an application-managed thread that has already been initialized.
Note: | Do not call the set_ctx method in a thread that is managed by the Oracle Tuxedo system. The Oracle Tuxedo system performs the appropriate context propagation automatically for the threads it manages. If your application calls this method on a thread managed by the Oracle Tuxedo system, the BAD_PARAM exception is thrown. |
TP::orb()->set_ctx(thread->context);
CORBA::ORB::get_ctx()
CORBA::ORB::clear_ctx()
Converts a string produced by CORBA::ORB::object_to_string
operation and returns the corresponding object reference.
C++ Binding
Object string_to_object ( in string str );
str
This operation is used by applications to convert a string produced by CORBA::ORB::object_to_string
operation and returns the corresponding object reference.
To guarantee that an ORB will understand the string form of an object reference, that ORB’s object_to_string
operation must be used to produce the string. The string_to_object
operation allows URLs in the IOR, corbaloc, corbalocs, and corbanames formats to be converted into object references. If a conversion fails, the string_to_object
operation raises the BAD_PARAM
standard exception with one of the following minor codes:
For all conforming ORBs, if obj
is a valid reference to an object, then string_to_object(object_to_string(obj))
will return a valid reference to the same object, if the two operations are performed on the same ORB. For all conforming ORB's supporting IOP, this remains true even if the two operations are performed on different ORBs.
Returns an indication of whether the ORB needs the main thread to perform server-related work.
CORBA::boolean CORBA::ORB::work_pending ();
This operation returns an indication of whether the ORB needs the main thread to perform server-related work.
A result of TRUE
indicates that the ORB needs the main thread to perform server-related work, and a result of FALSE
indicates that the ORB does not need the main thread.
The mapping of this member function to C++ is as follows:
class CORBA {
<appl-name> [-ORBid {BEA_IIOP | BEA_TOBJ} \
static CORBA::ORB_ptr ORB_init(int& argc, char** argv,
const char* orb_identifier = 0,
const char* -ORBport nnn);
[-ORBInitRef <ObjectID>=<ObjectURL> [*]]
[-ORBDefaultInitRef <ObjectURL>]
[-ORBport port-number] \
[-ORBsecurePort port-number] \
[-ORBminCrypto {0 | 40 | 56 | 128}] \
[-ORBmaxCrypto {0 | 40 | 56 | 128}] \
[-ORBmutualAuth] \
[-ORBpeerValidate {detect | warn | none}] \
[appl-options]
};
Initializes operations for an ORB.
static CORBA::ORB_ptr ORB_init(int& argc, char** argv,
const char* orb_identifier = 0);
argc
argv
char **
) and the number of strings in the array is passed in the argc
parameter.
orb_identifier
orb_identifier
parameter is supplied, “BEA_IIOP”
explicitly specifies a remote client and “BEA_TOBJ”
explicitly specifies a native client, as defined in the section Tobj_Bootstrap.
This member function initializes operations for an ORB and returns a pointer to the ORB. When your program is done with the ORB, use the CORBA::release
member function to free the resources allocated for the ORB pointer returned from CORBA::ORB_ptr
ORB_init
.
The ORB returned has been initialized with two pieces of information to determine how it will operate: client type (remote or native) and server port number. The client type can be specified in the orb_identifier
argument, in the argv argument, or in the system registry. The server port number can be specified in the argv
argument.
The arguments argc
and argv
are typically the same parameters that were passed to the main program. As specified by C++, these parameters contain string tokens from the command line that started the client. The two ORB options can be specified on the command line, each using a pair of tokens, as shown in examples below.
The ORB_init
function determines the client type of the ORB by the following steps.
orb_identifier
argument is present, ORB_init
determines the client type, either native or remote, if the string is "BEA_IIOP"
or "BEA_TOBJ"
, respectively. If an orb_identifier
string is present, all -ORBid
parameters in the argv
are ignored (removed).orb_identifier
is not present or is explicitly zero, ORB_init
looks at the entries in argc/argv
. If argv
contains an entry with "-ORBid"
, the next entry should be either "BEA_IIOP"
or "BEA_TOBJ"
, again specifying remote or native. This pair of entries occurs if the command line contains either "-ORBid BEA_IIOP”
or "-ORBid BEA_TOBJ”
.argc/argv
, ORB_init
uses the default client type from the system registry (BEA_IIOP
or BEA_TOBJ
). The system registry was initialized at the time Oracle Tuxedo was installed.In the case of an Oracle Tuxedo remote joint client/server, in order to support IIOP, by definition, the object references created for the server part must contain a host and port. For transient object references, any port is sufficient and can be obtained by the ORB dynamically, but this is not sufficient for persistent object references. Persistent references must be served on the same port after the ORB restarts, that is, the ORB must be prepared to accept requests on the same port with which it created the object reference. Thus, there must be some way to configure the ORB to use a particular port.
Typically, a system administrator assigns the port number for the client from the “user” range of port numbers rather from the dynamic range. This keeps the joint client/servers from using conflicting ports.
To determine port number, ORB_init
searches the argv
parameter for the token "-ORBport"
and a following numeric token. For example, if the client executable is named sherry, the command line might specify that the server port should be 937 as follows:
For C++, the order of consumption of argv
parameters may be significant to an application. To ensure that applications are not required to handle argv
parameters they do not recognize, the ORB initialization function must be called before the remainder of the parameters are consumed. Therefore, after the ORB_init
call, the argv
and argc
parameters have been modified to remove the ORB understood arguments. It is important to note that the ORB_init
function can only reorder or remove references to parameters from the argv
list. This restriction is made to avoid potential memory management problems caused by trying to free parts of the argv
list or extending the argv
list of parameters. This is why argv
is passed as a char**
and not as a char**&
.
Note: | Use the CORBA::release member function to free the resources allocated for the pointer returned from CORBA::ORB_init . |
Configures applications based on the Oracle Tuxedo CORBA C++ ORB to access or provide Oracle Tuxedo CORBA objects.
<appl-name> [-ORBid {BEA_IIOP | BEA_TOBJ} \
[-ORBInitRef <ObjectID>=<ObjectURL> [*]]
[-ORBDefaultInitRef <ObjectURL>]
[-ORBport port-number] \
[-ORBsecurePort port-number] \
[-ORBminCrypto {0 | 40 | 56 | 128}] \
[-ORBmaxCrypto {0 | 40 | 56 | 128}] \
[-ORBmutualAuth] \
[-ORBpeerValidate {detect | warn | none}] \
[appl-options]
The Oracle Tuxedo CORBA C++ ORB is an Oracle Tuxedo-supplied library that enables the development of CORBA-based applications used to access or provide Oracle Tuxedo objects using IIOP or IIOP-SSL. The ORB command-line options allow for customization.
[– ORBid {BEA_IIOP | BEA_TOBJ}]
BEA_IIOP
explicitly specifies that the ORB be configured to support either a client or a server environment that communicates over the IIOP or IIOP-SSL protocol.
The value BEA_TOBJ
explicitly specifies that the ORB be configured to support the native client environment that can only communicate over the TGIOP protocol within an Oracle Tuxedo domain.
If not specified, the ORB will detect the environment in which it is deployed and configure itself for use in that environment.
[– ORBInitRef
ObjectId
=
ObjectURL
]
-ORBInitRef
, allows specification of an arbitrary object reference for an initial service.
ObjectID
represents the well-known object ID for a service that is defined in the CORBA specification. This mechanism allows an ORB to be configured with new initial service Object IDs that were not defined when the ORB was installed.
ObjectURL
can be any of the URL schemes supported by the CORBA::ORB::string_to_object
operation as defined in CORBA specification. If a URL is syntactically malformed or can be determined to be invalid in an implementation-defined manner, CORBA::ORB_init
will raise the CORBA::BAD_PARAM
standard exception listed in Table 14-1.
[– ORBDefaultInitRef <ObjectURL>]
-ORBDefaultInitRef
, assists in the resolution of initial references not explicitly specified with -ORBInitRef
. This argument provides functionality similar to that of the list of IIOP Listeners address that is provided to the current Tobj_Bootstrap
object.
Unlike the – ORBInitRef
argument, -ORBDefaultInitRef
requires a URL that, after appending a slash ‘/’ character and a stringified object key, forms a new URL to identify an initial object reference. For example, if the following was specified as the default initial reference argument:-ORBDefaultInitRef corbaloc:555objs.com
A call to ORB::resolve_initial_references(“NotificationService”)
to obtain the initial reference for the service would result in the new URL:corbaloc:555objs.com/NotificationService
The implementation of the ORB::resolve_initial_references
operation would take the newly constructed URL and call CORBA::ORB::string_to_object
to obtain the initial reference for the service.
The URL specified as the value of the -ORBDefaultInitRef
argument can contain more than a single location. This is the similar to the functionality provided for the list of locations to be used by the Tobj_Bootstrap
object. In this situation, the ORB will process the locations in the URL based on the syntax rules for the URL. For example, if the following was specified as the default initial reference argument:-ORBDefaultInitRef corbaloc:555objs.com,555Backup.com
A call to ORB::resolve_initial_references(“NameService”)
to obtain the initial reference for the service would result in one of the following new URLs:corbaloc:555objs.com/NameService
or:corbaloc:555Backup.com/NameService
The resulting URL would then be passed to CORBA::ORB::string_to_object
in order to obtain the initial reference for the service.
[– ORBminCrypto [0 | 40 | 56 | 128]]
[– ORBmaxCrypto [0 | 40 | 56 | 128]]
– ORBmaxCrypto
or – ORBmaxCrypto
options are available only if either the International or U.S_Canada Oracle Tuxedo Security Add-on Package is installed.
[– ORBmutualAuth]
– ORBmutualAuth
option is available only if either the International or U.S_Canada Oracle Tuxedo Security Add-on Package is installed.
[– ORBpeerValidate {detect | warn | none}]
detect
causes an Oracle Tuxedo CORBA ORB to verify that the host specified in the object reference used to make the connection matches the domain name specified in the peer’s digital certificate. If the comparison fails, the ORB refuses to authenticate the peer and drops the connection. This check protects against man-in-the-middle attacks.
A value of warn
causes an Oracle Tuxedo CORBA ORB to verify that the host specified in the object reference used to make the connection matches the domain name specified in the peer’s digital certificate. If the comparison fails, the ORB logs a message to the user log, but continues processing the connection.
A value of none causes an Oracle Tuxedo CORBA ORB not to perform the peer validation and will continue the processing of the connection.
The – ORBpeerValidate
option is available only if either the International or U.S_Canada Oracle Tuxedo Security Add-on Package is installed.
If not specified, the default is detect
.
[– ORBport port-number]
port-number
is the TCP port number at which the Oracle Tuxedo CORBA ORB process listens for incoming requests. The port-number
can be a number between 0 and 65535.
[– ORBsecurePort port-number]
port-number
is the TCP port number at which the Oracle Tuxedo CORBA ORB process listens for incoming requests. The port-number
can be a number between 0 and 65535.
An administrator can configure to only allow secure connections into the Oracle Tuxedo CORBA ORB by setting port numbers specified by the– ORBport
and – ORBsecurePort
to the same value.
The – ORBsecurePort
option is available only if either the International or U.S_Canada Oracle Tuxedo Security Add-on Package is installed.
The Oracle Tuxedo CORBA ORB is supported as an Oracle Tuxedo-supplied client or server on UNIX and Microsoft Windows operating systems. It is also supported as an Oracle Tuxedo-supplied client on the Windows XP operating systems.
The Oracle Tuxedo CORBA ORB will interoperate with any IIOP compliant ORB that supports the 1.0, 1.1, or 1.2 version of the GIOP protocol over a TCP/IP connection. In addition, the Oracle Tuxedo CORBA ORB will interoperate with any IIOP-SSL compliant ORB that supports the use of the TAG_SSL_SEC_TRANS
tagged component in object references and version 3 of the Secure Socket Layer protocol.
ChatClient – ORBid BEA_IIOP – ORBport 2100
-ORBDefaultInitRef corbaloc:piglet:1900
-ORBInitRef TraderService=corbaloc:owl:2530
– ORBsecurePort 2100
-ORBminCrypto 40
– ORBmaxCrypto 128
TechTopics
java – DORBDefaultInitRef=corbalocs:piglet:1900
.....-DORBInitRef=TraderService=corbaloc:owl:2530
-Dorg.omg.CORBA.ORBPort=1948
-classpath=%CLASSPATH% client
A policy is an object used to communicate certain choices to an ORB regarding its operation. This information is accessed in a structured manner using interfaces derived from the Policy interface defined in the CORBA module.
Note: | These CORBA::Policy operations and structures are not usually needed by programmers. The derived interfaces usually contain the information relevant to specifications. A policy object can be constructed by a specific factory or by using the CORBA::create_policy operation. |
The mapping of this object to C++ is as follows:
class CORBA
{
class Policy
{
public:
copy();
void destroy();
}; //Policy
typedef sequence<Policy>PolicyList;
}; // CORBA
PolicyList
is used the same as any other C++ sequence mapping. For a discussion of sequence usage, see Sequences.
POA Policy and CORBA::ORB::create_policy
.
CORBA::Policy::copy();
This operation copies the policy object. The copy does not retain any relationships that the policy had with any domain or object.
Note: | This function is supported only for a joint client/server. |
void CORBA::Policy::destroy();
If the policy object determines that it cannot be destroyed, the CORBA::NO_PERMISSION
exception is raised.
This operation destroys the policy object. It is the responsibility of the policy object to determine whether it can be destroyed.
Note: | This function is supported only for a joint client/server. |
The mapping of the PortableServer member functions to C++ is as follows:
// C++
class PortableServer
{
public:
class LifespanPolicy;
class IdAssignmentPolicy;
class POA::find_POA
class reference_to_id
class POAManager;
class POA;
class Current;
class virtual ObjectId
class ServantBase};
ObjectId
ObjectId
values may be assigned and managed by the POA, or they may be assigned and managed by the implementation. ObjectId
values are hidden from clients, encapsulated by references. ObjectIds
have no standard form; they are managed by the POA as uninterpreted octet sequences.
The following sections describe the remaining classes.
Explicitly activates an individual object.
ObjectId * activate_object (
Servant p_servant);
p_servant
If the specified servant is already in the Active Object Map, the ServantAlreadyActive
exception is raised.
Note: | Other exceptions can occur if the POA uses unsupported policies. |
This operation explicitly activates an individual object by generating an ObjectId
and entering the ObjectId
and the specified servant in the Active Object Map.
Note: | This function is supported only for a joint client/server. |
If the function succeeds, the ObjectId
is returned.
In the following example, the first struct creates a servant by a user-defined constructor. The second struct tells the POA that the servant can be used to handle requests on an object. The POA returns the ObjectId
it has created for the object. The third statement assumes that the POA has the IMPLICIT_ACTIVATION
policy (the only supported policy in version 4.2 of the Oracle Tuxedo software) and returns a reference to the object. That reference can then be handed to a client for invocations. When the client invokes on the reference, the request is returned to the servant just created.
MyFooServant* afoo = new MyFooServant(poa,27);
PortableServer::ObjectId_var oid =
poa->activate_object(afoo);
Foo_var foo = afoo->_this();
Activates an individual object with a specified ObjectId
.
void activate_object_with_id (
const ObjectId & id,
Servant p_servant);
id
p_servant
The ObjectAlreadyActive
exception is raised if the CORBA object denoted by the ObjectId
value is already active in this POA.
The ServantAlreadyActive
exception is raised if the servant is already in the Active Object Map.
Note: | Other exceptions can occur if the POA uses unsupported policies. |
The BAD_PARAM system exception may be raised if the POA has the SYSTEM_ID policy and it detects that the ObjectId
value was not generated by the system or for this POA. An ORB is not required to detect all such invalid ObjectId
values. However, a portable application must not invoke activate_object_with_id on a POA if the POA has the SYSTEM_ID policy with an ObjectId
value that was not previously generated by the system for that POA, or, if the POA also has the PERSISTENT policy, for a previous instantiation of the same POA.
This operation enters an association between the specified ObjectId
and the specified servant in the Active Object Map.
Note: | This function is supported only for a joint client/server. |
MyFooServant* afoo = new MyFooServant(poa, 27);
PortableServer::ObjectId_var oid =
PortableServer::string_to_ObjectId("myLittleFoo");
poa->activate_object_with_id(oid.in(), afoo);
Foo_var foo = afoo->_this();
Obtains an object with the IdAssignmentPolicy interface so the user can pass the object to the POA::create_POA operation.
IdAssignmentPolicy_ptr
PortableServer::POA::create_id_assignment_policy (
PortableServer::
IdAssignmentPolicyValue value)
value
PortableServer::USE
R_ID, indicating ObjectIds
are assigned only by the application, or PortableServer::
SYSTEM_ID, indicating ObjectIds
are assigned only by the system.
The POA::create_id_assignment_policy operation obtains objects with the IdAssignmentPolicy interface. When passed to the POA::create_POA operation, this policy specifies whether ObjectIds
in the created POA are generated by the application or by the ORB. The following values can be supplied:
PortableServer::
USER_ID—objects created with that POA are assigned ObjectIds
only by the application. PortableServer::
SYSTEM_ID—objects created with that POA are assigned ObjectIds
only by the POA. If the POA also has the PERSISTENT LifespanPolicy
, assigned ObjectIds
must be unique across all instantiations of the same POA.If no IdAssignmentPolicy is specified at POA creation, the default is SYSTEM_ID.
Note: | This function is supported only for a joint client/server. |
Returns an Id Assignment
policy.
Obtains an object with the LifespanPolicy interface so the user can pass the object to the POA::create_POA operation.
LifespanPolicy_ptr
PortableServer::POA::create_lifespan_policy (
PortableServer::
LifespanPolicyPolicyValue value)
value
PortableServer::USE
R_ID, indicating ObjectIds
are assigned only by the application, or PortableServer::
SYSTEM_ID, indicating ObjectIds
are assigned only by the system.
Objects with the LifespanPolicy
interface are obtained using the POA::create_lifespan_policy
operation and passed to the POA::create_POA
operation to specify the lifespan of the objects implemented in the created POA. The following values can be supplied.
TRANSIENT
—the objects implemented in the POA cannot outlive the process in which they are first created. Once the POA is deactivated, use of any object references generated from it will result in an OBJECT_NOT_EXIST
exception. PERSISTENT
—the objects implemented in the POA can outlive the process in which they are first created.
If no LifespanPolicy
object is passed to POA::create_POA
, the lifespan policy defaults to TRANSIENT
.
Note: | This function is supported only for a joint client/server. |
Creates a new POA as a child of the target POA.
POA_ptr
PortableServer::create_POA (
const char * adapter_name,
POAManager_ptr a_POAManager,
const CORBA::PolicyList & policies)
adapter_name
a_POAManager
policies
IMP_LIMIT
PERSISTENT
without having set a port, as described in the operation CORBA::ORB_init.
This operation creates a new POA as a child of the target POA. The specified name, which must be unique, identifies the new POA with respect to other POAs with the same parent POA.
If the a_POAManager parameter is NULL, a new PortableServer::POAManager
object is created and associated with the new POA. Otherwise, the specified POAManager object is associated with the new POA. The POAManager object can be obtained using the attribute name the_POAManager.
The specified policy objects are associated with the POA and are used to control its behavior. The policy objects are effectively copied before this operation returns, so the application is free to destroy them while the POA is in use. Policies are not inherited from the parent POA.
Note: | This function is supported only for joint client/servers. |
Returns a pointer to the POA that was created.
In this example, the child POA would use the same manager as the parent POA; the child POA would then have the same state as the parent (that is, it would be active if the parent is active).
CORBA::PolicyList policies(2);
policies.length (1);
policies[0] = rootPOA->create_lifespan_policy(
PortableServer::LifespanPolicy::TRANSIENT);
PortableServer::POA_ptr poa =
rootPOA->create_POA("my_little_poa",
rootPOA->the_POAManager, policies);
In this example, a new POA is created as a child of the root POA.
CORBA::PolicyList policies(2);
policies.length (1);
policies[0] = rootPOA->create_lifespan_policy(
PortableServer::LifespanPolicy::TRANSIENT);
PortableServer::POA_ptr poa =
rootPOA->create_POA("my_little_poa",
PortableServer::POAManager::_nil(), policies);
Creates an object reference that encapsulates a POA-generated ObjectId
value and the specified interface repository ID.
CORBA::Object_ptr create_reference (
const char * intf)
intf
This operation requires the LifespanPolicy to have the value SYSTEM_ID; if not present, the PortableServer::Wro
ngPolicy exception is raised.
This create_reference operation creates an object reference that encapsulates a POA-generated ObjectId
value and the specified interface repository ID. This operation collects the necessary information to constitute the reference from information associated with the POA and from parameters to the operation. This operation only creates a reference; it does not associate the reference with an active servant. The resulting reference may be passed to clients, so that subsequent requests on those references return to the POA using the ObjectId
generated. The generated ObjectId
value may be obtained by invoking POA::reference_to_id with the created reference.
Note: | This function is supported only for a joint client/server. |
Returns a
pointer to the object.
Creates an object reference that encapsulates the specified ObjectId
and interface repository ID values.
CORBA::Object_ptr create_reference_with_id (
const ObjectId & oid,
const char * intf)
oid
intf
If the POA has a LifespanPolicy with value SYSTEM_ID and it detects that the ObjectId
value was not generated by the system or for this POA, the operation will raise the BAD_PARAM system exception.
The create_reference operation creates an object reference that encapsulates the specified ObjectId
and interface repository ID values. This operation collects the necessary information to constitute the reference from information associated with the POA and from parameters to the operation. This operation only creates a reference; it does not associate the reference with an active servant. The resulting reference may be passed to clients, so that subsequent requests on those references cause the invocation to be returned to the same POA with ObjectId
specified.
Note: | This function is supported only for a joint client/server. |
PortableServer::ObjectId_var oid =
PortableServer::string_to_ObjectId("myLittleFoo");
CORBA::Object_var obj = poa->create_reference_with_id(
oid.in(), "IDL:Foo:1.0");
Foo_var foo = Foo::_narrow(obj);
Removes the ObjectId
from the Active Object Map.
void deactivate_object (
const ObjectId & oid)
oid
If there is no active object associated with the specified ObjectId
, the operation raises an ObjectNotActive exception.
This operation causes the association of the ObjectId
specified by the oid parameter and its servant to be removed from the Active Object Map.
Note: | This function is supported only for a joint client/server. |
Destroys the POA and all descendant POAs.
void destroy (
CORBA::Boolean etherealize_objects,
CORBA::Boolean wait_for_completion)
etherealize_objects
wait_for_completion
This operation destroys the POA and all descendant POAs. The POA with its name may be recreated later in the same process. (This differs from the POAManager::deactivate operation, which does not allow a recreation of its associated POA in the same process.)
When a POA is destroyed, any requests that have started execution continue to completion. Any requests that have not started execution are processed as if they were newly arrived and there is no POA; that is, they are rejected and the OBJECT_NON_EXIST
exception is raised.
If the wait_for_completion parameter is TRUE
, the destroy operation returns only after all requests in process have completed and all invocations of etherealize have completed. Otherwise, the destroy operation returns after destroying the POAs.
Note: | This release of Oracle Tuxedo does not support multithreading. Hence, wait_for_completion should not be TRUE if the call is made in the context of an object invocation. That is, the POA cannot start destroying itself if it is currently executing. |
Note: | This function is supported only for a joint client/server. |
Returns a reference to a child POA with a given name.
void find_POA( in string adapter_name, in boolean activate_it);
adapter_name
active_it
AdapterNonExistent
If the POA has a child POA with the specified name, that child POA is returned. If a child POA with the specified name does not exist and the value of the activate_it
parameter is FALSE
, the AdapterNonExistent
exception is raised.
Returns the ObjectId
value encapsulated by the specified reference
.
ObjectId reference_to_id(in Object reference);
WrongAdapter
This operation returns the ObjectId
value encapsulated by the specified reference
. This operation is valid only if the reference was created by the POA on which the operation is being performed. The object denoted by the reference does not have to be active for this operation to succeed.
Note: | This function is supported only for a joint client/server. |
Returns the ObjectId
value encapsulated by the specified reference
.
Identifies the POA manager associated with the POA.
POAManager_ptr the_POAManager ();
This read-only attribute identifies the POA manager associated with the POA.
Note: | This function is supported only for a joint client/server. |
poa->the_POAManager()->activate();
This statement will set the state of the POAManager for the given POA to active, which is required if the POA is to accept requests. Note that if the POA has a parent, that is, it is not the root POA, all of its parent’s POAManagers must also be in the active state for this statement to have any effect.
Returns an object reference to the POA associated with the servant.
class PortableServer
{
class ServantBase
{
public:
virtual POA_ptr _default_POA();
}
}
All C++ Servants inherit from PortableServer::ServantBase
, so they all inherit the _default_POA
function. In this version of Oracle Tuxedo there is usually no reason to use _default_POA
.
The default implementation of this function returns an object reference to the root POA of the default ORB in this process—the same as the return value of an invocation of ORB::resolve_initial_references("RootPOA")
. A C++ servant can override this definition to return the POA of its choice, if desired.
Note: | This function is supported only for joint client/servers. |
The default POA associated with the servant.
The PortableServer::Current interface, derived from CORBA::Current, provides method implementations with access to the identity of the object on which the method was invoked.
Returns the ObjectId
identifying the object in whose context it is called.
ObjectId * get_object_id ();
None.
If called outside the context of a POA-dispatched operation, a PortableServer::
NoContext exception is raised.
This operation returns the PortableServer::ObjectId
identifying the object in whose context it is called.
Note: | This function is supported only for a joint client/server. |
This operation returns the ObjectId
identifying the object in whose context it is called.
Returns a reference to the POA implementing the object in whose context it is called.
POA_ptr get_POA ();
None.
If this operation is called outside the context of a POA-dispatched operation, a PortableServer::
NoContext exception is raised.
This operation returns a reference to the POA implementing the object in whose context it is called.
Note: | This function is supported only for a joint client/server. |
This operation returns a reference to the POA implementing the object in whose context it is called.
Each POA object has an associated POAManager object. A POAManager may be associated with one or more POA objects. A POAManager encapsulates the processing state of the POAs with which it is associated. Using operations on the POA manager, an application can cause requests for those POAs to be queued or discarded, and can cause the POAs to be deactivated.
POA managers are created and destroyed implicitly. Unless an explicit POAManager object is provided at POA creation time, a POAManager is created when a POA is created and is automatically associated with that POA. A POAManager object is implicitly destroyed when all of its associated POAs have been destroyed.
A POAmanager has four possible processing states: active, inactive, holding, and discarding. The processing state determines the capabilities of the associated POAs and the disposition of requests received by those POAs.
A POAmanager is created in the holding state. In that state, any invocations on its POA are queued until the POA manager enters the active state. This version of Oracle Tuxedo supports only the ability to enter active and inactive states. That is, this version does not support the ability to return to holding state or to enter discarding state.
Changes the state of the POAManager to active.
void activate();
If this operation is issued while the POAmanager is in the inactive state, the PortableServer::POAManager::AdapterInactive
exception is raised.
This operation changes the state of the POAManager to active. Entering the active state enables the associated POAs to process requests.
Note: | All parent POAs must also have POAManagers in the active state for this POA to process requests. |
Note: | This function is supported only for a joint client/server. |
Changes the state of the POA manager to inactive.
void deactivate (
CORBA::Boolean etherealize_objects,
CORBA::Boolean wait_for_completion);
etherealize_objects
FALSE
.
wait_for_completion
TRUE
, the deactivate operation returns only after all requests in process have completed. If this argument is FALSE
, the deactivate operation returns after changing the state of the associated POAs.
If issued while the POA manager is in the inactive state, the PortableServer::POAManager::AdapterInactive
exception is raised.
This operation changes the state of the POAManager to inactive. Entering the inactive state causes the associated POAs to reject requests that have not begun to be executed, as well as any new requests.
Note: | This release of Oracle Tuxedo does not support multithreading. Hence, wait_for_completion should not be TRUE if the call is made in the context of an object invocation. That is, the POAManager cannot be set to inactive state if it is currently executing. |
Note: | This function is supported only for a joint client/server. |
Interfaces derived from CORBA::Policy are used with the POA::create_POA operation to specify policies that apply to a POA. Policy objects are created using factory operations on any preexisting POA, such as the root POA. Policy objects are specified when a POA is created. Policies may not be changed on an existing POA. Policies are not inherited from the parent POA.
Specifies the life span of objects to the create_POA operation.
Objects with the LifespanPolicy interface are obtained using the POA::create_lifespan_policy operation and are passed to the POA::create_POA operation to specify the life span of the objects implemented in the created POA. The following values can be supplied:
Persistent objects have a POA associated with them (the POA that created them). When the ORB receives a request on a persistent object, it searches for the matching POA, based on the names of the POA and all of its ancestors.
POA names must be unique within their enclosing scope (the parent POA). A portable program can assume that POA names used in other processes will not conflict with its own POA names.
If no LifespanPolicy object is passed to create_POA, the lifespan policy defaults to TRANSIENT.
Note: | This function is supported only for a joint client/server. |
Specifies whether ObjectIds
in the created POA are generated by the application or by the ORB.
Objects with the IdAssignmentPolicy interface are obtained using the POA::create_id_assignment_policy operation and are passed to the POA::create_POA operation to specify whether ObjectIds
in the created POA are generated by the application or by the ORB. The following values can be supplied:
If no IdAssignmentPolicy is specified at POA creation, the default is SYSTEM_ID.
Note: | This function is supported only for a joint client/server. |
The mapping of these member functions to C++ is as follows:
// C++
class Request
{
public:
Object_ptr target() const;
const char *operation() const;
NamedValue_ptr result();
NVList_ptr arguments();
Environment_ptr env();
ExceptionList_ptr exceptions();
ContextList_ptr contexts();
void ctx(Context_ptr);
Context_ptr ctx() const
// argument manipulation helper functions
Any &add_in_arg();
Any &add_in_arg(const char* name);
Any &add_inout_arg():
Any &add_inout_arg(const char* name);
Any &add_out_arg():
Any &add_out_arg(const char* name);
void set_return_type(TypeCode_ptr tc);
Any &return_value();
void invoke();
void send_oneway();
void send_deferred();
void get_response();
Boolean poll_response();
};
Note: | The add_*_arg , set_return_type , and return_value member functions are added as shortcuts for using the attribute-based accessors. |
The following sections describe these member functions.
Retrieves the argument list for the request.
CORBA::NVList_ptr CORBA::Request::arguments () const;
This member function retrieves the argument list for the request. The arguments can be input
, output
, or both.
If the function succeeds, the value returned is a pointer to the list of arguments to the operation for the request. The returned argument list is owned by the Request object reference and should not be released.
If the function does not succeed, an exception is thrown.
Sets the Context object for the operation.
void CORBA::Request::ctx (
CORBA::Context_ptr CtxObject);
CtxObject
This member function sets the Context object for the operation.
Retrieves the response of a specific deferred synchronous request.
void CORBA::Request::get_response ();
This member function retrieves the response of a specific request; it is used after a call to the CORBA::Request::send_deferred
function or the CORBA::Request::send_multiple_requests
function. If the request has not completed, the CORBA::Request::get_response
function blocks until it does complete.
Performs an invoke on the operation specified in the request.
void CORBA::Request::invoke ();
This member function calls the Object Request Broker (ORB) to send the request to the appropriate server application.
Retrieves the operation intended for the request.
const char * CORBA::Request::operation () const;
This member function retrieves the operation intended for the request.
If the function succeeds, the value returned is a pointer to the operation intended for the object; the value can be 0 (zero). The memory returned is owned by the Request object and should not be freed.
If the function does not succeed, an exception is thrown.
Determines whether a deferred synchronous request has completed.
CORBA::Boolean CORBA::Request::poll_response ();
This member function determines whether the request has completed and returns immediately. You can use this call to check the state of the request. This member function can also be used to determine whether a call to CORBA::Request::get_response
will block.
If the function succeeds, the value returned is CORBA_TRUE
if the response has already completed, and CORBA_FALSE
if the response has not yet completed.
If the function does not succeed, an exception is thrown.
CORBA::ORB::get_next_response
CORBA::ORB::poll_next_response
CORBA::ORB::send_multiple_requests
CORBA::Request::get_response
CORBA::Request::send_deferred
Retrieves the result of the request.
CORBA::NamedValue_ptr CORBA::Request::result ();
This member function retrieves the result of the request.
If the function succeeds, the value returned is a pointer to the result of the operation. The returned result is owned by the Request object and should not be released.
If the function does not succeed, an exception is thrown.
Retrieves the environment of the request.
CORBA::Environment_ptr CORBA::Request::env ();
This member function retrieves the environment of the request.
If the function succeeds, the value returned is a pointer to the environment of the operation. The returned environment is owned by the Request object and should not be released.
If the function does not succeed, an exception is thrown.
Retrieves the context of the request.
CORBA::context_ptr CORBA::Request::ctx ();
This member function retrieves the context of the request.
If the function succeeds, the value returned is a pointer to the context of the operation. The returned context is owned by the Request object and should not be released.
If the function does not succeed, an exception is thrown.
Retrieves the context lists for the request.
CORBA::ContextList_ptr CORBA::Request::contexts ();
This member function retrieves the context lists for the request.
If the function succeeds, the value returned is a pointer to the context lists for the operation. The returned context list is owned by the Request object and should not be released.
If the function does not succeed, an exception is thrown.
Retrieves the exception lists for the request.
CORBA::ExceptionList_ptr CORBA::Request::exceptions ();
This member function retrieves the exception lists for the request.
If the function succeeds, the value returned is a pointer to the exception list for the request. The returned exception list is owned by the Request object and should not be released.
If the function does not succeed, an exception is thrown.
Retrieves the target object reference for the request.
CORBA::Object_ptr CORBA::Request::target () const;
This member function retrieves the target object reference for the request.
If the function succeeds, the value returned is a pointer to the target object of the operation. The returned value is owned by the Request object and should not be released.
If the function does not succeed, an exception is thrown.
Initiates a deferred synchronous request.
void CORBA::Request::send_deferred ();
This member function initiates a deferred synchronous request. You use this function when a response is expected and in conjunction with the CORBA::Request::get_response
function.
CORBA::ORB::get_next_response
CORBA::ORB::poll_next_response
CORBA::ORB::send_multiple_requests
CORBA::Request::get_response
CORBA::Request::poll_response
CORBA::Request::send_oneway
void CORBA::Request::send_oneway ();
This member function initiates a one-way request; it does not expect a response.
CORBA::ORB::send_multiple_requests
CORBA::Request::send_deferred
The mapping of these functions to C++ is as follows:
// C++
namespace CORBA {
static char * string_alloc(ULong len);
static char * string_dup (const char *);
static void string_free(char *);
...
}
Note: | A static array of char in C++ decays to a char* . Therefore, care must be taken when assigning a static array to a String_var , because the String_var assumes that the pointer points to data allocated via string_alloc , and thus eventually attempts to free it using string_free . This behavior has changed in ANSI/ISO C++, where string literals are const char* , not char* . However, since most C++ compilers do not yet implement this change, portable programs must heed the advice given here. |
The following sections describe the functions that manage memory allocated to strings.
Allocates memory for a string.
char * CORBA::string_alloc(ULong len);
len
This member function dynamically allocates memory for a string, or returns a nil pointer if it cannot perform the allocation. It allocates len+1
characters so that the resulting string has enough space to hold a trailing NULL character. Free the memory allocated by this member function by calling the CORBA::string_free
member function.
This function does not throw CORBA exceptions.
If the function succeeds, the return value is a pointer to the newly allocated memory for the string object; if the function fails, the return value is a nil pointer.
char* s = CORBA::string_alloc(10);
CORBA::string_free
CORBA::string_dup
char * CORBA::string_dup (const char * Str);
Str
This function dynamically allocates enough memory to hold a copy of its string argument, including the NULL character, copies the string argument into that memory, and returns a pointer to the new string.
This function does not throw CORBA exceptions.
If the function succeeds, the return value is a pointer to the new string; if the function fails, the return value is a nil pointer.
char* s = CORBA::string_dup("hello world");
CORBA::string_free
CORBA::string_alloc
Frees memory allocated to a string.
void CORBA::string_free(char * Str);
Str
This member function deallocates memory that was previously allocated to a string using the CORBA::string_alloc() or CORBA::string_dup()
member
functions. Passing a nil pointer to this function is acceptable and results in no action being performed.
This function may not throw CORBA exceptions.
char* s = CORBA::string_dup("hello world");
CORBA::string_free(s);
CORBA::string_alloc
CORBA::string_dup
Both bounded and unbounded wide string types are mapped to CORBA::WChar*
in C++. In addition, the CORBA module defines WString_var
and WString_out
classes. Each of these classes provides the same member functions with the same semantics as their string counterparts, except of course they deal with wide strings and wide characters.
Dynamic allocation and deallocation of wide strings must be performed via the following functions:
// C++
namespace CORBA {
// ...
WChar *wstring_alloc(ULong len);
WChar *wstring_dup(const WChar* ws);
void wstring_free(WChar*);
};
These member functions have the same semantics as the same functions for the string type, except they operate on wide strings.
A compliant mapping implementation provides overloaded operator<<
(insertion) and operator>>
(extraction) operators for using WString_var
and WString_out
directly with C++ iostreams.
For descriptions of these member functions, see the corresponding function for Strings.
Listing 14-1 shows a code example that uses wide strings and wide characters.
// Get a string from the user:
cout << "String?";
char mixed[256]; // this should be big enough!
char lower[256];
char upper[256];
wchar_t wmixed[256];
cin >> mixed;
// Convert the string to a wide char string,
// because this is what the server will expect.
mbstowcs(wmixed, mixed, 256);
// Convert the string to upper case:
CORBA::WString_var v_upper = CORBA::wstring_dup(wmixed);
v_simple->to_upper(v_upper.inout());
wcstombs(upper, v_upper.in(), 256);
cout << upper << endl;
// Convert the string to lower case:
CORBA::WString_var v_lower = v_simple->to_lower(wmixed);
wcstombs(lower, v_lower.in(), 256);
cout << lower << endl;
// Everything succeeded:
return 0;
A TypeCode represents OMG IDL type information.
No constructors for TypeCodes are defined. However, in addition to the mapped interface, for each basic and defined OMG IDL type, an implementation provides access to a TypeCode pseudo-object reference (TypeCode_ptr
) of the form _tc_<type>
that may be used to set types in Any
, as arguments for equal
, and so on. In the names of these TypeCode reference constants, <type>
refers to the local name of the type within its defining scope. Each C++ _tc_<type>
constant is defined at the same scoping level as its matching type.
Like all other serverless objects, the C++ mapping for TypeCode provides a _nil()
operation that returns a nil object reference for a TypeCode. This operation can be used to initialize TypeCode references embedded within constructed types. However, a nil TypeCode reference may never be passed as an argument to an operation, since TypeCodes
are effectively passed as values, not as object references.
The mapping of these member functions to C++ is as follows:
class CORBA
{
class TypeCode
{
public:
class Bounds { ... };
class BadKind { ... };
Boolean equal(TypeCode_ptr) const;
TCKind kind() const;
Long param_count() const;
Any *parameter(Long) const;
RepositoryId id () const;
}; // TypeCode
}; // CORBA
TypeCode has the following special memory management rule:
The following sections describe these member functions.
Determines whether two TypeCode objects are equal.
CORBA::Boolean CORBA::TypeCode::equal (
CORBA::TypeCode_ptr TypeCodeObj) const;
TypeCodeObj
This member function determines whether a TypeCode object is equal to the input parameter, TypeCodeObj
.
If the TypeCode object is equal to the TypeCodeObj
parameter, CORBA_TRUE
is returned.
If the TypeCode object is not equal to the TypeCodeObj
parameter, CORBA_FALSE
is returned.
If the function does not succeed, an exception is thrown.
Returns the ID for the TypeCode.
CORBA::RepositoryId CORBA::TypeCode::id () const;
This member function returns the ID for the TypeCode.
Repository ID for the TypeCode.
Retrieves the kind of data contained in the TypeCode object reference.
CORBA::TCKind CORBA::TypeCode::kind () const;
This member function retrieves the kind
attribute of the CORBA::TypeCode
class, which specifies the kind of data contained in the TypeCode object reference.
If the member function succeeds, it returns the kind of data contained in the TypeCode object reference. For a list of the TypeCode kinds and their parameters, see Table 14-2.
If the member function does not succeed, an exception is thrown.
Retrieves the number of parameters for the TypeCode object reference.
CORBA::Long CORBA::TypeCode::param_count () const;
This member function retrieves the parameter attribute of the CORBA::TypeCode
class, which specifies the number of parameters for the TypeCode object reference. For a list of parameters of each kind, see Table 14-2.
If the function succeeds, it returns the number of parameters contained in the TypeCode object reference.
If the function does not succeed, an exception is thrown.
Retrieves a parameter specified by the index input argument.
CORBA::Any * CORBA::TypeCode::parameter (
CORBA::Long Index) const;
Index
This member function retrieves a parameter specified by the index input argument. For a list of parameters of each kind, see Table 14-2.
If the member function succeeds, the return value is a pointer to the parameter specified by the index input argument.
If the member function does not succeed, an exception is thrown.
The Oracle Tuxedo software supports the throwing and catching of exceptions.
Caution: | Use of the wrong exception constructor causes noninitialization of a data member. Exceptions that are defined to have a reason field need to be created using the constructor that initializes that data member. If the default constructor is used instead, that data member is not initialized and, during destruction of the exception, the system may attempt to destroy nonexistent data. |
Caution: | When creating exceptions, be sure to use the constructor function that most fully initializes the data fields. These exceptions can be most easily identified by looking at the OMG IDL definition; they have additional data member definitions. |
Descriptions of exception member functions follow:
CORBA::SystemException::SystemException ()
CORBA::SystemException
class. Minor code is initialized to 0 (zero) and the completion status is set to COMPLETED_NO
.
CORBA::SystemException::SystemException (
const CORBA::SystemException & Se)
CORBA::SystemException::SystemException(
CORBA::ULong Minor, CORBA::CompletionStatus Status)
orbminor.h
.
CORBA::SystemException::~SystemException ()
CORBA::SystemException
class. It frees any memory used for the Exception object.
CORBA::SystemException CORBA::SystemException::operator =
const CORBA::SystemException Se)
Se
argument specifies the SystemException object that is to be copied by this operator.
CORBA::CompletionStatus CORBA::SystemException::completed()
CORBA::SystemException::completed(
CORBA::CompletionStatus Completed)
Completed
argument specifies the completion status for this exception.
CORBA::ULong CORBA::SystemException::minor()
CORBA::SystemException::minor (CORBA::ULong Minor)
minor
argument specifies the new minor code for this exception. The minor field is an implementation-specific value used by the application to identify the exception.
CORBA::SystemException * CORBA::SystemException::_narrow (
CORBA::Exception_ptr Exc)
Exc
argument specifies the exception to be narrowed.
CORBA::UserException * CORBA::UserException::_narrow(
CORBA::Exception_ptr Exc)
Exc
argument specifies the exception to be narrowed.
This section presents the standard exceptions defined for the ORB. These exception identifiers may be returned as a result of any operation invocation, regardless of the interface specification. Standard exceptions are not listed in raises
expressions.
To bound the complexity in handling the standard exceptions, the set of standard exceptions is kept to a tractable size. This constraint forces the definition of equivalence classes of exceptions, rather than enumerating many similar exceptions.
For example, an operation invocation can fail at many different points due to the inability to allocate dynamic memory. Rather than enumerate several different exceptions that correspond to the different ways that memory allocation failure causes the exception (during marshaling, unmarshaling, in the client, in the object implementation, allocating network packets, and so forth), a single exception corresponding to dynamic memory allocation failure is defined. Each standard exception includes a minor code to designate the subcategory of the exception; the assignment of values to the minor codes is left to each ORB implementation.
Each standard exception also includes a completion_status
code, which takes one of the following values:
CORBA::COMPLETED_YES
CORBA::COMPLETED_NO
CORBA::COMPLETED_MAYBE
The standard exceptions are defined below. Clients must be prepared to handle system exceptions that are not on this list, both because future versions of this specification may define additional standard exceptions, and because ORB implementations may raise nonstandard system exceptions. For more information about exceptions, see System Messages.
Table 14-3 defines the exceptions.
The CORBA::OBJECT_NOT_EXIST
exception is raised whenever an invocation on a deleted object is performed. It is an authoritative “hard” fault report. Anyone receiving it is allowed (even expected) to delete all copies of this object reference and to perform other appropriate “final recovery” style procedures.
The CORBA::TRANSACTION_REQUIRED
exception indicates that the request carried a NULL transaction context, but an active transaction is required.
The CORBA::TRANSACTION_ROLLEDBACK
exception indicates that the transaction associated with the request has already been rolled back or marked to roll back. Thus, the requested operation either could not be performed or was not performed because further computation on behalf of the transaction would be fruitless.
The CORBA::INVALID_TRANSACTION
indicates that the request carried an invalid transaction context. For example, this exception could be raised if an error occurred when trying to register a resource.
The ExceptionList
member functions allow a client or server application to provide a list of TypeCodes for all user-defined exceptions that may result when the Request is invoked. For a description of the Request member functions, see the section Request Member Functions.
The mapping of these member functions to C++ is as follows:
class CORBA
{
class ExceptionList
{
public:
Ulong count ();
void add(TypeCode_ptr tc);
void add_consume(TypeCode_ptr tc);
TypeCode_ptr item(Ulong index);
Status remove(Ulong index);
}; // ExceptionList
}// CORBA
Retrieves the current number of items in the list.
Ulong count ();
If the function does not succeed, an exception is thrown.
This member function retrieves the current number of items in the list.
If the function succeeds, the returned value is the number of items in the list. If the list has just been created, and no ExceptionList objects have been added, this function returns 0 (zero).
Constructs a ExceptionList object with an unnamed item, setting only the flags
attribute.
void add(TypeCode_ptr tc);
tc
If the member function does not succeed, a CORBA::NO_MEMORY
exception is thrown.
This member function constructs an ExceptionList object with an unnamed item, setting only the flags attribute.
The ExceptionList object grows dynamically; your application does not need to track its size.
If the function succeeds, the return value is a pointer to the newly created ExceptionList object.
CORBA::ExceptionList::add_consume
CORBA::ExceptionList::count
CORBA::ExceptionList::item
CORBA::ExceptionList::remove
Constructs an ExceptionList object.
void add_consume(TypeCode_ptr tc);
tc
If the member function does not succeed, an exception is raised.
This member function constructs an ExceptionList object.
The ExceptionList object grows dynamically; your application does not need to track its size.
If the function succeeds, the return value is a pointer to the newly created ExceptionList object.
CORBA::ExceptionList::add
CORBA::ExceptionList::count
CORBA::ExceptionList::item
CORBA::ExceptionList::remove
Retrieves a pointer to the ExceptionList object, based on the index passed in.
TypeCode_ptr item(ULong index);
index
If the function does not succeed, the BAD_PARAM
exception is thrown.
This member function retrieves a pointer to an ExceptionList object, based on the index passed in. The function uses zero-based indexing.
If the function succeeds, the return value is a pointer to the ExceptionList object.
CORBA::ExceptionList::add
CORBA::ExceptionList::remove
CORBA::ExceptionList::add_consume
CORBA::ExceptionList::count
CORBA::ExceptionList::remove
Removes the item at the specified index, frees any associated memory, and reorders the remaining items on the list.
Status remove(ULong index);
Index
If the function does not succeed, the BAD_PARAM
exception is thrown.
This member function removes the item at the specified index, frees any associated memory, and reorders the remaining items on the list.
CORBA::ExceptionList::add
CORBA::ExceptionList::add_consume
CORBA::ExceptionList::count
CORBA::ExceptionList::item
![]() ![]() ![]() |