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.
•
• 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.Constructs the Any object.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).Refers to the CORBA::Any to copy.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.A pointer to the data to be used to create the Any object. The data type of this argument must match the TypeCode specified.Determines whether the 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.Destructor for the 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.Any assignment operator.A reference to an Any to use in the assignment. The Any to use in the assignment determines whether the Any assumes ownership of the memory in 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.Type safe Any insertion operators.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.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.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.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.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.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.Nontype safe Any “insertion.”A TypeCode pseudo-object reference specifying the TypeCode value for the replaced Any object. This argument is duplicated.Determines whether the Any manages the specified Value argument. If 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.
• Ownership of the return values of the context_name and parent functions is maintained by the Context; these return values must not be freed by the caller.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.CORBA::BAD_PARAM if attribute is an empty string.
CORBA::BAD_CONTEXT if no matching attributes to be deleted were found.The Context object level at which to initiate the search for specified properties. The level is the name of the context, or parent, at which the search is started. If the value is 0 (zero), the search begins with the current Context object.The only valid operation flag is 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.Receives the values for the specified attributes (returns an 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.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.The value of the attribute. Currently, the Oracle Tuxedo system supports only the string type; therefore, this parameter must contain a 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.The name and value of the attribute. Currently the Oracle Tuxedo system supports only the string type; therefore, all NamedValue objects in the list must have 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.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‑96.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.If the member function does not succeed, a CORBA::NO_MEMORY exception is thrown.If this function does not succeed, the BAD_PARAM exception is thrown.If this function does not succeed, the BAD_PARAM exception is thrown.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.
• Ownership of the return values of the name() and value() functions is maintained by the NamedValue; these return values must not be freed by the caller.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.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:
• add—creates an unnamed value, initializing only the flags
• add_item—initializes name and flags
• add_value—initializes name, value, and flagsElements 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.
• Ownership of the return values of the 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.
• The 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.
• CORBA::NamedValue_ptr CORBA::NVList::add (
CORBA::Flags Flags);If the member function does not succeed, a CORBA::NO_MEMORY exception is thrown.CORBA::NamedValue_ptr CORBA::NVList::add_item (
const char * Name,
CORBA::Flags Flags);CORBA::NamedValue_ptr CORBA::NVList::add_value (
const char * Name,
const CORBA::Any & Value,
CORBA::Flags Flags);CORBA::NamedValue_ptr CORBA::NVList::item (
CORBA::ULong Index);If this function does not succeed, the BAD_PARAM exception is thrown.void CORBA::NVList::remove (
CORBA::ULong Index);If this function does not succeed, the BAD_PARAM exception is thrown.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.class CORBA
{
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,
ExceptionList_ptr Except_list,
ContextList_ptr Context_list,
Request_out request,
Flags req_flags
);
Request_ptr _request(const char* operation);
}; //Object
}; // CORBAThe following sections describe the Object member functions.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,);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.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.
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.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.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.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 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.CORBA::Request_ptr CORBA::Object::_request (
const char * 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.The object reference that the caller will no longer access. The specified object type must be one of the types listed in the section CORBA Member Functions.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.The object reference. The specified object type must be one of the types listed in the section CORBA Member Functions.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 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.Returns an initial object reference corresponding to an identifier string. Valid identifiers are “RootPOA” and “POACurrent”.Returns a CORBA::Object_ptr.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.
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.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 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.void CORBA::ORB::create_list (
CORBA::Long NumItem,
CORBA::NVList_out 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.void CORBA::ORB::create_named_value (
NameValue_out NewNamedVal);When no longer needed, the NamedValue object must be freed using the CORBA::release member function.void CORBA::ORB::create_operation_list (
CORBA::OperationDef_ptr Oper,
CORBA::NVList_out 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.BiDirPolicy::BIDIRECTIONAL_POLICY_TYPE is the only PolicyType value supported for Oracle WebLogic Enterprise version 4.2.The only val value supported for Oracle WebLogic Enterprise V4.2 is BiDirPolicy::BidirectionalPolicyValue.This exception is raised to indicate problems with the parameter values passed to the ORB::create_policy operation. The specific exception and reasons are as follows shown in Table 14‑1:
Table 14‑1 Exception and Reasons 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.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.In the above example, the bd_policy would then be placed in the PolicyList passed to the create_poa operation.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.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.void CORBA::ORB::get_next_response (
CORBA::Request_out 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.typedef string ObjectId;
typedef sequence ObjectId ObjectIdList;
ObjectIdList 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.Sequence of ObjectIds.char * CORBA::ORB::object_to_string (
CORBA::Object_ptr 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.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.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.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).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.void CORBA::ORB::send_multiple_requests_deferred (
const CORBA::ORB::RequestSeq & Reqs);The sequence of requests to be sent. For more information about how to populate the sequence with request references, see 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.void CORBA::ORB::send_multiple_requests_oneway (
const CORBA::RequestSeq & Reqs);The sequence of requests to be sent. For more information about how to populate the sequence with request references, see CORBA::ORB::RequestSeq in the section Usage.void set_ctx(CORBA::ORB::Ctx aContext)
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.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.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.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.class CORBA {
static CORBA::ORB_ptr ORB_init(int& argc, char** argv,
const char* orb_identifier = 0,
const char* -ORBport nnn);
<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]static CORBA::ORB_ptr ORB_init(int& argc, char** argv,
const char* orb_identifier = 0);The number of strings in argv.This argument is defined as an unbound array of strings (char **) and the number of strings in the array is passed in the argc parameter.If the 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.
1. If the 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).
2. If 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”.
3. If no client type is specified in 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.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.A pointer to a CORBA::ORB.The value 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.The ORB initial reference argument, -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‑2.
The ORB default initial reference argument, -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:A call to ORB::resolve_initial_references(“NotificationService”) to obtain the initial reference for the service would result in the new URL: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: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:The resulting URL would then be passed to CORBA::ORB::string_to_object in order to obtain the initial reference for the service.When establishing a network link, this is the maximum level of encryption allowed. Zero (0) means no encryption, while 40, 56, and 128 specify the length (in bits) of the encryption key. The default is whatever capability is specified by the license. The –ORBmaxCrypto or –ORBmaxCrypto options are available only if either the International or U.S_Canada Oracle Tuxedo Security Add-on Package is installed.The –ORBmutualAuth option is available only if either the International or U.S_Canada Oracle Tuxedo Security Add-on Package is installed.A value of 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.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.The 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.The 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 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.
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.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.If the policy object determines that it cannot be destroyed, the CORBA::NO_PERMISSION exception is raised.// 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
};A value that is used by the POA and by the user-supplied implementation to identify a particular abstract CORBA object. 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.If the specified servant is already in the Active Object Map, the ServantAlreadyActive exception is raised.This operation explicitly activates an individual object by generating an ObjectId and entering the ObjectId and the specified servant in the Active Object Map.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.ObjectId that identifies the object on which that operation was invoked.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.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.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)A value of either PortableServer::USER_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.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)A value of either PortableServer::USER_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.POA_ptr PortableServer::create_POA (
const char * adapter_name,
POAManager_ptr a_POAManager,
const CORBA::PolicyList & policies)Raised if the program tries to create a POA with a LifespanPolicy of PERSISTENT without having set a port, as described in the operation CORBA::ORB_init.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.Creates an object reference that encapsulates a POA-generated ObjectId value and the specified interface repository ID.This operation requires the LifespanPolicy to have the value SYSTEM_ID; if not present, the PortableServer::WrongPolicy 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.Returns a pointer to the object.Creates an object reference that encapsulates the specified ObjectId and interface repository ID values.ObjectId that identifies the object on which that operation was invoked.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.Removes the ObjectId from the Active Object Map.ObjectId that identifies the object.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.This argument should be FALSE for this release of Oracle Tuxedo.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.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.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.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.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.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.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.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.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.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: Changes the state of the POA manager to inactive.If this argument is 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.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:
• TRANSIENT—the objects implemented in the POA cannot outlive the process in which they are first created.
• PERSISTENT—the objects implemented in the POA can outlive the process in which they are first created.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:
•
• SYSTEM_ID—objects created with that POA are assigned ObjectIds only by the POA. If the POA also has the PERSISTENT policy, assigned ObjectIds must be unique across all instantiations of the same POA.
Note: The add_*_arg, set_return_type, and return_value member functions are added as shortcuts for using the attribute-based accessors.This member function retrieves the argument list for the request. The arguments can be input, output, or both.void CORBA::Request::ctx (
CORBA::Context_ptr CtxObject);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.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.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.
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.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 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.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.A compliant mapping implementation provides overloaded operator<< (insertion) and operator>> (extraction) operators for using WString_var and WString_out directly with C++ iostreams.Listing 14‑1 shows a code example that uses wide strings and wide characters.Listing 14‑1 Wide Strings ExampleNo 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.
• Ownership of the return values of the id function is maintained by the TypeCode; these return values must not be freed by the caller.CORBA::Boolean CORBA::TypeCode::equal (
CORBA::TypeCode_ptr TypeCodeObj) const;This member function determines whether a TypeCode object is equal to the input parameter, TypeCodeObj.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‑3.
Table 14‑3 Legal Typecode Kinds and Parameters 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‑3.CORBA::Any * CORBA::TypeCode::parameter (
CORBA::Long Index) const;This member function retrieves a parameter specified by the index input argument. For a list of parameters of each kind, see Table 14‑3.
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.This is the default constructor for the CORBA::SystemException class. Minor code is initialized to 0 (zero) and the completion status is set to COMPLETED_NO.This is the copy constructor for the CORBA::SystemException class.This constructor for the CORBA::SystemException class sets the minor code and completion status.This is the destructor for the CORBA::SystemException class. It frees any memory used for the Exception object.This assignment operator copies exception information from the source exception. The Se argument specifies the SystemException object that is to be copied by this operator.This member function sets the completion status for this exception. The Completed argument specifies the completion status for this exception.This member function sets the minor code for this exception. The 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.This member function determines whether a specified exception can be narrowed to a system exception. The Exc argument specifies the exception to be narrowed.This member function determines whether a specified exception can be narrowed to a user exception. The Exc argument specifies the exception to be narrowed.Each standard exception also includes a completion_status code, which takes one of the following values:Table 14‑4 defines the exceptions.
Table 14‑4 Exception Definitions 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.Defines the memory location referred to by TypeCode_ptr.If the member function does not succeed, a CORBA::NO_MEMORY exception is thrown.If the function does not succeed, the BAD_PARAM exception is thrown.