Table of Contents

There is also a listing of tables, figures, and captioned examples.

Part I: Getting Started

Chapter 1: Introduction

• 1.1 Welcome
• 1.2 HydraExpress Features
• 1.3 For Users of HydraSCA
• 1.4 Organization of This Manual

Chapter 2: Building Web Services with HydraExpress

• 2.1 Overview
• 2.2 Supporting a Dynamic System
• 2.2.1 Configurable Transports and Message Handlers
• 2.2.2 Message Patterns and Asynchronous Messaging
• 2.2.3 Support for Named Objects
• 2.2.4 Dynamic Switching at Runtime
• 2.3 Handling of Complex Datatypes
• 2.4 Web Services and Service-Oriented Architecture (SOA)
• 2.5 Summary

Chapter 3: Creating a Web Service

• 3.1 Overview
• 3.2 Service Description
• 3.3 Invoking the Generator
• 3.4 The Generated Application Samples
• 3.4.1 The Client Proxy
• 3.4.1.1 Using the Client Proxy and the Client Implementation
• 3.4.2 The Service Implementation
• 3.5 Compiling and Running the Application
• 3.5.1 Compiling the Application
• 3.5.1.1 Compiling Using the Makefile
• 3.5.1.2 Compiling Using MSVC
• 3.5.2 Deploying the Service
• 3.5.2.1 Deploying with the makefile
• 3.5.2.2 Deploying Services Compiled with MSVC Project Files
• 3.5.3 Testing the Service
• 3.6 Next Steps

Chapter 4: Extending Your Web Service

• 4.1 Overview
• 4.2 Add a Secure Transport
• 4.3 Generate Code
• 4.4 Add a Special SOAP Header
• 4.4.1 Add the SOAP Header to the Generated Client
• 4.4.2 Edit the Server-Side Code to Return a Response Based on the Header
• 4.5 Compile, Deploy, and Run the Service
• 4.6 Next Steps

Chapter 5: Code Generator Basics

• 5.1 Overview
• 5.2 Invoking the Generator
• 5.3 Common Generator Options
• 5.4 Generated Files
• 5.5 Next Steps

Chapter 6: Complex Data Types

• 6.1 Overview
• 6.2 Service Description
• 6.3 The Generated Code
• 6.3.1 HTML Documentation
• 6.3.2 The Generated Data Types
• 6.3.3 The Data "main" Sample Application
• 6.4 Runtime Validation of simpleType Data
• 6.5 Next Steps

Part II: Client and Server Options

Chapter 7: Developing Clients

• 7.1 Overview
• 7.2 Developing and Running the Example
• 7.2.1 Service Description
• 7.2.2 Invoking the Generator
• 7.2.3 Using the Client Proxy
• 7.2.3.1 Looking at the Code
• 7.2.3.2 Using the Client Proxy
• 7.2.4 Compiling and Deploying the Client
• 7.3 Further Options
• 7.3.1 The Asynchronous Client API
• 7.3.2 Multithreading
• 7.3.3 Transports
• 7.3.4 Runtime Options
• 7.3.5 Client Security
• 7.3.5.1 Authorization
• 7.3.5.2 HTTPS Support
• 7.3.6 Error Reporting and Faults
• 7.3.7 WSDL-Defined Faults
• 7.3.8 Client-Side Logging
• 7.3.9 Turning off Text Escaping to Improve Performance
• 7.3.10 Customizing the Client Configuration Files
• 7.3.10.1 Transport Configuration File: client-transports.xml
• 7.3.10.2 Handlers Configuration File: client-handlers.xml
• 7.4 Next Steps

Chapter 8: Developing Services

• 8.1 Overview
• 8.2 Developing and Running the Example
• 8.2.1 Invoking the Generator
• 8.2.2 Using the Server Implementation
• 8.2.2.1 The Generated Abstract Base Class
• 8.2.2.2 The Generated Sample Implementation
• 8.2.2.3 The Provided Sample Implementation
• 8.2.3 Compiling the Service
• 8.2.3.1 Compiling Using the Makefile
• 8.2.3.2 Compiling Using MSVC
• 8.2.4 Deploying the Service
• 8.2.4.1 Deploying with the Makefile
• 8.2.4.2 Deploying Services Compiled with MSVC
• 8.2.5 Testing the Service
• 8.3 Further Options
• 8.3.1 Multithreading
• 8.3.1.1 A Note on Allocating Objects in Multi-threaded Applications
• 8.3.2 Service Security
• 8.3.3 Error Reporting and WSDL-Defined Faults
• 8.3.4 Implementing as a Standalone Server
• 8.3.5 Server-Side Logging
• 8.3.6 Session Management
• 8.3.7 Using a Different Implementation Name
• 8.3.8 Wrapped Style Operations
• 8.3.8.1 Developing a WSDL to Support the Wrapped Style
• 8.3.8.2 Generating Code with the -wrapped Option
• 8.3.8.3 Looking at the Generated Code
• 8.3.9 Turning off Text Escaping to Improve Performance
• 8.3.10 Accessing the Request URL
• 8.3.11 Customizing the Service Configuration Files
• 8.3.11.1 Transport Configuration File: server-transports.xml
• 8.3.11.2 Servlet Configuration File: web.xml
• 8.3.11.3 Service Chains Configuration File: handlers.xml
• 8.3.11.4 Named Objects Configuration File: objects.xml
• 8.4 Next Steps

Part III: Working with Message Patterns

Chapter 9: Introduction to Message Patterns

• 9.1 Overview
• 9.2 Message Patterns in WSDL
• 9.2.1 Weather Summary Service Description
• 9.2.2 The Request-Response Pattern
• 9.2.3 The One Way Pattern
• 9.2.4 The Notification Pattern
• 9.2.5 The Solicit-Response Pattern
• 9.2.6 Message Patterns and Asynchronicity
• 9.3 Architecture of the Notification Classes
• 9.4 Next Steps

Chapter 10: Implementing One Way and Notification Messages

• 10.1 Overview
• 10.2 Generating Code
• 10.2.1 Code Generation Outputs
• 10.3 Implementing the Service
• 10.3.1 The Request-Response Operation
• 10.3.2 The One Way and Notification Operations
• 10.3.2.1 The Notification Proxy
• 10.3.2.2 Implementing One Way and Notification
• 10.3.3 The Solicit Response Operation
• 10.4 Implementing the Client
• 10.4.1 The Request-Response Operation
• 10.4.2 The One Way Operation
• 10.4.2.1 Putting it All Together in the main() Function
• 10.4.3 Implementing the Client-Side Notification
• 10.4.4 Implementing Client Side Solicit-Response
• 10.4.5 Transport Configuration File Supporting Notification
• 10.5 Compiling, Deploying, and Running the Service
• 10.6 Summary

Part IV: Extending your Applications

Chapter 11: Dynamic Transports

• 11.1 Overview
• 11.2 Transport Configuration Files
• 11.3 Transport and Listener Properties
• 11.4 Autoconfiguring Listeners
• 11.5 Making Transports Dynamic
• 11.5.1 Selectable Transports
• 11.5.2 Interchangeable Transports
• 11.6 Creating a Transport
• 11.6.1 A Note on Multithread Safety

Chapter 12: Web Service Logging

• 12.1 Overview
• 12.2 Default Logging Levels
• 12.3 Using the Logger
• 12.3.1 The Client Logger
• 12.3.2 Configuring the Client Logger
• 12.3.3 Logging Without Using the Configuration File
• 12.4 The Server Logger

Chapter 13: Asynchronous Messaging

• 13.1 Overview
• 13.2 The Asynchronous API
• 13.2.1 Using the Asynchronous API
• 13.3 The Async Example
• 13.3.1 Implementing the Request/Response Method Asynchronously
• 13.3.2 Implementing the One-Way Method Asynchronously
• 13.3.3 Running the Async Example
• 13.4 Asynchronous Method Naming Conflicts

Chapter 14: SOAP Message Handler SDK

• 14.1 Overview
• 14.2 Types of SOAP Handlers
• 14.2.1 Transport Handlers
• 14.2.2 Request Handlers
• 14.2.3 Response Handlers
• 14.2.4 Fault Handlers
• 14.3 The Message Handler API
• 14.4 Creating Your Own Handlers
• 14.4.1 Generate Code
• 14.4.2 Write the Handler Implementation
• 14.4.2.1 Creating a Request Handler
• 14.4.2.2 Creating a Transport Handler
• 14.4.2.3 Aborting Handler Processing
• 14.4.3 Add the Handlers to the Proxy
• 14.4.4 Register the Handlers
• 14.4.5 Configure the Handlers
• 14.4.6 Compile and Deploy the Service
• 14.5 Chaining Handlers
• 14.5.1 Chaining Handlers on the Client
• 14.5.1.1 Client Side Chain Processing Order
• 14.5.2 Chaining Handlers on the Server
• 14.5.2.1 The handlers.xml Configuration File
• 14.5.2.2 Editing the handlers.xml File
• 14.5.2.3 Server Side Chain Processing Order
• 14.6 Adding Initialization Parameters to Handlers

Chapter 15: SOAP and Transport Headers

• 15.1 Overview
• 15.2 Architecture
• 15.3 Example
• 15.3.1 Client-Side Code
• 15.3.2 Server-Side Code
• 15.3.3 Viewing the Results
• 15.4 Uses for Header Support
• 15.5 Summary

Chapter 16: Named Objects

• 16.1 Overview
• 16.2 How HydraExpress Uses Named Objects
• 16.3 Using a Named Object for Database Connectivity
• 16.3.1 Creating the Object for Accessing a Database
• 16.3.2 Creating an Entry Point to the Object
• 16.3.3 Configuring the Named Object
• 16.3.4 Using the Named Object
• 16.3.4.1 Summary
• 16.3.5 Configuring Objects that are Also Handlers

Chapter 17: SOAP with Attachments

• 17.1 Overview
• 17.2 The SOAP with Attachments Specification
• 17.3 Working with Attachments
• 17.3.1 Example Service Description
• 17.3.2 Define the Attachment in WSDL
• 17.3.2.1 Define the Type
• 17.3.2.2 Define the Message Parts and Operation
• 17.3.2.3 Define the Binding
• 17.3.3 Generate Code and Manipulate the Attachment
• 17.3.3.1 Sending the Attachment
• 17.3.3.2 Accessing the Attachment
• 17.3.4 Build and Run the Example
• 17.4 Summary

Chapter 18: Sessions and State

• 18.1 Overview
• 18.2 Session Management in the Servlet Execution Engine
• 18.3 Manipulating a Service's Session Data
• 18.4 Configuring Session Timeouts

Chapter 19: Internationalizing Your Services

• 19.1 Overview
• 19.2 How HydraExpress Performs Character Conversions for Non-UTF-8 Encodings
• 19.2.1 Character Encoding in XML Schemas and WSDLs
• 19.2.2 Character Encoding in Generated Classes
• 19.3 Automatic Character Conversion through a Customized Mapping
• 19.3.1 Create a Customized Mapping
• 19.3.2 Add the Mapping to a HydraExpress Project File and Generate Code
• 19.3.2.1 Adding the mappings to an existing HydraExpress Project File
• 19.3.2.2 Creating a New HydraExpress Project File Containing the Mappings
• 19.3.2.3 A Look at the Generated Converter
• 19.4 Creating a Custom Character Converter
• 19.4.1 Generate Code
• 19.4.2 Create the Converter
• 19.5 Internationalization Concepts
• 19.5.1 What is a Character Encoding?
• 19.5.2 An Introduction to Unicode
• 19.5.3 Character Encoding in an XML Prolog

Part V: Exploring HydraExpress

Chapter 20: The HydraExpress Code Generator

• 20.1 Overview
• 20.2 Invoking the Generator
• 20.2.1 Introduction to the HydraExpress Project File
• 20.2.1.1 Using the HydraExpress Project File to Set Options
• 20.3 Invoking the Generator with an XML Schema
• 20.3.1 Architecture of the Generated Classes
• 20.3.2 Generated Files
• 20.3.2.1 HTML Documentation
• 20.3.2.2 Sample Application Files
• 20.3.2.3 C++ Makefiles
• 20.3.2.4 MSVC Project Files
• 20.3.3 Issues with Large Complex Schemas
• 20.4 Invoking the Generator with a WSDL File
• 20.4.1 Architecture of the Generated Classes
• 20.4.1.1 Server Classes
• 20.4.1.2 Client Classes
• 20.4.2 Generated Files
• 20.4.2.1 HTML Documentation
• 20.4.2.2 Sample Application Files
• 20.4.2.3 C++ Makefiles
• 20.4.2.4 MSVC Project Files
• 20.5 Generating Code with Multiple Schemas or WSDLs
• 20.5.1 A Note on Namespace Collisions
• 20.6 Generator Options
• 20.6.1 Adding Options and Customized Mappings to the HydraExpress Project File
• 20.6.1.1 Providing Customized Type Mappings to the Code Generator
• 20.6.2 Adding Outside Libraries, Includes or Compiler Properties to a Project
• 20.6.3 Conflicting Options and Property Precedence
• 20.6.3.1 Platform Properties and Startup Properties Files
• 20.6.3.2 The HydraExpress Project File
• 20.6.3.3 Command Line Options
• 20.7 Overwrite Protection
• 20.8 Validation Provided during Code Generation
• 20.8.1 WSDL Validation
• 20.8.2 Schema Validation
• 20.8.3 SOAP Message Validation

Chapter 21: The Project File and Directory Structure

• 21.1 Overview
• 21.2 The Project File
• 21.2.1 A Sample Project File
• 21.2.2 Adding Options to a Project File Vs. Adding them to the Command Line
• 21.2.3 Creating a Customized Project File for Special Generation Options
• 21.3 The Code Generation Directory
• 21.3.1 The Top-Level Code Generation Directory
• 21.3.2 The SubDirectories
• 21.3.2.1 The App Directory
• 21.3.2.2 The Bin Directory
• 21.3.2.3 The Codegen Directory
• 21.3.2.4 The Conf Directory
• 21.3.2.5 The Docs Directory
• 21.3.2.6 The Include Directory
• 21.3.2.7 The Lib Directory

Chapter 22: Options for Compiling

• 22.1 Overview
• 22.2 The Default Generated Makefiles
• 22.3 Makefile Options
• 22.3.1 The -noserver, -noclient, and -nosample Options
• 22.3.2 The -nomake Option
• 22.3.3 Support for Alternate Platforms
• 22.3.4 Customizing the Name of a Makefile
• 22.3.5 Adding Third Party Includes to Makefiles
• 22.3.6 Customizing Systems Properties
• 22.4 Using the Debug Makefiles
• 22.5 Procedure for Building with the Makefiles
• 22.5.1 Building just a Client or Server
• 22.5.2 Location of Generated Libraries and Binary Files
• 22.6 Using your own Makefile
• 22.7 Using MSVC Project Files
• 22.8 Next Steps

Chapter 23: Options for Deploying Services to the Agent

• 23.1 Overview
• 23.2 Deploying to the Servlet Execution Engine
• 23.2.1 Starting and Stopping the HydraExpress Agent
• 23.2.2 Agent Ports
• 23.2.3 Deploying your Service with the Makefile
• 23.2.4 Deploying your Service Using MSVC Files
• 23.2.5 Agent Options
• 23.3 Standalone Server Implementations
• 23.3.1 Standalone Server Options
• 23.3.2 Standalone Server Ports
• 23.3.3 Shutting down a Standalone Server
• 23.3.4 Configuring a Multithreaded Standalone Server or Listener
• 23.4 Configuring the Servlet Used by the Service

Part VI: Appendices

Appendix A: Code Generation Details

• A.1 Overview
• A.2 File Generation Conventions
• A.2.1 Naming Conventions
• A.2.2 Client-Side Classes
• A.2.3 Server-Side Classes
• A.2.4 Notification Classes
• A.2.5 Methods and Parameters
• A.2.5.1 Possible Naming Conflicts with Asynchronous Clients
• A.2.6 Configuration Files
• A.2.7 Makefile Naming Conventions
• A.3 Simple Type Mappings
• A.3.1 Mapping to Datatypes from Previous SourcePro Editions
• A.4 Complex Types
• A.5 SOAP Encoding
• A.5.1 SOAP-Encoded Arrays
• A.5.2 SOAP-Encoded Built-in Types and References
• A.5.3 Recursive Arrays
• A.6 SOAP Headers

Topic Index

© 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.