Using an Autoconfigured Listener

HydraExpress Web Service Development Guide
Rogue Wave web site: Home Page | Main Documentation Page

11.4 Using an Autoconfigured Listener

You may choose to autoconfigure your HTTP and HTTPS listener. Autoconfiguration may be useful for several reasons -- for instance, to avoid binding a listener to a port already in use, or to allow your service to be moved to a different machine without having to revise the configuration files.

Once the listener has been bound to a local address (in the rwsf::MessageListener::start() method), the "bound-host", "bound-ip", and "bound-port" properties are set to the host name, ip address, and port of the address. For example, let's look at the generated client configuration file client-transports.xml for HTTP.

<rwsf:listener name="HTTP"
  uri="http://schemas.xmlsoap.org/soap/listener/http" scheme="http"
  default="true" class="rwsf_webservice.createHttpMessageListener">
   <rwsf:property name="auto-start" value="false"/> 
   <!-- When host and port listener properties are absent, 
         they will be auto-configured to the machine's host name 
         and first available port. The machine will need to be
         configured for lookup on the network under its host name. -->
   <rwsf:property name="host" value="localhost"/> 
   <!-- <rwsf:property name="port" value="9000"/> -->
   <rwsf:property name="request-backlog" value="5"/>
   <rwsf:property name="request-timeout" value="60000"/>
   <rwsf:property name="request-buffersize" value="4096"/>
   <rwsf:property name="keep-alive" value="true"/>
 </rwsf:listener>

Note that the "port" property is commented out, allowing the listener location to be dynamically assigned. If you do not want a dynamic assignment, uncomment this property and enter a value.

Another way to implement auto-assignment is to comment out the host property. In other words, your applications could have a fixed host with an automatically-assigned port, or a fixed port, with an automatically-assigned host.

(The bound-host, bound-port, and bound-ip properties will also reflect these values.)

It is easy to use an auto-configured listener in your applications. Following are some excerpts from WeatherSummaryClient.cpp, the provided sample implementation in the WeatherSummary example implementing listener auto-configuration. (This example is located in your <installdir>\examples\webservices\WeatherSummary directory.)

Before accessing the autoconfigured properties, first set up and start a listener:

#include <rwsf/webservice/listener/MessageListener.h>                     //1


rwsf::MessageHandler service = 
    rwsf::HandlerManager::findHandler("WeatherSummaryNotificationService");  //2

rwsf::MessageListener listener;                                          //3
if (transportName.empty()) {
  listener = rwsf::TransportManager::findListenerByUrl(location);      
} else {
  listener = rwsf::TransportManager::findListener(transportName);      

if (listener.isValid()) {                                                //4
  std::cout << "Starting Listener..." << std::endl << std::endl;
  listener.setHandler(service);                                          //5
  listener.start();                                                      //6
}
else {
  std::cerr << "Unable to find a listener of name: " << transportName << std::endl;
  std::cerr << "Exiting." << std::endl;
  return 1;
}

`//1`	Necessary include.
`//2`	Gets the service, defined in the `client-handler.xml` file as this example uses a notification message pattern.
`//3`	Creates an instance of the listener either by name or by location, i.e. URL.
`//4`	Tests that the listener has been found and created properly.
`//5`	The `setHandler()` method is used to set the service that will handle a message. The service is loaded from `client-handlers.xml` by *rwsf::HandlerManager*, and retrieved by name, in line `//2`.
`//6`	Starts the listener.

Once the listener is started, it can get its auto-configured properties, and invoke the subscribe operation with the values:

...

std::cout << "Subscribing to WeatherSummary service..." << std::endl;
std::string host = listener.getProperty("bound-ip");
std::string port = listener.getProperty("bound-port");
std::string scheme = listener.getProperty("name");
bool status;
std::string msg;
proxy.subscribe(host, port, scheme, status, msg);
...

Note the call listener.getProperty("bound-ip") and listener.getProperty("bound-port"). These calls return the auto-configured values for the IP address and the port.

The Rogue Wave name and logo are registered trademarks of Rogue Wave Software, and HydraExpress is a trademark of Rogue Wave Software. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.