Application programming interface to the simple object access protocol

Methods and systems for providing an application programming interface (API) to the Simple Object Access Protocol (SOAP) are described. The API provides mechanisms for creating all parts of SOAP request messages, for sending the created messages over HTTP to a remote server, and, if the request is successful, for retrieving the response from the remote server, or, in the case of failure, for accessing whatever error information is available. The information passed through the API can be in the form of parameters which allows both the SOAP protocol and the applications that use it to change without requiring changes to the API itself.

TECHNICAL FIELD

This invention relates generally to computer operating system services, and, more particularly, to an application programming interface to the Simple Object Access Protocol.

BACKGROUND OF THE INVENTION

SOAP (“Simple Object Access Protocol”) is a standard method for a client application running on one computer to request services from a server application running on another computer. SOAP encodes remote procedure calls into XML messages that are carried to the server by an HTTP transport protocol. By standardizing the protocol for this much-used service, SOAP eliminates protocol development redundancy and application-specific protocol variations. SOAP has been proposed to the Internet Engineering Task Force for consideration as an Internet communications standard. The proposal may be found at http://search.ietf.org/internet-drafts/draft-box-http-soap-01.txt.

However, the proposed SOAP standard does not specify an application programming interface (API) to allow applications to easily use SOAP. Each applications development group must individually code the interactions between its application and the SOAP protocol leading to resource waste through coding replication and possibly to interoperability errors when connecting applications written by different development groups. Therefore, the lack of a standard SOAP API directly counters some of the benefits hoped to be achieved by using SOAP.

SUMMARY OF THE INVENTION

The above problems and shortcomings, and others, are addressed by the present invention, which can be understood by referring to the specification, drawings, and claims. The invention provides a general API for SOAP-using client applications. The API provides mechanisms for creating all parts of SOAP request messages, for sending the created messages over HTTP to a remote server, and, if the request is successful, for retrieving the response from the remote server, or, in the case of failure, for accessing whatever error information is available. Applications developers building on top of this API are freed from redeveloping these general mechanisms and can thus focus on the unique aspects of their applications.

In one embodiment of the present invention, the API consists of software objects. In addition to providing the well-known benefits of an object-oriented interface, this embodiment parameterizes the information passed through the API. Because of this, both the SOAP protocol and the applications that use it can change without requiring changes to the API.

Besides the aspects, features, and advantages described, the invention includes other aspects, features, and advantages that will become apparent from studying the following detailed description and claims.

DETAILED DESCRIPTION OF THE INVENTION

Overview of a General-Purpose Computer

With reference toFIG. 1, an exemplary system for implementing the invention includes a general-purpose computing device in the form of a conventional personal computer20, including a processing unit21, a system memory22, and a system bus23that couples various system components, including the system memory, to the processing unit21. The system bus23may be any of several types of bus structures including a memory bus or memory controller, a peripheral bus, and a local bus using any of a variety of bus architectures. The system memory includes read only memory (ROM)24and random access memory (RAM)25. A basic input/output system (BIOS)26, containing the basic routines that help to transfer information between elements within the personal computer20, such as during start-up, is stored in ROM24. The personal computer20further includes a hard disk drive27for reading from and writing to a hard disk60, a magnetic disk drive28for reading from or writing to a removable magnetic disk29, and an optical disk drive30for reading from or writing to a removable optical disk31such as a CD ROM or other optical medium.

The hard disk drive27, magnetic disk drive28, and optical disk drive30are connected to the system bus23by a hard disk drive interface32, a magnetic disk drive interface33, and an optical disk drive interface34, respectively. The drives and their associated computer-readable media provide nonvolatile storage of computer-readable instructions, data structures, program modules, and other data for the personal computer20. Although the exemplary environment described herein employs a hard disk60, a removable magnetic disk29, and a removable optical disk31, it will be appreciated by those skilled in the art that other types of computer-readable media which can store data accessible by a computer, such as magnetic cassettes, flash memory cards, digital video disks, Bernoulli cartridges, random access memories, read only memories, and the like, may also be used in the exemplary operating environment.

A number of program modules may be stored on the hard disk60, magnetic disk29, optical disk31, ROM24, or RAM25, including an operating system35, one or more applications programs36, other program modules37, and program data38. Often, the operating system35offers services to applications programs36by way of one or more APIs (not shown). Because the operating system35incorporates these services, developers of applications programs36need not redevelop code to use the services. Examples of APIs provided by operating systems such as Microsoft's “WINDOWS” are well-known in the art.

A user may enter commands and information into the personal computer20through input devices such as a keyboard40and a pointing device42. Other input devices (not shown) may include a microphone, joystick, game pad, satellite dish, scanner, and the like. These and other input devices are often connected to the processing unit21through a serial port interface46that is coupled to the system bus, but may be connected by other interfaces, such as a parallel port, game port, or a Universal Serial Bus (USB). A monitor47or other type of display device is also connected to the system bus23via an interface, such as a video adapter48. In addition to the monitor, personal computers typically include other peripheral output devices (not shown), such as speakers and printers.

An Application's Use of an Object-Oriented SOAP API

In accordance with one aspect of the present invention,FIG. 2shows the steps an application may go through when using an object-oriented SOAP API. The client-side application36, shown running on a general-purpose computer20, needs a service provided by the server application200. To request the service, the client-side application first creates a SOAP Request Object in step202. This object conveniently presents to the client-side application all the information it needs with respect to this one SOAP request.

In steps204-208, the client-side application36opens the SOAP Request Object and writes into it the information needed to create the request message. This information includes the address of the server that will process the request and the request itself According to one aspect of the invention, this information (and the response and status information described below) is passed via parameters: this allows both the client-side application and the SOAP protocol itself to change without requiring changes to the API. When all the information has been presented, the client-side application in step210tells the SOAP Request Object to format and send the request. The SOAP Request message212is sent via the HTTP protocol to the remote server49, shown here connected to the client-side application's host by a LAN51. The connection between these two machines may be much more elaborate, involving dial-up modems, the Internet, and the like. The SOAP Request message is passed along to the server application200. Ideally, the server application responds favorably to the request, performs the requested service, and sends back a SOAP Response message214.

The SOAP API provides one place for retrieving all status and response information relevant to this one SOAP request. In step216, the client-side application36queries the SOAP Request Object. If the request was successfully processed, this Object includes an indication of success along with whatever information the server application200passed along. Errors can occur anywhere in the communications system, from the client-side application's mistaken use of the SOAP API, to lack of resources (such as memory) on the client-side application's host machine20, to congestion on the communications link51, to unavailability of the remote server49. Because of this, in the case of an error the SOAP Request Object includes not just a failure indication but as much error-resolution information as can be reasonably gathered.

In order to prevent the client-side application36from having to constantly poll the SOAP Request Object for response and status information, the client-side application may be suspended in step210when the SOAP request is sent. The client-side application is then reanimated when there is new response or status information for it to process.

A Detailed Usage Guide to an Object-Oriented SOAP API

The steps202-210, and216ofFIG. 2are now described in more detail. A COM-based embodiment of the present invention may be built around an object class called SOAPRequest which exports the interface ISOAPRequest. In the following, coding examples are given in JScript.

Step202Create a SOAP Request Object

A SOAP Request Object can be created using COM's standard object creation techniques. The following code creates the object, referring to the SOAPRequest class by the ProgID “SOAPAPI.SOAPRequest.”

A SOAP Request Object is initialized with information about the remote service being requested. The client-side application36provides the name of the procedure that will perform the remote service and, optionally, the name of the interface to which the procedure belongs. The following code passes the name of the interface as a URI (Universal Resource Identifier); this is optional and the interpretation of its value is left up to the remote server49. The procedure name is simply a text string; here it is “loadFile”.

//Initialize the SOAPRequest ObjectsoapRequest.Open(“LoadFile”, “IMediaPlayer”, “uuid:47edc63b-4a80-494a-beea-39122c4a120c”);
Step206Initialize the Headers of the SOAP Request Object

A client-side application36may wish to pass information to the remote server application200in addition to the information that is strictly part of the request for service. SOAP provides headers for this purpose, each header providing one piece of information for the server application. These headers and their attributes, including their number, names, and values, are not part of the SOAP specification but are defined by the client-side application. One embodiment of the invention parameterizes all of this information, thus allowing the information to change without requiring changes to the API. The information passing through the API in steps208and216is parameterized for similar reasons.

Each SOAP header is an arbitrary XML fragment containing a single root element. The root element may contain child elements or text. This is an example of a SOAP header called sequenceNumber:

Client-side applications36create header elements using XML DOM and then add them to a SOAP Request Object by calling the SetHeader( ) method. For more information on XML DOM, see Microsoft's XML Developer's Guide, incorporated herein in its entirety by reference. The following three code segments show the creation and setting of a header. First, create a new XML DOM Document Object that will be used in creating the subsequent XML Nodes to represent each header:

//Create the Text for the sequenceNumber and Attach Itvar sequenceNumberTextNode;sequenceNumberTextNode=xmlDoc.createTextNode(“5”);sequenceNumberNode.appendChild(sequenceNumberTextNode);
Once the header element is created, it is added to the SOAP Request Object by calling SetHeader( ). SetHeader( ) may also be used to change the value of an existing header.

Because headers are defined by the client-side application36and not by the SOAP specification, it is quite possible that the remote server application200will receive a header that it does not understand. According to the SOAP specification, a header contains a mustUnderstand attribute. If this attribute is set to1, then the server application cannot process the request unless it understands this header. SetHeader( )'s third argument is the value of mustUnderstand.

An application can delete a header element by calling DeleteHeader( ) and can read the value of a parameter by querying the HeaderValue property.

Step208Initialize the Parameters of the SOAP Request Object

Requests can take any number of parameters of arbitraily complex data types. Like the header elements described in the previous section, parameter values are expressed as XML fragments. Each parameter element consists of a root element that may contain either child elements or text. This XML fragment shows how a parameter named fileName is specified in a SOAP request:

An application uses the XML DOM to create a parameter element such as the one shown above, and then calls SetParameter( ) to add it to the SOAP Request Object. SetParameter( ) can also be used to change the value of an existing parameter. The following code creates a parameter element and inserts it into a SOAP Request Object:

//Add the File Name as a ParametersoapRequest.SetParameter(“fileName”, fileNameNode);
An application can delete a parameter element by calling DeleteParameter( ) and can read the value of a parameter by querying the ParameterValue property.
Step210Send the SOAP Request to the Remote Server

Once the headers and parameters are initialized, the client-side application36calls the Execute( ) method to send the SOAP request to the remote server49. The client-side application is suspended until the remote server sends a response, an error occurs, or thirty seconds pass without either of the above happening. In the case of a timeout, the client application resumes and Execute( ) returns a timeout error. In the other cases, Execute( ) returns and response and status information is available in the SOAP Request Object. The next section describes the information that may be returned. The following code sends a SOAP request to a server whose address is expressed as a URL (Uniform Resource Locator).

//Execute the SOAP Request

Step216Determine the Result of the SOAP Request

When the Execute( ) method returns, it passes a success or failure code to the client-side application36. That application may then query various ISOAPRequest properties to read the values returned from the server application200(in the case of a successful request) and to access status information.

If Execute( ) returns a success code, then the ResponseElement property contains the contents of the Body element of the XML response sent by the server application200. The contents of this property are server-dependent and the client-side application36should know in advance what to expect. If the SOAP request defines any out parameters (parameters whose values might be changed by the server application), then the client-side application may query their new values by using the ParameterValue property. The ResponseHeaders property returns the contents of the headers sent by the server application200. Just as a client-side application36can send additional information about a request in the SOAP headers, the server application can return additional information in the headers.

When the request fails at the server application200, the ResponseFaultCode, ResponseFaultString, and ResponseFaultDetail properties are filled from the contents of the server application's error response.

The status of the network protocol is available in the ResponseHTTPStatus (HTTP status code) and ResponseHTTPStatusText (text description of the HTTP status code) properties. The values of these properties are, however, only interesting if there was a network-related failure.

A Detailed Definition of an Object-Oriented SOAP API

In accordance with one aspect of the present invention, the following is a complete definition of the object-oriented SOAP API used to illustrate the examples given above.

CONCLUSION

In view of the many possible embodiments to which the principles of this invention may be applied, it should be recognized that the embodiments described herein with respect to the drawing figures are meant to be illustative only and should not be taken as limiting the scope of invention. Therefore, the invention as described herein contemplates all such embodiments as may come within the scope of the following claims and equivalents thereof