7.2 Developing and Running the Example

The client created in this tutorial uses the WSDL provided in the file DayOfWeek.wsdl located in the tutorials\webservices\DayOfWeek directory of your HydraExpress distribution. The WSDL file defines a single operation, GetDayofWeek, located at a port named DayOfWeekPortType. Since this tutorial focuses on the various options available to a client rather than designing an implementation, the service is deliberately simple. The operation receives a message containing an XML Schema date part. The operation returns a message containing an XML Schema string that holds the day of the week on the date provided.

Make sure that you have set up your environment as described in Chapter 2, "Installation," in the HydraExpress User's Guide.

Open a command prompt and change to the tutorials\webservices\DayOfWeek directory under the RWSF_HOME directory, as shown below:

In addition to the DayofWeek WSDL and the provided implementation files, this directory contains a HydraExpress project file, example-project.xml. This file provides custom configuration information to the generator. (For more information on the HydraExpress project file, see Section 22, "The Project File and Directory Structure."

If you open this file, you'll note that it identifies a value for the project-name attribute and a files element that references the DayofWeek.wsdl, so there is no need to include these items on the command line if this file is provided to the generator.

Run rwsfgen with example-project.xml as the sole argument, as follows:

prompt> rwsfgen example-project.xml

The above invocation is exactly the same as the following:

prompt> rwsfgen -projectname DayOfWeekExample -whitespace DayofWeek.wsdl

---

The two required options above are -projectname and the name of the file to parse. The project name is required, and may be entered directly into a HydraExpress project file or on the command line. Note that the name may not include spaces, as HydraExpress supports only file paths without spaces.

---

Since this chapter is primarily interested in creating a client to access the service, we could also choose to generate only a client, using an additional argument -noserver as follows:

 prompt> rwsfgen -noserver example-project.xml 

Since we will be using this example to also discuss server-side options in Chapter 7, we'll build both a client and server.

For full information on the various code generation options, see Chapter 21.6, "Generator Options."

HydraExpress generates server and client-side code, sample applications, configuration files, makefiles, MSVC project files, and documentation into a directory DayOfWeekExample, using the options included in the example-project.xml file. (HydraExpress supports only file paths without spaces, so when naming your project, do not include spaces, since HydraExpress uses the project name as a basis for the name of the code generation directory.)

Files are separated into several subdirectories according to type, as shown below:

  DayOfWeekExample/
     app/ 
        client
        server
     bin
     codegen/
        client
        server
     conf
     docs
     include/
        DayOfWeekExample
     lib

The directory app contains the sample implementations for the server and client, and the directory include contains relevant include and header files organized under project name. The conf directory contains the various configuration XML files used to configure transports, handlers, and named objects on the server side. The directory codegen contains generated code used to implement the service. The contents of this directory should not be modified.

The generator also produces HTML documentation. Single-click access is provided through the index.html file in the docs directory.

The directories bin and lib are empty at code generation, but will include the .exe and .dll files, and the .lib or .so files after the project build, depending on your platform.

For more information on this directory structure, see Section 22.3, "The Code Generation Directory."

Table 4 lists the generated files.

---

Files that are overwrite-protected are generated with a ".sample" extension if a file exists in the code generation directory of the same name. See Section 21.7, "Overwrite Protection."

---

Table 4: Files generated for DayofWeek example 

DayOfWeekExample/

DayOfWeekExample.xml

makefile
makefile_debug

makefile.include

[DayOfWeekExample.dsw or
DayOfWeekExample.sln]

deployDebug.bat deployRelease.bat

    app/

makefile
makefile_debug

        /client

DayOfWeekPortClient.cpp

makefile
makefile_debug

[DayOfWeekPortClient.dsp or
DayOfWeekPortClient.vcproj]

        /server

DayOfWeekPortTypeImp.cpp
DayOfWeekPortTypeImp.h

makefile
makefile_debug

[DayOfWeekPortService.dsp or
DayOfWeekPortService.vcproj]

    codegen/

makefile
makefile_debug

        /client

DayofWeekBindingProxy.cpp

makefile
makefile_debug

[DayOfWeekBindingClientLibrary.dsp or
DayOfWeekBindingClientLibrary.vcproj]

        /server

DayOfWeekBindingSkeleton.cpp
DayOfWeekPortTypeBase.cpp

makefile
makefile_debug 

[DayOfWeekPortService.dsp or
<DayOfWeekPortService.vcproj]

    conf/

server-transports.xml
client-transports.xml

dayofweek_handlers.xml

client-handlers.xml

dayofweek_objects.xml

dayofweek_web.xml

makefile 
makefile_debug

    docs/

index.html

    include/

      /DayOfWeekExample

DayOfWeekBindingProxy.h

DayOfWeekBindingSkeleton.h

DayOfWeekPortTypeBase.h

The proxy provides a set of five methods for each operation specified in the WSDL description. One pair of methods implements synchronous behavior; the remaining three methods implement asynchronous behavior. To send a message to the Web service, construct an instance of the proxy and invoke either the synchronous or asynchronous method(s) that correspond to the operation. The method returns the values defined in the WSDL file for the response message. (Appendix A describes type mappings for these values.)

The generated sample client implementation uses one of the synchronous methods for all operations, but you can easily change the implementation to create an asynchronous client. The asynchronous <operation-name>Start() method launches a thread for the operation so that the client can continue other processes while waiting for the server to respond. For more information on the client's asynchronous features, see Section 7.3.1, "The Asynchronous Client API.".

The generated header file for the client proxy contains the signatures for the generated service operation methods. The names of the methods that implement the operations in the WSDL file match the WSDL's operation names, with the first letter of the name converted to lower case. Parameter names match the part names in the WSDL file, with an underscore and the direction of the part appended to the name. For example, a part named tickerSymbol which is only used for input will have the name tickerSymbol_in, while an inout part named targetStruct will have the name targetStruct_inout. For details on naming conventions, see Appendix A.

The sample below shows the public interface for the client proxy, DayOfWeekBindingProxy.h located in the DayofWeekExample\include\DayofWeekExample directory.

The sample is reformatted slightly to fit on the page, and omits include statements, comments, and private members:

class DayOfWeekBindingProxyImp;
 
class DayOfWeekBindingProxy : public rwsf::Client                        //1
{
  public:
    static DayOfWeekBindingProxy make(                                   //2
      const std::string& location =
        "http://localhost:8090/dayofweek/DayOfWeek");
    static DayOfWeekBindingProxy make(                                   //3
        const rwsf::Transport& transport);
    static DayOfWeekBindingProxy make(                                   //4
        DayOfWeekBindingProxyImp *impl);

    DayOfWeekBindingProxy();                                             //5
    DayOfWeekBindingProxy(const DayOfWeekBindingProxy& proxy);  
    ~DayOfWeekBindingProxy();

    DayOfWeekBindingProxy& operator=(                                    //6
        const DayOfWeekBindingProxy& proxy);

    void setTransportProperty(const std::string& property,             //7
                              const std::string& value);

    // Operations:
    std::string getDayOfWeek(const std::string& date_in);                //8
    std::string getDayOfWeek(rwsf::CallInfo& callInfo, const 
       std::string& date_in);
    rwsf::AsyncHandle getDayOfWeekStart(const std::string& date_in);     //9
    rwsf::AsyncHandle getDayOfWeekStart(rwsf::CallInfo& info, const 
       std::string& date_in);
    std::string getDayOfWeekEnd(rwsf::AsyncHandle& handle);             //10

Use the proxy to implement your client application. HydraExpress creates a sample implementation you may use as a framework. This section discusses how to implement the proxy for a synchronous operation. For information on the asynchronous operation, see Section 7.3.1, "The Asynchronous Client API."

First, we'll look at the generated class, and then we'll see how we can easily edit it to implement the getDayofWeek method.

The generated sample implementation below shows the DayOfWeekPortClient.cpp file created by the rwsfgen program and located in the DayOfWeekExample\app\client directory. The sample is not a class, but a source file that includes the proxy header file and a main() function that invokes the proxy's methods.

#include "DayOfWeekExample/DayOfWeekBindingProxy.h"             //1
#include <iostream>

#include <include/webservice/DefaultLogger.h>
#include <include/webservice/HandlerManager.h>
#include <include/webservice/MessageHandler.h>
#include <include/webservice/transport/TransportManager.h>

void invoke_DayOfWeek(DayOfWeekBindingProxy& proxy)             //2
{
  std::string date_in;
  std::string dayOfWeek_ret;
  rwsf::CallInfo  callInfo;

  try {
    dayOfWeek_ret = proxy.getDayOfWeek(callInfo, date_in);
  } catch(const rwsf::SoapFaultException& e) {
    std::cout << "Fault Code: " << e.getFault().getFaultcode().asString() 
        << std::endl;
    std::cout << "Fault String: " << e.getFault().getFaultstring() << std::endl;
  }
}

void logError(std::string error, std::string detail) {
  rwsf::HandlerManager::invokeLogger(error + ": " + detail,
     rwsf::CallInfo::Error);
}

using rwsf::DefaultLogger;
RWSF_DEFINE_STATIC_MESSAGE_HANDLER("RWSFClientLogger",DefaultLogger)

int main(int argc, char* argv[]) 
{

  std::string location;                                       //3

  if (argc < 2) {                                               
    location = "http://localhost:8090/dayofweek/DayOfWeek";
  }
  else if (argv[1][0]=='-' && argv[1][1]=='a') {
    location = "http://localhost:8013/dayofweek/DayOfWeek";
  }
  else if (argv[1][0]=='-' && argv[1][1]=='l') {
    location = "http://localhost:8090/dayofweek/DayOfWeek";
  }
  else {
    location = argv[1];
  }
      try {
    // initialize config files                                  //4
    rwsf::NamingContext::loadGlobal("C:/RogueWave/Hydra/examples/webservices/
          DayOfWeek/DayOfWeekExample/conf/client-objects.xml");
    rwsf::HandlerManager::loadConfiguration("C:/RogueWave/Hydra/examples/
          webservices/DayOfWeek/DayOfWeekExample/conf/client-handlers.xml");

    rwsf::TransportManager::initialize("C:/RogueWave/Hydra/examples/webservices/
          DayOfWeek/DayOfWeekExample/conf/client-transports.xml");


    DayOfWeekBindingProxy proxy =
        DayOfWeekBindingProxy::make(location);                  //5

    if(!proxy.isValid()) {
      std::cerr << "Unable to create proxy. " << "\nExiting" <<
         std::endl;
      return 1;
    }
    invoke_getDayOfWeek(proxy);                                 //6

  } catch (const rwsf::Exception& x) {                          //7
    std::cerr << "rwsf::Exception thrown: "
              << x.what() << std::endl;
    return 1;
  } catch(const std::exception& x) {
    std::cerr << "std::exception thrown:" << std::endl
              << x.what() << std::endl;
    return 1;
  } catch(...) {
    std::cerr << "Unknown exception thrown" << std::endl;
    return 1;
  }
  return 0;
}

To create a working client, simply implement the invoke_getDayOfWeek method, replacing the generated code with your own.

In this case we will use the implemented client application DayOfWeekPortClient.cpp provided in the directory <installdir>\tutorials\webservices\DayofWeek.

The code below shows how the shipped file implements the service operation method invoke_getDayofWeek().

void invoke_getDayOfWeek(DayOfWeekBindingProxy& proxy)
{
  std::string date_in; 
  std::cout << "Enter date: " << std::flush;
  std::cin >> date_in;
  
  if (!date_in.isValid()) {
    std::cout << "Error: Invalid date" << std::endl;
    return;
  }
  else {
    rwsf::DateTime today;
    std::string toBe;
    std::string dayOfWeek_ret;    
    
    if (date_in < today) {
     toBe = " was a ";
    } else if (date_in == today) {
     toBe = " is a ";
    } else {
     toBe = " will be a ";
    }
    rwsf::CallInfo info;

    try {
      dayOfWeek_ret = proxy.getDayOfWeek(info, date_in);
      std::cout << date_in << toBe << dayOfWeek_ret << std::endl;    
    } catch(const rwsf::SoapFaultException& e) {
      std::cout << "Fault Code: " << e.getFault().getFaultcode().asString()
      << std::endl;
      std::cout << "Fault String: " << e.getFault().getFaultstring() 
      << std::endl;
    }
  }
}
...

Class rwsf::DateTime correctly parses many common date formats. The client uses this class to simplify the process of converting input from the console into the ISO8601 format that the schema requires.

At this point the client is implemented and ready to compile. The service now needs to be implemented; then both can be built and the service can be deployed to the HydraExpress Agent. Chapter 8 discusses how to implement the service, and Section 8.2.3 discusses building the client and service, and deploying the service.

©2004-2007 Copyright Quovadx, Inc. All Rights Reserved.
Quovadx and Rogue Wave are registered trademarks of Quovadx, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.