Galaxy Communicator Documentation:

Coordinating Locations of Hub and Server Listeners

License / Documentation home / Help and feedback

By default, servers start up listeners on their default ports, and the Hub contacts them. Alternatively, you can set up a listener in the Hub and have the server contact the Hub instead. In both these cases, the programmer needs to make sure that the server entries in the Hub program file, the default server header, and the server command line arguments all correspond to each other, so that the Hub and servers can connect. Not only can this be a difficult and unreliable procedure, but it's also possible that multiple instances of the same Communicator system might be running at the same site on different sets of machines. In this latter case, the scripts and program files for the system would typically have to be modified for each invocation (or separate versions would need to be maintained). The overhead of this chore can be extremely frustrating.

In version 3.0, we've implemented a simple solution to address this issue.

The server locations file

Both the Hub and servers now accept a -server_locations_file command line argument which names a file which describes where the listeners are located. The format of each meaningful line of this file should be as follows:

<entry_name> <listener_host_or_ip>":"<listener_port> ["hub"|"server"]

In other words, each entry is a triple, with the entries delimited by whitespace. The first element of each triple is an entry name, which is a character sequence. The second entry is a token consisting of a host name or IP address, followed by a colon (":"), followed by a port number. The third entry is either the token hub or the token server. We've provided an example.

In addition to the meaningful lines described above, all lines consisting entirely of whitespace are ignored, as are all lines whose first non-whitespace character is a hash mark ("#"). There can be any nonempty amount of whitespace in between the three tokens in each meaningful line.

The interpretation of this file differs slightly depending on whether the Hub or a server is looking at it. We'll start with the Hub side.

The Hub's view of the server locations file

On the Hub side, <server_name> is either a provider name or the name of a service type. If the third element is the token hub, then the Hub uses <listener_port> as the port to set up a listener on, and <listener_host_or_ip> is ignored. If the third element is the token server, the Hub uses  <listener_host_or_ip>:<listener_port> as the contact information to use for updating on of its provider specifications. Each line is treated as a separate entry.

In general, each entry is able to override an existing declaration, and even switch the direction of connectivity, as long as there's no more than one element to override. Specifically, the rules for matching are as follows:

The server's view of the server location file

On the server side, things are a little different. First, the server is only looking for one entry: the one that it matches. It identifies this entry by matching the <server_name>. By default, it uses its own name (that is, the value of the GAL_SERVER_NAME macro). However, sometimes that's not useful. For instance, when the <server_name> is a Hub provider name, the server has no way of matching this entry against its own name, since the provider names are assigned by the Hub. If you want to provide an alternate name for the server to look up an entry in the server locations file, use the -slf_name argument.

If the third element of the matched entry is hub, the server updates itself to contact the Hub ad <listener_host_or_ip>:<listener_port> . If the third element of the matched entry is the token server, the server updates itself to set up a listener on <listener_port>, and <listener_host_or_ip> is ignored.

An example

For example, the following server locations file describes a situation where the Hub has a listener on port 3600 listening for connections from a provider of service type multiply, and a server which the Hub knows as having the provider name [double] opens up its own listener on port 5200. In addition, the multiply server will try to find that Hub listener on (so the Hub had better be running on that machine), and the Hub will try to find the [double] listener on (so the [double] server had better be running on that machine):

multiply hub
[double] server

So as long as the Hub starts up on and is passed this server locations file, and as long as the double server starts up on and is passed this server locations file with the appropriate index into the file, and as long as the multiply server starts up somewhere and is passed this server locations file, this system configuration will initialize itself appropriately:$ hub -server_locations_file double.loc
---------------------------------------------------------$ double -server_locations_file double.loc -slf_name "[double]"
----------------------------------------------------------$ multiply -server_locations double.loc

The result is that it's possible to configure a suite of servers and Hub with a single configuration file, and no scripts or program files need to be changed.

Note: this utility does not currently provide a facility for ensuring that the listener is started on the correct host. The crudest version of this support would be to shut down if the specified host wasn't the host the listener was running on, but it's not clear whether this would work for DHCP connections, for instance.

Server locations files and other command line arguments

The server locations files override all other port information. On the Hub side, it supersedes the host and port information in the program file and in the -locations command line argument. On the server side, it supersedes the information in the server declaration header file, as well as the -port and -contact_hub command line arguments. On both the Hub and server sides, the specified port for the listener is required; the listener startup process will not search for the first available port, but rather fail if the specified port is not available.

Note: this override mechanism only works in the Hub when there is at most one service provider for the named service type.

License / Documentation home / Help and feedback
Last updated August 23, 2002