Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 3 Performing Basic TIBCO ActiveSpaces Tasks : Connecting to the Metaspace

Connecting to the Metaspace
Typically, one of the first things an ActiveSpaces process does is connect to a metaspace.
Before an application can do anything with ActiveSpaces, it must be connected to a metaspace.
As mentioned in Chapter 2, TIBCO ActiveSpaces Fundamentals, there are two modes of connection to a metaspace—as a full peer or as a remote client. Regardless of the connection mode, the API calls to use to connect to a Metaspace are the same.
The Metaspace.connect() method—or, in C, the tibasMetaspace_Connect() call—has two input parameters:
The tibasMetaspace_Connect() function returns a metaspace object that you can use to define a space or join a space. The input parameters are explained in more detail in the sections that follow.
Metaspace Name
The metaspace name is a string containing the name of a particular metaspace instance. The name can not start with a $ or _, and cannot contain the special characters., >, or *. If null or an empty string is given as argument to the connect call, the default metaspace name of ms will be used.
MemberDef Object
The MemberDef object contains the attributes of the connection to the metaspace:
Discovery Attribute
The discovery attribute specifies how this instance of the metaspace discovers the current metaspace members.
The format of the discovery attribute determines the mode of connection to the metaspace (either as a full peer or as a remote client).
When your application is connecting as a full peer, the discovery attribute specifies how this instance of the metaspace is used.
Discovery can be unicast (TCP) or multicast (PGM —Pragmatic General Multicast or TIBCO Rendezvous—RV).
There are three different discovery protocols:
See PGM (Pragmatic General Multicast) URL format.
See TIBCO Rendezvous Discovery URL format.
See TCP Discovery URL format.
To become members of the same metaspace, all intended members of a metaspace must use compatible discovery URLs. If the members do not specify compatible discovery URLs, then they are not connected to the same metaspace.
For example, if two metaspace members attempt to connect to the same metaspace using different discovery protocols, two different metaspaces are created and the two members are in different metaspaces. For example, if one application connects to a metaspace named ms using tibrv as its discovery URL, and another connects to a metaspace named ms using tibpgm as its discovery URL, since tibrv and tibpgm are two incompatible discovery protocols, two independent metaspaces, with the same name, are created instead of a single one.
PGM (Pragmatic General Multicast) URL format
With PGM, discovery of the current metaspace members is done by using reliable IP multicast. The attributes of this discovery mechanism are expressed in the form of an URL in the following format:
tibpgm://[dport]/[interface];[discovery group address]/[option=value;]*
where
dport specifies the destination port used by the PGM transport protocol. If not specified, the default value of 7888 is used.
interface;discovery group address specifies the address of the interface to be used for sending discovery packets, and the discovery group address to be used. If not specified, it will default to the default interface and discovery address, 239.8.8.8.
optional transport arguments a semicolon-separated list of optional PGM transport arguments. For example:
source_max_trans_rate=100000000 (in bits per second) would limit the PGM transport to limit its transmission rate to 100 megabits per second.
 
 
TIBCO Rendezvous Discovery URL format
The discovery URL for use with TIBCO Rendezvous has the following format:
tibrv://[service]/[network]/[daemon]
The syntax indicates that Rendezvous is used as the discovery transport, and that the optional service, network, and daemon Rendezvous transport creation arguments can be specified, separated by slashes, as shown.
service specifies the Rendezvous service number (UDP port) that will be used. If not specified, it will default to 7889.
network specifies the interface and the discovery group address that will be used to send the Rendezvous discovery packets. The format is:
      interface;discovery_group_address
If not specified, ActiveSpaces uses the default interface and discovery group address 239.8.8.9 (so the URL will be equivalent to tibrv://7889/;239.8.8.9/). If an interface is specified (by IP address, hostname, or by interface name) do not forget to also specify a discovery group address otherwise Rendezvous will revert to using broadcast rather than discovery (for example, to specify usage of the interface identified by IP address 192.168.1.1 use the URL: tibrv:///192.168.1.1;239.8.8.9/).
daemon specifies where to find the Rendezvous daemon. If not specified, it will try to connect to a local daemon on port 7500.
TCP Discovery URL format
When multicast discovery is not desirable or possible, you can use pure TCP discovery. In this case, a number of metaspace members are designated as the “well known” members of the metaspace, and all metaspace members must specify this exact same list of well known members in their discovery URL. At least one of the members listed in the discovery URL must be up and running for the metaspace to exist.
Each well known member is identified by an IP address and a port number. This address and the port are those specified by the well known member's Listen URL (if the member did not specify a Listen URL then the discovery process will use it's default IP address and the first free TCP port it can acquire from the OS (starting at port 50000 and above). See the following section for more information on the Listen URL).
The discovery URL to use well known address TCP discovery has the following format:
tcp://ip1[:port1];ip2[:port2],...
Where any number of ip[:port] well-known addresses can be listed. If no port is specified, the default port number value of 50000 is assumed.
.
.
Discovery URL format for remote clients
Remote clients connect to the seeder that is running as-agent by calling the Java setremoteDiscovery method.
The discovery URL format is the same as the discovery URL for the listen attribute:
tcp://interface:port
 
Connecting as a remote client:
The discovery URL format for connecting to a metaspace as a remote client is
tcp://IP:port?remote=true
Where IP is the IP address and port is the TCP port number of a member of the metaspace that is connected as a full peer AND offering remote client connectivity (though the “remote listen” attribute of its metaspace connection).
For information on how remote clients connect to the seeder that is running as-agent, see Steps for Connecting a Remote Client.
Listen Attribute
Regardless of the mechanism used for the initial metaspace member discovery phase, the members of the metaspace always establish TCP connections to each other. The listen attribute lets the user specify the interface and the TCP port that the process will use to listen for incoming connections from new members to the metaspace, and specified in the form of a URL.
Listen URL format
To use a listen URL, use a string of the form:
   tcp://[interface[:port]]
This syntax specifies that the member should bind to the specified interface and the specified port when creating the TCP socket that will be used for direct communication between the members of the metaspace. If not specified, it will default to 0.0.0.0 (INADDR_ANY) for the interface and to the first available port starting from port 5000 and above.
A successful connection to the metaspace will return a valid instance of a Metaspace object, which can then be used to define, join or leave spaces.
See the entry for Metaspace in the TIBCO ActiveSpaces Java API Reference for more information about transport arguments.
MemberName Attribute
The MemberName attribute specifies a string that indicates the member name. Each member must have a unique name in the metaspace.
If no member name is provided at connection name, then a globally unique name is generated automatically. If a member name is provided but there is already another member of the metaspace connected with that name, then the connection fails.

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved