Web Services Example - Introduction
From BIRT Exchange
The IDAPI is a robust, powerful API. However, this power can make the IDAPI a bit daunting for new users. This section provides some pointers to get you started by focusing on the basics and avoiding the complex bits until later.
Contents |
IDAPI Overview
The IDAPI is a SOAP-based web services API. Each operation is performed by sending a SOAP request to the server which returns a SOAP response. The IDAPI is stateless, meaning that iServer Express keeps no state information about login sessions. Instead, each message contains everything needed for that one operation.
The first step when using the IDAPI is to read Programming With Actuate iServer APIs. This is a large book, but the following are essential to get started. Our advice is to skim each section on a first read so you are familiar with what's available, then go back and read selected sections in greater detail when you're ready to work with a particular area.
- Chapter 1, "Understanding the Actuate Information Delivery API" — provides a good overview of the types of operations that the IDAPI provides. Read the first section, then skim the others to get a sense of the operations available.
- Chapter 2, "Understanding the Information Delivery API schema" — worth a read if you are new to SOAP-based APIs. The "Accessing the Actuate schema using a web browser" subsection is key for learning how to obtain WSDL for the IDAPI.
- Chapter 3, "Constructing a SOAP message" — provides more of an overview of SOAP messaging. You can skip this on first reading as Apache Axis (discussed below) does most of this work for you.
- Chapter 4, "Running, printing, and viewing a document" — gives a good overview of how to use the IDAPI to work with reports. Read this if your application will use these operations.
- Chapter 5, "Administering an Encyclopedia volume" — explains operations related to users, groups, roles, file, folders and the like.
- Chapter 8, "Actuate Information Delivery API operations summary" — summarizes the available operations. Read this to identify the messages needed for your particular application.
The other chapters provide detailed reference information. For the IDAPI as a whole:
- Chapter 9, "Actuate Information Delivery API operations" — is a detailed reference of each operation (message).
- Chapter 10, "Actuate Information Delivery API data types" — is a detailed reference of each data type used within the above operations.
Often, the following technique works well for building a client. Work message-by-message. For each:
- Check Chapter 8, "Actuate Information Delivery API operations summary" to identify the message you need.
- Find the message in Chapter 9, "Actuate Information Delivery API operations". Read the message description and description of each parameter (request element). Skip the WSDL details.
- If using Eclipse, use the auto-complete feature to learn the method names and the data types that a method expects.
- Refer to the detailed WSDL, and Chapter 10, "Actuate Information Delivery API data types" if you get stuck.
- Use [foo Apache TCPMon] to see the actual IDAPI messages that are sent and responses returned by iServer Express.
WSDL
The IDAPI messages are described using WSDL (Web Services Description Language.) Although a very simple application might directly generate the message XML, it is far more convenient to use the WSDL to generate client wrapper code. This article discusses such a client for Java, but other clients are available for other programming languages.
The WSDL for the IDAPI is available directly from iServer Express as the following URL:
This assumes that iServer Express is installed on the local machine using the default port assignment. Change the URL to match your actual install.
This URL displays a page with table that lists Actuate versions across the top and the various Actuate web services APIs down the page. The WSDL you need is in the cell for "IDAPI" and the latest Actuate version (which, at the time of this writing, is Actuate 9.) Each cell provides a link to the WSDL appropriate for various client applications.
For Java users, choose the "Apache Axis" link. This displays a list of IDAPI messages like this:
all Login GetFileACL GetChannelACL ...
Click on a message to see the WSDL for that message. The "all" link retrieves the WSDL for all messages, which results in a huge XML file. For browsing, select a single operation of interest. (Unfortunately, the operations are not sorted alphabetically, so you need to hunt around to find the one of interest.)
Refer to Programming With Actuate iServer APIs, Chapter 2, "Understanding the Information Delivery API schema" → "Accessing the Actuate schema using a web browser" for additional details.
Schema Versions
The IDAPI is versioned: each major Actuate iServer Express version introduces a new schema version number. At the time of this writing, version 9 is current, and version 10 is planned. The Enterprise version of iServer introduced the IDAPI in version 6, and so you will see versions 6, 7, and 8 all listed on the WSDL page described above. iServer Express became available with version 9, and so provides only the version 9 schema.
Each new version is designed to be as compatible as possible with the prior version. Often, new versions introduce new messages or data types for new features, though occasionally old messages or data types may be deprecated. The versions ensure that old clients (that is, clients using older versions) will work with newer versions of iServer Express. As a result, you need update your client application only when you need to use new features.
Service URL
All IDAPI messages are sent to an HTTP port on iServer Express. By default, that port is:
http://localhost:8000
with the usual caveats about changing the host and port names to match your install.
Message names appear directly in the URL:
http://localhost:8000/Login
The bulk of the message is sent using an HTTP POST operation. See Programming With Actuate iServer APIs, Chapter 2, "Constructing a SOAP message" for details.
IDAPI Clients
A great feature of a SOAP-based API such as the IDAPI is that it can be used by any programming environment. The iServer product line is used in a wide variety of applications that use a large number of languages. IDAPI applications have been written in C#, C++, and other languages in addition to Java. A web services interface is ideal in such an environment: XML is as usable in Visual Basic as it is in Java. Because of the wide variety of client platforms, Actuate designed the IDAPI to require no Actuate-provided client code.
A web service message is just XML, and one could certainly work with the raw XML. Doing so is handy for debugging or for creating very quick and simple scripts, but is impractical for larger applications. Fortunately, the web services standard makes it possible to create client tooling: programs that generate client applications in some target language. Tools exist for C#, C++, Java and many other platforms. The tools typically convert the WSDL message structure into a series of classes; and provide a library to send and receive messages, serialize and deserialize the client data structures, and so on.
Apache Axis
Apache Axis is a popular open-source tool for Java, and we focus our attention on using the client that Axis generates for the IDAPI. The advantage of Axis is that it can generate Java bindings for a wide array of web services.
The disadvantage is that Axis knows nothing about the semantics of the web service, and so the classes it generates tend to be quite low-level. Indeed, for the IDAPI, there is one class per message, per response, per data structure and per enumeration. The result is that using the Axis client directly is a bit like programming in assembler: you can do anything you want, but you have to think at two levels simultaneously: the semantic level of the service and the mechanical level of gluing together the various low-level data structures in order to perform a semantic task.
The Server Integration Technology Web Services example code shows how to code against the Axis client directly. One glance at these examples shows the volume of code needed to assemble all the bits and pieces that Axis generated into an iServer operation. We also quickly discover that we are writing the same boilerplate code over and over.
Axis Client Wrapper
Because of this complexity, a discussion the IDAPI with the Axis client inevitably ends up being about how to perform the low-level tasks, and less about what the IDAPI can do for your application. Since this article seeks to raise the discussion to the semantic level, we need a way to abstract away the low-level details. The result is a wrapper library that handles the Axis details, leaving us free to focus on application operations.
The result is that you have a choice about how to implement your application: you can use the "classic" approach of working with the Axis classes directly, or you can use the "wrapper" approach by starting with the client wrapper that this article provides. Even if you choose to go with the straight-Axis, the client wrapper shows how to do much of the Axis plumbing. And, this article will help you think at the level of server operations rather than Axis data structures. The bulk of this discussion covers the client wrapper, but the product documentation covers the original Axis client that comes with the Server Integration Technology download.
Background
As explained in the previous section, the goal of the client wrapper library is to encapsulate the low-level Axis plumbing so that we can focus on higher-level semantics. Additional goals include:
- Manage the log in session including the authentication id.
- Fill in default arguments for each message so that each message is ready to send.
- Provide constants for special values.
- Provide an iterator mechanism for the cursor-based "select" messages.
- Manage the details of uploading and downloading files.
- Keep each class a manageable size: no single central class with all operations.
- Provide full access to the IDAPI messages and responses while also accomplishing the above goals.
- Suitable for use in real-world applications.
- Easy to extend with new operations.
Documentation
Later sections discusses how to perform typical operations using the light-weight client, followed by a discussion of running reports. The code also contains full Javadoc comments with usage details. And, of course, the source is available to answer additional questions.
Some Assembly Required
The light-weight client wrapper is light-weight in another sense as well: it includes the most common operations, but does not wrap the entire IDAPI. Operations focus on users, files and jobs, which tend to be the objects that most applications use. If your application requires objects or operations not in the framework, the easiest solution is to add the required operations using the existing code as a template. For example, it is easy to add Channel support by taking User support as an example.
This client wrapper is unofficial, meaning that it is built and maintained by the BIRT Exchange community rather than by Actuate Engineering. You are encouraged to modify and extend this code. If you do make enhancements, please consider posting your code in DevShare so that others can use it as well, and we can fold your additions into a future version of the client.
Error Codes
The IDAPI messages return very detailed error codes if something goes wrong. The number code error ranges are described in "Configuring Actuate iServer" → Chapter 8, "Using Diagnostic, usage, and error logging" (unfortunately, this manual is not yet posted on in the [Documentation] page.)
A detailed list of error codes and descriptions can be found in:
AC_HOME/iServer/servletcontainer/iportal/WEB-INF/ErrorMessages.txt
Debugging Hints
Even when using a generated client application, it sometimes helps to see the actual messages exchanged between your client and iServer Express. Apache TCPMon does just that.
- Programming With Actuate iServer APIs → Chapter 6, "Developing Actuate Information Delivery API applications using Java" → "Developing Actuate Information Delivery API applications" → "Capturing SOAP messages using Axis TCPMonitor" — explains how to use TCPMon. (Note, the manual uses the name "TCPMonitor" which is the old name for this tool.)
- Apache TCPMon project site — provides the software download and instructions.
Next Step
With that background out of the way, let's get the client set up on your machine.