Practical Web Services on the System i

Article ID: 61749

Posted August 1st, 2008

Try two different ways to create web services

By:

In this article I outline two ways of creating web services from existing System i programs. The first approach is to deploy RPG programs in the new IBM Integrated Web Services Server for i, and the second is to create web services in Rational Developer for System i for SOA Construction (RDi SOA). In addition to giving step-by-step instructions, I explain the benefits of each implementation method and provide hints on how to successfully deploy web services in a production environment.

What Is a Web Service?

In IT terminology, a "service" is a program or procedure that performs a business task. Examples of such tasks are "register a user," "find an item in a catalog," and "place an order." The main difference between standalone programs and self-contained procedures that implement business tasks and web services is the way you invoke the programs. A web service is a service that's called using standard service-oriented architecture (SOA) technologies, defined as "Basic Profile" by the Web Services Interoperability Organization. You can learn more about Basic Profile on the organization's website at ws-i.org. Although HTTP is one of the most common protocols used in web service invocation (hence "web" in the name), it's not a requirement.

Web services technologies specify how to invoke a web service. The Basic Profile specification covers the following items:

transport layer: HTTP (the only transport protocol supported by the Basic Profile standard), JMS, FTP, or other transport protocols (not supported by Basic Profile)
message invocation: SOAP
web service description: Web Services Definition Language (WSDL)
web services catalog: Universal Description, Discovery, and Integration (UDDI)

Figure 1 shows how to use these technologies in a web services interaction. A developer creates a web service and deploys it in a web services server, which is often called a "SOAP server." In addition to producing a web service, the developer creates or generates WSDL — an XML file that describes the web service. WSDL contains information about the web service location, web service methods, and input/output parameters for each implemented method. The developer then sends the WDSL file to the web service client developer, who creates or generates web service invocation code based on the WSDL file. After you have completed the implementation, you can test the web service.

A web service client constructs a SOAP message. SOAP is an XML dictionary for creating a remote procedure call. A SOAP message contains a service location (usually a URL), the name of the service, and input parameters used by the service. The SOAP message is transmitted over HTTP or another transport protocol. On the server side, the web services server listens for SOAP messages. The SOAP server parses incoming SOAP messages and invokes web services. Depending on implementation, either the web service or the SOAP server creates a response SOAP message and sends it to the client.

Web Services Design

Can you make your existing standalone program or a procedure into a "web service"? Yes, if your program is stateless, self-contained, and has a well-defined parameter list. Stateless programs or procedures don't rely on global variables and don't expect any sequence of events to happen before you call a program. "Self-contained" means that for each invocation, the program has all the data it needs to be executed. People often point to stock quote lookup as a web service example because it has the described characteristics:

It's stateless. Stock quote lookup doesn't store stock quote information and doesn't depend on setting or initializing data before the current stock quote lookup is requested.
It's self-contained. All data required to execute the program is passed as parameters; no other information is required.
It has a well-described parameter list with a stock symbol as an input parameter and stock price as an output parameter.

Although each web service that's used in an application should be stateless, the application as a whole has to maintain state. State is needed to verify that a user is logged in before invoking a procedure and to keep track of the user's progress through a business task that has several steps, such as making a travel reservation or ordering items.

Figure 2 shows one approach for maintaining state in an application that uses web services. When the user logs in, you can generate a token and pass it back to the web service client. Each subsequent web service call takes the token as an input parameter and verifies that the user is logged in. The web service can also store state on the server, for example, in a data queue and look up information based on the passed token. With this implementation, the web service is still stateless, but the application maintains state.

The next design point to review is web service parameters, in particular, parameter types and parameter format. When you create a SOAP message, you convert implementation-specific data types such as java.lang.String or RPG zoned decimal to SOAP types. This process is called "serialization." Because a SOAP message is a text message, it specifies the data type as "encoding." A WDSL document details parameter types. A web service must have parameter types that are supported by SOAP, which supports most common data types used in programming languages such as string, integer, float, boolean, and so on. If you choose a data type that's not sustained by SOAP, you can still create your web service request message. The SOAP API converts input parameters to text, but the SOAP server will not interpret parameters correctly because it doesn't know how to process the unsupported data type. See Find Out More, at left, for information about supported SOAP data types.

Consider web service client requirements when deciding on parameter type and format. For example, you can pass customer information as a set of single parameters, as a data structure, or as an XML document encapsulated in a string parameter. Passing information in an XML file encapsulated as a string offers the best interoperability because string data type is supported by most programming languages and SOAP. However, if you use this approach, the web service loses its "self-describing" property. The WSDL file will show that your web service has a string parameter, but it will not describe the content of the string parameter. You need to provide an additional document to web service client developers to describe the XML schema. Another disadvantage of this approach is the additional work needed to create and parse the XML file. Other parameter types convert from SOAP format to web service programming language data types by the SOAP server or SOAP APIs on the client side.

If you don't have specific parameter format requirements from the web service client application, you can provide several web service interfaces that call a "business task" procedure with a common parameter format.

Finally, you need to decide how to deal with errors in your web service. SOAP servers and programming languages have different error-handling implementations. For example, if a Java method throws an exception, most SOAP servers will convert it to a SOAP fault. This means that the web service client needs to know how to process SOAP faults in addition to processing the SOAP message. An alternative error-handling implementation is to return error status and error messages as output parameters. Your program or procedure should handle all error messages and, if needed, return the error status and message to web service clients. With this approach, you have a consistent way of handling and communicating error messages that's not dependent on a SOAP server.

IBM Integrated Web Services Server for i

V6R1 includes Integrated Web Services Server, and you can install it with PTFs on V5R4. Integrated Web Services Server provides a runtime environment for deploying web services that are created with the IBM web administration for i5/OS wizard. The wizard provides the capability to create web services from existing RPG programs — *PGM or *SRVPGM. You need to make small changes to your programs before deploying them in the i5/OS Integrated Web Services Server. On V6R1 recompile modules,

CRTRPGMOD PGMINFO(*PCML *MODULE)
CRTCBLMOD PGMINFO(*PCML *MODULE)

On V5R4, add the following directives and recompile modules:

For RPG: H PGMINFO(*PCML:*MODULE)
For Cobol: PROCESS OPTIONS PGMINFO(PCML MODULE)

You can access IBM web administration through the browser http://systemi_hostname:2001. If you get a "Page not found" error, verify that the admin instance of HTTP server has been started on IBM i. Use the Create Web Services Server wizard to deploy your RPG programs as web services. You can deploy web services to a single server or multiple web services servers. You may need to deploy web services to different servers for server-management reasons, but keep in mind that additional web services servers will take up system resources.

The web server wizard guides you through the process of selecting an RPG program and procedures that you would like to expose as web services. Figure 3 shows the wizard page for selecting RPG procedures to expose as "operations" of a web service. In the web services implementation terminology, a "web service" refers to a program that contains multiple operations (procedures). Carefully review parameters for each procedure and specify parameter use: input, output, or input/output parameters. WSDL, a document that describes a web service, does not have a concept of an input/output parameter. WSDL describes input and output parameters separately for each web service operation.

Another important consideration is configuring multiple occurrence data structure (array) data types. For an array, you can specify a count property that points to another output parameter. If your program returns an array that's initialized with 100 records and you don't use the count variable, web services runtime will process all 100 elements, even if only 10 records contain data. If at runtime you can determine how many records are returned, you can set the count to that variable. In Figure 3, the COUNTRET variable represents the number of records. Setting the count variable will improve the web service performance because web service runtime processes only the actual number of records returned.

Note that when you step through the web services wizard, you deploy existing programs. If you need to make changes to your program, especially procedure interface changes such as add more parameters or change parameter types, do them before you start the wizard.

After you finish stepping through the wizard, the web services server deploys selected programs and procedures. As mentioned earlier, your program becomes a web service. Two web services operations are generated for each procedure. The first returns parameter types specified in your procedure, and the second returns parameters as an XML document contained in a string data type. You can test web services with the web services Test Client, a web application that lets you invoke deployed web services. After you finish, you can send the generated WSDL file to web services client developers. You can access the WSDL file for each web service through the Manage Deployed Services page of the Manage Web Services Server wizard in Figure 4.

Rational Developer for System i

A second approach for creating web services from your existing RPG programs requires developing JavaBean wrappers and exposing JavaBeans as web services. RDi SOA generates all the code required to create a web service. You can also use WebSphere Development Studio client (WDSc) for System i Version 7.0 for this implementation approach.

First, create a dynamic web project that will contain your web service. Next, create a JavaBean that invokes an RPG program with the Program Call Bean wizard, which is called by selecting File|New|iSeries|Java|Program Call Bean. You can generate several JavaBeans for each RPG program. The JavaBean that ends with "services" is the one that invokes the RPG program.

Generated Program Call Bean has two Java methods for each RPG procedure. The first returns parameter types specified in your procedure, and the second returns parameters as an XML document in a java.lang.String data type. Although you don't need to make any changes to the generated JavaBean before creating a web service from it, you can add code or change method interfaces (parameter name, types, method name).

You may want to change or extend generated JavaBeans to keep existing RPG code unchanged and implement changes required for web services in the Java layer. For example, you can add code to maintain state or perform parameter validation before invoking the RPG program.

After completing changes in the generated "services" JavaBean, you can generate a web service by stepping through the web services wizard — File|New|Other|Web services. The wizard will ask which one of the public JavaBean methods you would like to expose as web service operations (Figure 5). You can test the generated web service in the WebSphere Test Environment in RDi SOA. To deploy the web service, export your web project as an EAR file and install it in WebSphere Application Server (WAS). You can deploy the EAR file to WAS on any platform, but you can't install it in the IBM Integrated Web Services Server for i.

Just as in the first implementation approach, the last step in web services deployment is to send the WSDL file to the web services client developer. You can find the WSDL file in the WebContent directory of the web project. When selecting an implementation approach, consider the factors listed in Figure 6.

Troubleshooting Web Services Deployment

If you deployed your web services in the IBM Integrated Web Services Server for i, start debugging by looking at SOAP messages in the SOAP message monitor, which you can launch from IBM Web Administration. The next step is to check lwistdout.txt and lwistderr.txt log files, located in /qibm/userdata/os/osgi/lwisysinst/admin2/lwi/logs on V5R4 and in /qibm/userdata/os/osgi/lwisysinst/admin/lwi/logs in V6R1. You can also access these log files from the IBM Web Administration interface.

If you are developing web services in RDi SOA, the first place to troubleshoot is the IDE. You can start the TCP Tunnel tool to see request and response SOAP messages. In addition, you can step through the RPG program and the Java wrapper by running them in the debug mode. If your web service runs in the IDE but doesn't work when deployed in WAS, try the following steps:

Verify that WAS is started and configured to accept HTTP requests. One way to do this is to bring up the snoop servlet http://hostname:port/snoop.
Confirm that you have deployed the web service successfully. Display the service URL found in the <wsdlsoap> tag of the WSDL document, for example, http://localhost:9081/SampleWebService/services/GETCUSTOMERSServices. You should see a web page that says, "<Your service name> Hi there, this is an AXIS service!"
If you can invoke the web service with your test application but web services clients receive errors, check that they have the correct service URL. In some cases web service client developers forget to change the URL to the correct server name and port. Also check that HTTP requests to WAS can get through the firewall.
Check WebSphere log files to debug runtime problems on the server. Log files are located in the server profile logs directory <WAS Installation Directory>\<AppServer>\profiles\<Profile>\logs\<server>. Start by looking in SystemOut.log and SystemErr.log. You can also find useful information in the WAS ffdc logs.

Web Service Clients

Most development tools support web service client generation based on a WSDL file. IDEs generate a "web services invocation proxy" that lets the client program invoke a web service as a native program. The web service invocation proxy converts regular program calls to SOAP calls. RDi SOA and WDSc can generate different types of Java web service clients, and IBM i includes the integrated web services client product that generates web service invocation proxies for RPG and Cobol programs. You can learn more about web service client development on the Integrated Web Services Server product website (see Find Out More).

Taking the First Step

Although the two approaches for developing web services presented here have many similarities, the main differences between the methods are required developer skills and deployment options. The Java wrapper approach has been used for several years, and IBM developed the Integrated Web Services Server in response to IBM i customers' requests to be able to create web services directly from RPG. The best way to find out which development option is the right choice for your company is to prototype it.

Elena Lowery (elowery@us.ibm.com) is a technical consultant in the ISV Solutions Enablement organization in Rochester, Minnesota. She works with ISVs, helping them adopt the latest IBM and open-source technologies.