Though much of the work done by the VisiBroker ORB is transparent to you, your client program must explicitly initialize the VisiBroker ORB. VisiBroker ORB options, described in “Programmer tools for C++” can be specified as command-line arguments. To ensure these options take effect you will need to pass the supplied argc and argv arguments to ORB_init. The code samples below illustrate the VisiBroker ORB initialization.
#include <fstream.h>
#include "Bank_c.hh"
int main(int argc, char* const* argv) {
CORBA::ORB_var orb;
CORBA::Float balance;
try {
// Initialize the ORB.
orb = CORBA::ORB_init(argc, argv);
. . .
}
#include "Bank_c.hh"
int main(int argc, char* const* argv) {
CORBA::ORB_var orb;
CORBA::Float balance;
try {
// Initialize the ORB.
orb = CORBA::ORB_init(argc, argv);
. . .
}
A client program uses a remote object by obtaining a reference to the object. Object references are usually obtained using the <interface> _bind() method. The VisiBroker ORB hides most of the details involved with obtaining the object reference, such as locating the server that implements the object and establishing a connection to that server.
When the server process starts, it performs CORBA::ORB.init() and announces itself to Smart Agents on the network.
When your client program invokes the _bind() method, the VisiBroker ORB performs several functions on behalf of your program.
|
•
|
The VisiBroker ORB contacts the Smart Agent to locate an object implementation that offers the requested interface. If an object name is specified when _bind() is invoked, that name is used to further qualify the directory service search. The Object Activation Daemon (OAD), described in “Using the Object Activation Daemon (OAD)” may be involved in this process if the server object has been registered with the OAD.
|
|
Figure 18
|
Your client program will never invoke a constructor for the server class. Instead, an object reference is obtained by invoking the static _bind() method.
Your client program uses an object reference to invoke an operation on an object or to reference data contained by the object. “Manipulating object references” describes the variety of ways that object references can be manipulated.
The _bind() method returns a reference to a CORBA object to your client program. Your client program can use the object reference to invoke operations on the object that have been defined in the object's IDL interface specification. In addition, there are methods that all VisiBroker ORB objects inherit from the class CORBA::Object that you can use to manipulate the object.
You can use the CORBA class method is_nil() shown below to determine if an object reference is nil. This method returns 1 if the object reference passed is nil. It returns 0 (zero) if the object reference is not nil.
You can obtain a nil object reference using the CORBA::Object class _nil() member function. It returns a NULL value that is cast to an Object_ptr.
When your client program invokes the _duplicate member function, the reference count for the object reference is incremented by one and the same object reference is returned. Your client program can use the _duplicate member function to increase the reference count for an object reference so that the reference can be stored in a data structure or passed as a parameter. Increasing the reference count ensures that the memory associated with the object reference will not be freed until the reference count has reached zero.
The IDL compiler generates a _duplicate member function for each object interface you specify. The _duplicate member function accepts and returns a generic Object_ptr.
The _duplicate member function has no meaning for the POA or VisiBroker ORB because these objects do not support reference counting.
You should release an object reference when it is no longer needed. One way of releasing an object reference is by invoking the CORBA::Object class _release member function.
Always use the release member function. Never invoke operator delete on an object reference.
You may also use the CORBA class release member function, which is provided for compatibility with the CORBA specification.
Each object reference has a reference count that you can use to determine how many times the reference has been duplicated. When you first obtain an object reference by invoking _bind(), the reference count is set to one. Releasing an object reference will decrement the reference count by one. Once the reference count reaches 0 (zero), VisiBroker automatically deletes the object reference. The code sample below shows the _ref_count member function for retrieving the reference count.
A client program can use the object_to_string method to convert an object reference to a string and pass it to another client program. The second client may then de-stringify the object reference, using the string_to_object method, and use the object reference without having to explicitly bind to the object.
The caller of object_to_string is responsible for calling CORBA::string_free() on the returned string.
Locally-scoped object references like the VisiBroker ORB or the POA cannot be stringified. If an attempt is made to do so, a MARSHAL exception is raised with the minor code 4.
The table below shows the methods provided by the Object class that you can use to obtain the interface and object names as well as the repository id associated with an object reference. The interface repository is discussed in “Using Interface Repositories”
When you invoke _bind() without specifying an object name, invoking the _object_name() method with the resulting object reference will return NULL.
You can use the _hash() member function to obtain a hash value for an object reference. While this value is not guaranteed to be unique, it will remain consistent through the lifetime of the object reference and can be stored in a hash table.
You can check whether an object reference is of a particular type by using the _is_a() method. You must first obtain the repository id of the type you wish to check using the _repository_id() method. This method returns 1 if the object is either an instance of the type represented by _repository_id() or if it is a sub-type. The member function returns 0 (zero) if the object is not of the type specified. Note that this may require remote invocation to determine the type.
You can use _is_equivalent() to check if two object references refer to the same object implementation. This method returns 1 if the object references are equivalent. It returns 0 (zero) if the object references are distinct, but it does not necessarily indicate that the object references are two distinct objects. This is a lightweight method and does not involve actual communication with the server object.
|
Returns true if two objects refer to the same interface implementation.
|
Given a valid object reference, your client program can use _is_bound() to determine if the object bound. The method returns 1 if the object is bound and returns 0 (zero) if the object is not bound.
The _is_local() method returns 1 if the client program and the object implementation reside within the same process or address space where the method is invoked.
The _is_remote() method returns 1 if the client program and the object implementation reside in different processes, which may or may not be located on the same host.
You can use the _non_existent() member function to determine if the object implementation associated with an object reference still exists. This method actually “pings” the object to determine if it still exists and returns 1 if it does exist.
The _narrow() member function may construct a new C++ object and returns a pointer to that object. When you no longer need the object, you must release the object reference returned by _narrow().
VisiBroker Edition maintains a type graph for each object interface so that narrowing can be accomplished by using the object's narrow() method.
If the narrow member function determines it is not possible to narrow an object to the type you request, it will return NULL.
Converting an object reference's type to a super-type is called widening. The code sample below shows an example of widening an Account pointer to an Object pointer. The pointer acct can be cast as an Object pointer because the Account class inherits from the Object class.
|
•
|
The VisiBroker ORB level policies are handled by a locality constrained PolicyManager, through which you can set Policies and view the current Policy overrides. Policies set at the VisiBroker ORB level override system defaults.
|
|
•
|
Thread level policies are set through PolicyCurrent, which contains operations for viewing and setting Policy overrides at the thread level. Policies set at the thread level override system defaults and values set at the VisiBroker ORB level.
|
The QoS policies installed at the ORB level will only affect those objects on which no method is called before installing the policies, for example a non_existent call internally makes a call on a server object. If ORB level QoS policies are installed after the non_existent call, then the policies do not apply.
The effective policy is the policy that would be applied to a request after all applicable policy overrides have been applied. The effective policy is determined by comparing the Policy as specified by the IOR with the effective override. The effective Policy is the intersection of the values allowed by the effective override and the IOR-specified Policy. If the intersection is empty a org.omg.CORBA.INV_POLICY exception is raised.
|
•
|
_get_policy returns the effective policy for an object reference.
|
|
•
|
_set_policy_override returns a new object reference with the requested list of Policy overrides at the object level.
|
|
•
|
_get_client_policy returns the effective Policy for the object reference without doing the intersection with the server-side policies. The effective override is obtained by checking the specified overrides in first the object level, then at the thread level, and finally at the VisiBroker ORB level. If no overrides are specified for the requested PolicyType the system default value for PolicyType is used.
|
|
•
|
_get_policy_overrides returns a list of Policy overrides of the specified policy types set at the object level. If the specified sequence is empty, all overrides at the object level will be returned. If no PolicyTypes are overridden at the object level, an empty sequence is returned.
|
|
•
|
_validate_connection returns a boolean value based on whether the current effective policies for the object will allow an invocation to be made. If the object reference is not bound, a binding will occur. If the object reference is already bound, but current policy overrides have changed, or the binding is no longer valid, a rebind will be attempted, regardless of the setting of the RebindPolicy overrides. A false return value occurs if the current effective policies would raise an INV_POLICY exception. If the current effective policies are incompatible, a sequence of type PolicyList is returned listing the incompatible policies.
|
The PolicyManager is an interface that provides methods for getting and setting Policy overrides for the VisiBroker ORB level.
|
•
|
get_policy_overrides returns a PolicyList sequence of all the overridden policies for the requested PolicyTypes. If the specified sequence is empty, all Policy overrides at the current context level will be returned. If none of the requested PolicyTypes are overridden at the target PolicyManager, an empty sequence is returned.
|
|
•
|
set_policy_overrides modifies the current set of overrides with the requested list of Policy overrides. The first input parameter, policies, is a sequence of references to Policy objects. The second parameter, set_add, of type SetOverrideType indicates whether these policies should be added onto any other overrides that already exist in the PolicyManager using ADD_OVERRIDE, or they should be added to a PolicyManager that doesn't contain any overrides using SET_OVERRIDES. Calling set_policy_overrides with an empty sequence of policies and a SET_OVERRIDES mode removes all overrides from a PolicyManager. Should you attempt to override policies that do not apply to your client, NO_PERMISSION will be raised. If the request would cause the specified PolicyManager to be in an inconsistent state, no policies are changed or added, and an InvalidPolicies exception is raised.
|
The DeferBindPolicy determines if the VisiBroker ORB will attempt to contact the remote object when it is first created, or to delay this contact until the first invocation is made. The values of DeferBindPolicy are true and false. If DeferBindPolicy is set to true all binds will be deferred until the first invocation of a binding instance. The default value is false.
If you create a client object, and DeferBindPolicy is set to true, you may delay the server startup until the first invocation. This option existed before as an option to the Bind method on the generated helper classes.
The RelativeConnectionTimeoutPolicy indicates a timeout after which attempts to connect to an object using one of the available endpoints is aborted. The timeout situation could happen in various circumstances, for example with objects protected by firewalls, where HTTP tunneling is the only way to connect to the object.
RebindPolicy accepts values of type Messaging::RebindMode to define the behavior of the client when rebinding. RebindPolicies are set only on the client side. It can have one of six values that determine the behavior in the case of a disconnection, an object forwarding request, or an object failure. The supported values are:
|
•
|
Messaging::TRANSPARENT allows the VisiBroker ORB to silently handle object-forwarding and necessary reconnections during the course of making a remote request.
|
|
•
|
Messaging::NO_REBIND allows the VisiBroker ORB to silently handle reopening of closed connections while making a remote request, but prevents any transparent object-forwarding that would cause a change in client-visible effective QoS policies. When RebindMode is set to NO_REBIND, only explicit rebind is allowed.
|
|
•
|
Messaging::NO_RECONNECT prevents the VisiBroker ORB from silently handling object-forwards or the reopening of closed connections. You must explicitly rebind and reconnect when RebindMode is set to NO_RECONNECT.
|
|
•
|
QoSExt::VB_TRANSPARENT is the default policy. It extends the functionality of TRANSPARENT by allowing transparent rebinding with both implicit and explicit binding. VB_TRANSPARENT is designed to be compatible with the object failover implementation in VisiBroker 3.x.
|
|
•
|
QoSExt::VB_NOTIFY_REBIND throws an exception if a rebind is necessary. The client catches this exception, and binds on the second invocation. If a client has received a CloseConnection message before, it will also reestablish the closed connection.
|
|
•
|
QoSExt::VB_NO_REBIND does not enable failover. It only allows the client VisiBroker ORB to reopen a closed connection to the same server; it does not allow object forwarding of any kind.
|
Be aware that if the effective policy for your client is VB_TRANSPARENT and your client is working with servers that hold state data, VB_TRANSPARENT could connect the client to a new server without the client being aware of the change of server, any state data held by the original server will be lost.
If the Client has set RebindPolicy and the RebindMode is anything other that the default(VB_TRANSPARENT), then the RebindPolicy is propagated in a special ServiceContext as per the CORBA specification. The propagation of the ServiceContext occurs only when the client invokes the server through a GateKeeper or a RequestAgent. This propagation does not occur in a normal Client/Server scenario.
In the case of NO_REBIND or NO_RECONNECT, the reopening of the closed connection or forwarding may be explicitly allowed by calling _validate_connection on the CORBA::Object interface.
The following table describes the behavior of the different RebindMode types.
The RelativeRequestTimeoutPolicy indicates the relative amount of time which a Request or its responding Reply may be delivered. After this amount of time, the Request is canceled. This policy applies to both synchronous and asynchronous invocations. Assuming the request completes within the specified timeout, the Reply will never be discarded due to timeout. The timeout value is specified in hundreds of nanoseconds. This policy is only effective on established connections, and is not applicable to establishing a connection.
The RelativeRoundTripTimeoutPolicy specifies the relative amount of time for which a Request or its corresponding Reply may be delivered. If a response has not yet been delivered after this amount of time, the Request is canceled. Also, if a Request had already been delivered and a Reply is returned from the target, the Reply is discarded after this amount of time. This policy applies to both synchronous and asynchronous invocations. Assuming the request completes within the specified timeout, the Reply will never be discarded due to timeout. The timeout value is specified in hundreds of nanoseconds.
The SyncScopePolicy defines the level of synchronization for a request with respect to the target. Values of type SyncScope are used in conjunction with a SyncScopePolicy to control the behavior of one-way operations.
The default SyncScopePolicy is SYNC_WITH_TRANSPORT. To perform one-way operations via the OAD, you must use SyncScopePolicy=SYNC_WITH_SERVER. Valid values for SyncScopePolicy are defined by the OMG.
Applications must explicitly set an VisiBroker ORB-level SyncScopePolicy to ensure portability across VisiBroker ORB implementations. When instances of SyncScopePolicy are created, a value of type Messaging::SyncScope is passed to CORBA::ORB::create_policy. This policy is only applicable as a client-side override.
|
Raised when there is an incompatibility between Policy overrides.
|
|
|
Raised when the RebindPolicy has a value of NO_REBIND, NO_RECONNECT, or VB_NO_REBIND and an invocation on a bound object references results in an object-forward or location-forward message.
|
|
|
Raised when the requested Policy is not supported.
|
|
|
Raised when an operation is passed a PolicyList sequence. The exception body contains the policies from the sequence that are not valid, either because the policies are already overridden within the current scope, or are not valid in conjunction with other requested policies.
|