A.2 File Generation Conventions

This section describes the conventions HydraExpress follows when creating C++ classes and other supporting files.

In general, the class names are based on names extracted from the WSDL file. In using these names, HydraExpress removes any namespace prefix, ensures that the first letter of the name is uppercase, and translates characters that are not legal C++ identifiers to underscores.

Below is an abbreviated WSDL file illustrating the names that are used in creating class names. The example class names in the sections below use this WSDL.

<definitons ...>
  <!-- message definitions -->
  <portType name="GetSkiReport">                                //1
    ...
  </portType>
  <binding name="GetSkiReportSOAPBinding"                       //2
    type="tns:GetSkiReport">
    <soap:binding style="rpc" 
      transport="http://schemas.xmlsoap.org/soap/http"/>        //3
    ...
  </binding>
  <portType name="GetInternationalSkiReport">                   //4
    ...
  </portType>
  <binding name="GetInternationalSkiReportSOAPBinding"          //5
    type="tns:GetSkiReport">
    <soap:binding style="rpc" 
      transport="http://schemas.xmlsoap.org/soap/http"/>        //6
    ...
  </binding>
  <service name="GetUSASkiReportService">                       //7
    <port binding="tns:GetSkiReportSOAPBinding"
      name="GetUSASkiReport">                                   //8
      <soap:address location="http://localhost:8080/etc"/>
    </port>
  </service>
  <service name="GetCanadianSkiReportService">                  //9
    <port binding="tns:GetSkiReportSOAPBinding" 
      name="GetCanadianSkiReport">                             //10
      <soap:address location="http://localhost:8080/etc"/>
    </port>
  </service>
  <service name="GetInternationalSkiReportService">            //11
    <port binding="tns:GetInternationalSkiReportSOAPBinding" 
      name="GetInternationalSkiReport">                        //12
      <soap:address location="http://localhost:8080/etc"/>
    </port>
  </service>
</definitions>

HydraExpress creates a client proxy class for each wsdl:portType. The name of each class is based on the name of the associated binding with the string Proxy appended.

The WSDL file shown above would create one proxy class for each of the two portType elements (lines //1 and //4). The class names would be based on the binding names (lines //2 and //5), resulting in the classes GetSkiReportSOAPBindingProxy and GetInternationalSkiReportSOAPBindingProxy.

HydraExpress also generates a sample client implementation for each service defined in the WSDL. The implementation file names are based on the name attribute of the port element associated with each service, lines //8, //10, and //12 above. The client implementation files for this WSDL would be GetUSASkiReportClient.cpp, GetCanadianSkiReportClient.cpp, and GetInternationalSkiReportClient.cpp.

HydraExpress creates two server classes for each portType, a message handling skeleton class and an implementation base class. The port must have an associated wsdl:binding that contains a soap:binding element. In the typical case, the soap:binding element has a transport attribute that specifies the HTTP transport: transport="http://schemas.xmlsoap.org/soap/http".

The name of the skeleton class is based on the port binding name with the string Skeleton appended. The WSDL file shown above would create one skeleton class for each of the two portType elements (lines //1 and //4). The class names would be based on the binding names (lines //2 and //5), resulting in the classes GetSkiReportSOAPBindingSkeleton and GetInternationalSkiReportSOAPBindingSkeleton.

The name of the implementation base class is based on the portType name with the string Base attached. The WSDL file shown above would create one implementation base class for each of the two portType elements (lines //1 and //4), resulting in the classes GetSkiReportBase and GetInternationalSkiReportBase.

HydraExpress also generates a sample implementation class for each implementation base class. The sample implementation class derives from the base class, and its name is the base class name with the final Base changed to Imp. For the above example, these classes would be GetSkiReportImp and GetInternationalSkiReportImp.

When the WSDL file defines a notification or a solicit-response service, additional classes are generated. Assume the addition of the following definitions for a notification service to the example WSDL file:

<portType name="NotifySkiReport">                             //1
  <!-- For notification, an operation with only an output -->
  <!-- For solicit-response, an operation with an output
       followed by an input -->
</portType>
<binding name="NotifySkiReportSOAPBinding"                    //2
  type="tns:NotifySkiReport">
  <soap:binding style="rpc" 
    transport="http://schemas.xmlsoap.org/soap/http"/>        //3
  ...
</binding>
<service name="NotifySkiReportService">                       //4
  <port binding="tns:NotifyReportSOAPBinding"
    name="NotifySkiReport">                                   //5
    <soap:address location="http://localhost:8080/etc"/>
  </port>
</service>

The client-side classes for notification mirror the usual server-side classes. There is a skeleton class whose name is based on the binding name (line //2) with the string NotificationSkeleton appended. The resulting class name would be NotifySkiReportSOAPBindingNotificationSkeleton. Then there are an implementation base class and a sample implementation class whose names are based on the portType name (line //1), resulting in the classes NotifySkiReportNotificationBase and NotifySkiReportNotificationImp.

On the server side, there is just a proxy class whose name is based on the binding name (line //2) with the string NotificationProxy appended. The resulting class would be NotifySkiReportSOAPBindingNotificationProxy.

Generated classes contain one method for each wsdl:operation in the wsdl:portType that the class represents. The name of the method is the operation name. HydraExpress converts the first letter of the name to lowercase, translates characters that are not legal in C++ identifiers to underscores, and appends "_op" to the name if the result is a C++ keyword. For example, the generator creates a method named currentTemperature for an operation named CurrentTemperature. The generator creates a method named test_operation for an operation named test.operation.

The generator names the arguments to the generated methods based on the names of the wsdl:part elements within the wsdl:message elements for the operation. The generator converts characters that are not legal C++ identifiers to underscores, and appends the direction of the part to the name. The direction is determined as follows:

• If a part name appears only in the input message, the part is an input part. The generator appends "_in" to the part name.

• If a part name appears in both the input message and the output message, the part is an inout part. The generator appends "_inout" to the part name.

• If there is a single output part, and the part name does not appear in the input message, that part is the return value of the method. The generator does not create a part name.

• If there is a part named return, and the part name return does not appear in the input message, that part is the return value of the method. The generator does not create a part name for that part.

• Any other parts in the output message are output parts. The generator appends "_out" to the part names.

If all return values are inout parts, the method signature will have a void return type. Note that the complete signature of the method depends on the C++ type mapping, described in Section A.3 and Section A.4.

When building an asynchronous client, be aware of possible naming collisions between your service operation names and the generated asynchronous service operation methods. Asynchronous methods are generated with a suffix start and end. For example, for the service operation getDayOfWeek, HydraExpress generates two asynchronous service operation methods getDayOfWeekStart() and getDayOfWeekEnd().

For more information, see Section 13.4, "Asynchronous Method Naming Conflicts."

For each project, HydraExpress either generates or copies from the <installdir>\conf directory a set of XML configuration files. For clients, these files are:

• client-transports.xml, which configures the transports the client uses to send messages, and the listener the client uses to listen for messages initiated by the server. This file is copied from the conf directory.

• client-handlers.xml, which configures the message handlers for the client. This file always includes at least a configured default logger. This file is generated.

• client-objects.xml, an optional file to configure client-side named objects to be loaded into the container. This file is generated only when the WSDL contains a notification message, and serves to configure the listener on the client.

For servers, the files are:

• server-transports.xml, which configures the transports the server uses to send messages to the client. For HTTP and HTTPS, there are no corresponding listeners because this functionality is inherent in the server. This file is copied from the conf directory.

• <servicecontextname>_handlers.xml, which configures the message handlers for the server. There is always at least a server implementation as the endpoint of the message handler chain. Usually there is a SOAP message handler as well. This file is generated.

• <servicecontextname>_objects.xml, which configures all named objects to be loaded into the service container. These objects include the transports and handlers configured in the other two files. This file is generated.

• <servicecontextname>_web.xml, which configures all named objects to be loaded into the service container. These objects include the transports and handlers configured in the other two files. This file is generated.

Note: The variable <servicecontextname> comes from the soap:address location in the service's WSDL document. For instance, in the following line:

<soap:address location="http://localhost:8090/dayofweek/DayOfWeek" />

the context is "dayofweek" just before the service name.

The default name for the generated makefiles is makefile and makefile_debug. You may customize the name of your makefiles using the -makefilename option when generating code. For more information, see Section 22.3.4, "Customizing the Name of a Makefile."

© Copyright Rogue Wave Software, Inc. All Rights Reserved. All Rights Reserved. Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. HydraExpress is a trademark of Rogue Wave Software, Inc. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.