Location service interfaces and classes

This section describes the interfaces you can use to locate object instances on a network of Smart Agents. For more information on the Location Service, see “Using the Location Service” in the VisiBroker for C++ Developer's Guide.

Agent

class Agent : public CORBA::Object

This class provides methods that enable you to locate all instances of a particular object on a network of Smart Agents. The methods offered by this class are divided into two categories: those that query a Smart Agent for data about objects and those that deal with triggers.

Your client application can obtain object information based on an interface repository ID alone or in combination with an instance name.

Triggers allow your client application to be notified of changes in the availability of one or more object instances.

IDL definition

interface Agent {
HostnameSeq all_agent_locations()
raises (Fail);
RepositoryIdSeq all_repository_ids()
raises (Fail);
ObjSeqSeq all_available()
raises (Fail);
ObjSeq all_instances (in string repository_id)
raises (Fail);
ObjSeq all_replica (in string repository_id, in string instance_name)
raises (Fail);
DescSeqSeq all_available_descs()
raises (Fail);
DescSeq all_instances_descs (in string repository_id)
raises (Fail);
DescSeq all_replica_descs (in string repository_id,
in string instance_name)
raises (Fail);
void reg_trigger(in TriggerDesc desc, in TriggerHandler handler)
raises (Fail);
void unreg_trigger(in TriggerDesc desc, in TriggerHandler handler)
raises (Fail);
attribute boolean willRefreshOADs;
};

Include file

You should include the locate_c.hh file when you use this class.

Agent methods

ObjLocation::HostnameSeq_ptr all_agent_locations();

Returns a sequence of host names representing the hosts on which osagent processes are currently executing.

See also

“<type>Seq”

This method throws the following exceptions:

Exception	Description
Fail	The FailReason values that may be presented include:NO_AGENT_AVAILABLE, AGENT_ERROR. For more information on the Fail class, see “Fail”.

ObjLocation::ObjSeqSeq all_available();

Returns a sequence of object references for all objects currently registered with some Smart Agent on the network.

See also

“<type>Seq”

This method throws the following exceptions:

Exception	Description
Fail	The FailReason values that may be presented include: NO_AGENT_AVAILABLE, AGENT_ERROR. For more information on the Fail class, see “Fail”.

ObjLocation::DescSeqSeq_ptr all_available_descs();

Returns descriptions for all objects currently registered with a Smart Agent on the network. The description information returned is organized by repository id.

See also

“<type>Seq”

This method throws the following exceptions:

Exception	Description
Fail	The FailReason values that may be presented include: NO_AGENT_AVAILABLE, AGENT_ERROR. For more information on the Fail class, see “Fail”.

ObjLocation::ObjSeq_ptr all_instances(const char *repository_id);

Returns a sequence of object references to all instances with the specified repository_id.

See also

“<type>Seq”

Parameter	Description
repository_id	The repository ID of the object references to be retrieved.

This method throws the following exceptions:

Exception	Description
Fail	Any of the FailReason values, other than NO_SUCH_TRIGGER, may be presented. For more information on the Fail class, see “Fail”.

ObjLocation::DescSeq_ptr all_instances_descs(const char *repository_id);

Returns description information for all object instances with the specified repository_id.

See also

“<type>Seq”

Parameter	Description
repository_id	The repository ID of the object descriptions to be retrieved.

This method throws the following exceptions:

Exception	Description
Fail	Any of the FailReason values, other than NO_SUCH_TRIGGER, may be presented. For more information on the Fail class, see “Fail”.

ObjLocation::ObjSeq_ptr all_replica(const char *repository_id, const char *instance_name);

Returns a sequence of object references for objects with the specified repository_id and instance_name.

See also

“<type>Seq”

Parameter	Description
repository_id	The repository ID of the object references to be retrieved.
instance_name	The instance name of the object references to be returned.

This method throws the following exceptions:

Exception	Description
Fail	Any of the FailReason values, other than NO_SUCH_TRIGGER, may be presented. For more information on the Fail class, see “Fail”.

ObjLocation::DescSeq_ptr all_replica_descs(const char *repository_id, const char *instance_name);

Returns a sequence of description information for all object instances with the specified repository_id and instance_name.

See also

“<type>Seq”

Parameter	Description
repository_id	The repository ID of the object descriptions to be retrieved.
instance_name	The instance name of the object descriptions to be retrieved.

This method throws the following exceptions:

Exception	Description
Fail	Any of the FailReason values, other than NO_SUCH_TRIGGER, may be presented. For more information on the Fail class, see “Fail”.

CORBA::StringSequence* all_repository_ids();

This method retrieves all interfaces known to any osagent. This method throws the following exception:

Exception	Description
Fail	The FailReason values that may be presented include NO_AGENT_AVAILABLE, AGENT_ERROR. For more information on the Fail class, see “Fail”.

void reg_trigger(const ObjLocation::TriggerDesc& desc,
ObjLocation::TriggerHandler_ptr hdlr);

Registers the trigger handler hdlr for object instances that match the description information specified in desc.

Note

A TriggerHandler is invoked every time an object that satisfies the trigger's description becomes available. If you are only interested in learning when the first instance of the object becomes available, you should use the unreg_trigger method to remove the trigger after the first notification is received.

Parameter	Description
desc	The object instance description information, which can contain combinations of the following information: repository ID, instance name, hostname. You can provide more or less information to narrow or widen the object instances to be monitored.
hdlr	The trigger handler object being registered.

This method throws the following exceptions:

Exception	Description
Fail	Any of the FailReason values, other than NO_SUCH_TRIGGER, may be presented. For more information on the Fail class, see “Fail”.

void unreg_trigger(const ObjLocation::TriggerDesc& desc, ObjLocation::TriggerHandler_ptr hdlr);

Unregisters the trigger handler hdlr for object instances that match the description information specified in desc.

Parameter	Description
desc	The object description information.
hdlr	The trigger handler object being unregistered.

This method throws the following exceptions:

Exception	Description
Fail	The only FailReason value possible is NO_SUCH_TRIGGER. For more information on the Fail class, see “Fail”.

CORBA::Boolean willRefreshOADs();

Returns TRUE if the set of Object Activation Daemon is updated each time a method offered by this class is invoked, otherwise returns FALSE. If the cache is not refreshed on each invocation, the following conditions may occur:

•	All objects are still reported, but their descriptor's activable flag may be incorrect.

•	Any attempt to verify the existence of an object registered with an OAD that has been started since the last refresh of the OAD cache causes those objects to be activated by the OAD.

void willRefreshOADs(CORBA::Boolean val);

This class maintains a set of Object Activation Daemons. This method enables or disables the automatic refreshing of the OADs contained in this set.

Parameter	Description
val	If TRUE, the OAD set will be refreshed whenever a method offered by this class is invoked.

Desc

struct Desc

This structure contains information you use to describe the characteristics of an object. You pass this structure as an argument to several of the Location Service methods described in the chapter. The Desc structure, or a sequence of them, is returned by some of the Location Service methods.

See also

“<type>Seq”

IDL definition

module ObjLocation {
struct Desc {
Object ref;
IIOP::ProfileBody iiop_locator;
string repository_id;
string instance_name;
boolean activable;
string agent_hostname;
};
. . .
};

Desc members

Object ref

A reference to the object being described.

IIOP::ProfileBody iiop_locator

Represents profile data for the object, described in “IIOP::ProfileBody”.

CORBA::String_var repository_id

The object's repository identifier.

CORBA::String_var instance_name

The object's instance name.

CORBA::Boolean activable

Set to TRUE to indicate that this object is registered with the Object Activation Daemon. It is set to FALSE to indicate that the object was started manually and is registered with the osagent.

CORBA::String_var agent_hostname

The name of the host running the Smart Agent with which this object is registered.

Fail

class Fail : public CORBA::UserException

This exception class may be thrown by the Agent class to indicate various errors. The data member FailReason is used to indicate the nature of the failure.

Fail members

FailReason reason

Set to one of the following values to indicate the nature of the failure:

enum FailReason {
NO_AGENT_AVAILABLE,
INVALID_REPOSITORY_ID,
INVALID_OBJECT_NAME,
NO_SUCH_TRIGGER,
AGENT_ERROR
};

TriggerDesc

struct TriggerDesc

This structure contains information you use to describe the characteristics of one or more objects for which you wish to register a TriggerHandler, described in “TriggerHandler” on page 279.

The host_name and instance_name members may be set to NULL to monitor the widest possible set of objects. The more information specified, the smaller the set of objects is.

IDL definition

module ObjLocation {
. . .
struct TriggerDesc {
string repository_id;
string instance_name;
string host_name;
};
. . .
};

TriggerDesc members

ORBA::String_var repository_id

The repository identifiers of the objects to be monitored by the TriggerHandler. May be set to NULL to include all possible repository identifiers.

CORBA::String_var instance_name

The instance name of the object to be monitored by the TriggerHandler. May be set to NULL to include all possible instance names.

CORBA::String_var host_name;

The host name where the object or objects monitored by the TriggerHandler are located. May be set to NULL to include all hosts in the network.

TriggerHandler

You use this base class to derive your own callback object to be invoked every time an object becomes available or unavailable. You specify the criteria for the object or objects in which you are interested. You register your TriggerHandler object using the Agent::reg_trigger method, described in “TriggerHandler” on page 279.

You must provide implementations for the impl_is_ready and impl_is_down methods.

IDL definition

interface TriggerHandler {
void impl_is_ready(in Desc desc);
void impl_is_down(in Desc desc);
};

Include file

You should include the locate_c.hh file when you use this class.

TriggerHandler methods

virtual void impl_is_ready(const Desc& desc);

This method is invoked by the Location Service when an object instance matching the criteria specified in desc becomes accessible.

Parameter	Description
desc	The object description information.

virtual void impl_is_down(const Desc& desc);

This method is invoked by the Location Service when an object instance matching the criteria specified in desc is no longer accessible.

Parameter	Description
desc	The object description information.

<type>Seq

This is a generalized class description for the following sequence classes used by the Location Service:

Class	Description
DescSeq	A sequence of Desc structures.
HostnameSeq	A sequence of host names.
ObjSeq	A sequence of object references.
RepositoryIdSeq	A sequence of repository identifiers.

Each class represents a particular sequence of <type>. The Location Service returns lists of information to your client application in the form of sequences which are mapped to one of these classes.

Each class offers operators for indexing items in the sequence just as you would a C++ array. Each class also offers methods for setting and obtaining the length of the array.

The code sample below shows the correct way to index a HostnameSeq returned from the Agent::all_agent_locations method.

. . .
ObjLocation::HostnameSeq_var hostnames(myAgent->all_agent_locations());
for (CORBA::ULong i=0; i < hostnames->length(); i++) {
cout << "Agent host #" << i+1 << ": " << hostnames[i] << endl;
}
. . .

See also

“<type>SeqSeq”

<type>Seq methods

<type>& operator[](CORBA::ULong index) const;

Returns a reference to the element in the sequence identified by index.

Caution

You must use a CORBA::ULong type for the index. Using an int type may lead to unpredictable results.

Parameter	Description
index	The zero-based index of the element to be returned.

This method throws the following exception:

Exception	Description
CORBA::BAD_PARAM	The index specified is less than zero or greater that the size of the sequence.

CORBA::ULong length() const;

Returns the number of elements in the sequence.

void length(CORBA::ULong len);

Sets the maximum length of the sequence to the value contained in len.

Parameter	Description
len	The new length for the sequence.

<type>SeqSeq

This is a generalized class description for the following classes used by the Location Service:

Class	Description
DescSeqSeq	A sequence of DescSeq objects.
ObjSeqSeq	A sequence of ObjSeq objects.

Each class represents a particular sequence of <type>Seq. Some Location Service methods return lists of information to your client application in the form of sequences of sequences which are mapped to one of these classes.

Each class offers operators for indexing items in the sequence just as you would a C++ array. The class also offer methods for setting and obtaining the length of the array.

See also

“<type>Seq”

<type>SeqSeq methods

<type>Seq& operator[](CORBA::ULong index) const;

Returns a reference to the element in the sequence identified by index. The reference is to a one dimensional sequence, described in “<type>Seq”

Caution

You must use a CORBA::ULong type for the index. Using an int type may lead to unpredictable results.

Parameter	Description
index	The zero-based index of the element to be returned.

This method throws the following exceptions:

Exception	Description
CORBA::BAD_PARAM	The index specified is less than zero or greater that the size of the sequence.

CORBA::ULong length() const;

Returns the number of elements in the sequence.

void length(CORBA::ULong len);

Sets the maximum length of the sequence to the value contained in len.

Parameter	Description
len	The new length for the sequence.