Quality of Service interfaces and classes

This section describes the VisiBroker for C++ implementation of the Quality of Service APIs. See “Core interfaces and classes” for information about creating policies.

CORBA::PolicyManager

class CORBA::PolicyManager

This class is used to set and access policy overrides at the VisiBroker ORB level. Policies defined at the VisiBroker ORB level override any system defaults. The instance belonging to the manager thread is accessible by using resolve_initial_reference("PolicyManager")and narrowing down to PolicyManager.

IDL definition

module CORBA {
interface PolicyManager {
     PolicyList get_policy_overrides(in PolicyTypeSeq ts);
void set_policy_overrides(in PolicyList policies,
in SetOverrideType set_add)
raises (InvalidPolicies);
};
};

Include file

Include the file corba.h when you use this class.

Methods

CORBA_PolicyList* get_policy_overrides (PolicyTypeSeq ts);

This method returns a policy list containing the policies of the requested policy types. If the specified sequence is empty (that is, if the length of the list is zero), all policies at this scope are returned. If none of the requested policy types is set at the target PolicyManager, an empty sequence is returned.

Parameter	Description
ts	A sequence containing the requested policy types.

void set_policy_overrides (const CORBA_PolicyList& policies, CORBA::SetOverrideType set_add)

This method updates the current set of policies with the requested list of policy overrides. To remove all overrides from a PolicyManager, invoke set_policy_overrides with an empty sequence of policies and a mode of SET_OVERRIDE.

Only certain policies that pertain to the invocation of an operation at the client end can be overridden using this operation. An attempt to override any other policy results in the raising of the CORBA::NO_PERMISSION exception. If the request would put the set of overriding policies for the target PolicyManager in an inconsistent state, no policies are changed or added, and the exception InvalidPolicies is raised. There is no evaluation of compatibility with policies set within other PolicyManagers.

Parameter	Description
policies	A sequence of references to Policy objects.
set_add	Indicates whether these policies should be added (ADD_OVERRIDE) to any other overrides that already exist in the PolicyManager or added to a clean PolicyManager free of any other overrides (SET_OVERRIDE).

CORBA::PolicyCurrent

class CORBA::PolicyCurrent

This class provides access to policies overridden at the thread level and is defined with operations for querying and applying quality of service values to a thread. Policies defined at the thread level override any system defaults or values set at the VisiBroker ORB level but not those at the Object level. The instance belonging to the current thread is accessible by using resolve_initial_reference("PolicyCurrent") and narrowing down to PolicyCurrent.

IDL definition

interface PolicyCurrent : PolicyManager, Current {
};

Include file

Include the file corba.h when you use this class.

CORBA::Object

class CORBA::Object

The VisiBroker Edition implementation of the Quality of Service API allows policies to be assigned to objects, threads, and VisiBroker ORBs. Policies assigned to Objects override all other policies.

IDL definition

#pragma prefix "omg.org"
module CORBA {
interface Object {
Policy get_client_policy(in PolicyType type);
Policy get_policy(in PolicyType type);
PolicyList get_policy_overrides(in PolicyTypeSeq types);
Object set_policy_overrides(in PolicyList policies,in SetOverrideType
set_add)
raises (InvalidPolicies);
boolean validate_connection(out PolicyList inconsistent_policies);
};
};

Include file

Include the file corba.h when you use this class.

Methods

CORBA::Policy_ptr get_client_policy(CORBA::PolicyType type);

Returns the effective overriding Policy for the object reference. The effective override is obtained by first checking for an override of the specified PolicyType at the Object scope, then at the Current scope, and finally at the VisiBroker ORB scope. If no override is present for the requested PolicyType, the system-dependent default value for that PolicyType is used. Portable applications are expected to set the desired "defaults" at the VisiBroker ORB scope since default Policy values are not specified.

CORBA::Policy_ptr get_policy(CORBA::PolicyType type);

Returns the effective Policy for the object reference. The effective Policy is the one that would be used if a request were made. This Policy is determined first by obtaining the effective override for the PolicyType as returned by get_client_policy.

The effective override is then compared with the Policy as specified in the IOR. The effective Policy is the intersection of the values allowed by the effective override and the IOR-specified Policy. If the intersection is empty, the system exception INV_POLICY is raised. Otherwise, a Policy with a value legally within the intersection is returned as the effective Policy. The absence of a Policy value in the IOR implies that any legal value may be used. To ensure the accuracy of the returned effective Policy, invoke non_existent or validate_connection on an object reference prior to get_policy. If get_policy is invoked prior to the object reference being bound, the returned effective Policy is implementation-dependent. In that situation, a compliant implementation may do any of the following: raise the exception CORBA::BAD_INV_ORDER, return some value for that PolicyType which may be subject to change once a binding is performed, or attempt a binding and then return the effective Policy. Note that if the RebindPolicy has a value of TRANSPARENT, the effective Policy may change from invocation to invocation due to transparent rebinding.

Note

In VisiBroker, this method gets the Policy assigned to an Object, thread or the VisiBroker ORB.

CORBA::Object_ptr set_policy_overrides(const CORBA_PolicyList& _policies, CORBA::SetOverrideType _set_add);

This method works as does the PolicyManager method of the same name. However, this method updates the current set of policies of an Object, thread or the VisiBroker ORB with the requested list of Policy overrides. In addition, this method returns a CORBA::Object whereas other methods of the same name return void.

CORBA::Boolean validate_connection(CORBA_PolicyList& inconsistent_policies);

Returns the value TRUE if the current effective policies for the Object will allow an invocation to be made. If the object reference is not yet bound, a binding will occur as part of this operation. If the object reference is already bound, but current policy overrides have changed or for any other reason the binding is no longer valid, a rebind will be attempted regardless of the setting of any RebindPolicy override. The validate_connection operation is the only way to force such a rebind when implicit rebinds are disallowed by the current effective RebindPolicy. The attempt to bind or rebind may involve processing GIOP LocateRequests by the VisiBroker ORB.

This method returns the value FALSE if the current effective policies would cause an invocation to raise the system exception INV_POLICY. If the current effective policies are incompatible, the out parameter inconsistent_policies contains those policies causing the incompatibility. This returned list of policies is not guaranteed to be exhaustive. If the binding fails due to some reason unrelated to policy overrides, the appropriate system exception is raised.

Messaging::RebindPolicy

class Messaging::RebindPolicy

The VisiBroker implementation of RebindPolicy is a complete implementation of RebindPolicy as defined in the Messaging Specification with enhancements to support failover.

The RebindPolicy of the VisiBroker ORB determines how it handles GIOP location-forward messages and object failures. The VisiBroker ORB handles fail-over/rebind by looking at the effective policy at the CORBA::Object instance.

The OMG implementation, derived from CORBA::Policy, determines whether the VisiBroker ORB may transparently rebind once it is successfully bound to a target server. The extended implementation determines whether the VisiBroker ORB may transparently failover once it is successfully bound to a target Object, thread, or VisiBroker ORB.

IDL definition

#pragma prefix "omg.org"
module Messaging {
typedef short RebindMode;
const CORBA::PolicyType REBIND_POLICY_TYPE = 23;
local interface RebindPolicy CORBA::Policy {
readonly attribute RebindMode rebind_mode;
};
};

Include file

Include the file corba.h when you use this class.

Policy values

Note

Policies are enforced only after a successful bind.

The OMG Policy values that can be set as the Rebind Policy are:

Policy Value	Description
TRANSPARENT	This policy allows the VisiBroker ORB to silently handle object-forwarding and necessary reconnection when making a remote request. This is the least restrictive OMG policy value.
NO_REBIND	This policy 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 the client-side effective QoS policies.
NO_RECONNECT	This policy prevents the VisiBroker ORB from silently handling object-forwards or the reopening of closed connections. This is the most restrictive OMG policy value.

The VisiBroker-specific values that can be set as the Rebind Policy are:

Policy Value	Description
VB_TRANSPARENT	This policy extends TRANSPARENT behavior to failover conditions in the object, the thread and the VisiBroker ORB. This is the default policy. If this policy is set, if a remote invocation fails because the server object goes down, then the VisiBroker ORB tries to reconnect to another server using the osagent. The VisiBroker ORB masks the communication failure and does not throw an exception to the client.
VB_NOTIFY_REBIND	VB_NOTIFY_REBIND behaves as does VB_TRANSPARENT but throws an exception when the communication failure is detected. It will try to transparently reconnect to another object if the invocation is re-attempted.
VB_NO_REBIND	VB_NO_REBIND does no failover. It only allows the client VisiBroker ORB to reopen a closed GIOP re-connection to the same server; it does not allow object forwarding of any kind.

QoSExt::DeferBind Policy

class QoSExt::DeferRebindPolicy

By default, the VisiBroker ORB connects to the (remote) object when it receives a bind() or a string_to_object call.

If set to TRUE, this policy changes this behavior; it causes the VisiBroker ORB to delay contacting the Object until the first invocation.

IDL definition

#pragma prefix "inprise.com"
module QoSExt {
interface DeferBindPolicy :CORBA::Policy {
readonly attribute boolean value;
};
};

Include file

Include the file corba.h when you use this class.

QoSExt::RelativeConnectionTimeoutPolicy

class QoSExt::RelativeConnectionTimoutPolicy

The RelativeConnectionTimeoutPolicy indicates a timeout after which attempts to connect to an object using one of the available endpoints is aborted. The policy value of unsigned longlong type specifies the timeout in 100s of nanoseconds. It is applied to every endpoint that the VisiBroker ORB tries to connect to. Therefore, if multiple connection attempts are made, the elapsed time will be a multiple of the configured timeout. The default value of 0 sets the timeout value to that of the operating system default timeout.

Note

This Policy is not enforced for in-process communications.

IDL definition

module QoSExt {
const CORBA::PolicyType RELATIVE_CONN_TIMEOUT_POLICY_TYPE = 0x56495304;
local interface RelativeConnectionTimeoutPolicy :CORBA::Policy {
readonly attribute TimeBase::TimeT relative_expiry;
};
};

Include file

Include the file corba.h when you use this class.

Messaging::RelativeRequestTimeoutPolicy

class Messaging::RelativeRequestTimeoutPolicy

The RelativeRequestTimeoutPolicy specifies the maximum time that a client is to block waiting to send an operation request. If the request times out, CORBA::TIMEOUT exception is raised.

IDL definition

module Messaging{
const CORBA::PolicyType RELATIVE_REQ_TIMEOUT_POLICY_TYPE = 31;
local interface RelativeRequestTimeoutPolicy : CORBA::Policy {
readonly attribute TimeBase::TimeT relative_expiry;
};
};

Include file

Include the file corba.h when you use this class.

Messaging::RelativeRoundtripTimeoutPolicy

class Messaging::RelativeRoundtripTimeoutPolicy

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 100s of nanoseconds.This policy is also effective in the initial establishment of a connection.

IDL definition

module Messaging{
const CORBA::PolicyType RELATIVE_RT_TIMEOUT_POLICY_TYPE = 32;
local interface RelativeRoundtripTimeoutPolicy : CORBA::Policy {
readonly attribute TimeBase::TimeT relative_expiry;
};
};

Include file

Include the file corba.h when you use this class.

Messaging::SyncScopePolicy

class Messaging::SyncScopePolicy

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.

IDL definition

module Messaging{
const CORBA::PolicyType SYNC_SCOPE_POLICY_TYPE = 24;
const SyncScope SYNC_NONE = 0;
const SyncScope SYNC_WITH_TRANSPORT = 1;
const SyncScope SYNC_WITH_SERVER = 2;
const SyncScope SYNC_WITH_TARGET = 3;
local interface SyncScopePolicy : CORBA::Policy {
readonly attribute SyncScope synchronization;
};
};

Include file

Include the file corba.h when you use this class.