Web service design elements
Table of contents
In today's environment of the soaring popularity, availability, and functionality of Web Services, it is important to consider whether you can or should make part of your application available as a web service, or, make use of an existing public Web service.
The ability to easily create a Web service was added in Domino Release 7. Included as part of Domino designer, creating a Web service involves the following basic steps:
- Create the Web service and set its properties
- Code the Web service
- Export and create a WSDL if you want to make it public
Your Web service is a set of Java or LotusScript classes. In the case of LotusScript, you must use that approach and create your classes in the Declarations section.
To begin, create the Web service by clicking the New Web Service button in the Web Services pane as shown in the following figure.
Next, you can set the Web Service properties and then code the Web service, as shown in the following figure.
While coding your Web service, you can also use the following actions:
- Import WSDL: If you started by creating a WSDL file from scratch, or have a WSDL file for which the entire Web service needs to be created, you can use the import function to create your code stubs.
- Export WSDL: After you create your Web service, you can use this action to export the WSDL file and subsequently publish it.
- Show WSDL: Shows the current WSDL for the service while you are developing it.
The following table lists additional properties that you should be aware.
Warn if the WSDL interface is modified
Use this! This tells the developer when a change made to the service will affect the WSDL file. After you make the Web Service publicly available, then you should not change the WSDL.
This is the name of your Web service's class file. The service can be written as a Java or LotusScript class.
Run as web user/Run on behalf of
Equivalent to the same settings for agents.
Set runtime security level
Equivalent to the same setting for agents.
Allow Public Access users to use this web service
Equivalent to the same setting for agents.
Include operation name in SOAP action
sets the soapAction="OperationName" setting in the WSDL
Port type name
Sets the "name" attribute for tag in the WSDL file when it is exported. This defaults to the name of the PortTypeClass specified on the Basics tab.
Service element name
Sets the "name" attribute of tag in the WSDL file when it is exported. This defaults to the name of the PortTypeClass on the basics tab followed by "Service".
Service port name
Sets the "name" attribute of tag in the WSDL file when it is exported. This defaults to "Domino".
After you code your Web service, you access it by using the following syntax, which is similar to all Domino Web URLs:
Be aware that if you send the URL command for opening a Web service to a Domino server in an HTTP GET request (for example, by typing the command in a browser), Domino responds with the Web service's port name and the names of the operations/methods for the port. To invoke and run the Web service, an HTTP POST must be used.
To look at the WSDL, use the syntax shown in the following example:
In both cases, the Web service name is the Domino design element name (or alias) of the Web service.
Domino does not easily lend itself to consuming an external Web service. Domino Designer currently has no such tools to facilitate the the import of an external WSDL file and the code generation of its supporting functions.
However, there are two alternative suggestions, Stubby and Apache Axis.
Stubby is an open source application that comes in the form of an NSF file. Based on Apache Axis, it is essentially a UI tool that takes as input the URL location of a WSDL file, or a WSDL file thats on your current file system, and does the following tasks:
- Stubby generate all the .java files, .class files, and a .jar file or files suitable for use and import into your notes application. You either must import the JAR file itself, or the Java files into Domino Designer (and therefore compile them) into an agent or library if you want to keep the source as a reference.
- Stubby provides a code stub for an agent that shows you how to instantiate and call the target Web service.
Some of the advantages of using Stubby is that no modifications to the client or server are needed, and there are no external library dependencies.
Stubby (as any piece of software) has been known to have some limitations. For example, its SAX parser of the Web service objects being passed back and forth could be more robust than it is. The best recommendation is to try it and see if it fills your requirements and works for you.
Another alternative is to use Apache Axis. Apache Axis is essentially a downloadable package that contains Jar files and tools for generating all the files needed to call and use the target Web service. Like Stubby, the included tools take as input the physical local file location of the WSDL file of the target Web service. After you install or extract Axis, you can use a .bat file to produce your Java stubs. The batch file has to be changed to reflect the directories on your machine, and you need a Java SDK to be present.
- Apache Axis generates only the .java files, and a .jar file or files that are suitable for use and import into your notes application; However, it does not generate the compiled class files. Like Stubby, you will either need to import the jar file itself, or the Java files into Domino Designer (and therefore compile them) into an agent or library if you want to keep the source as a reference.
- Apache Axis does not provide you with a code stub to call the service from Domino.
As it turns out, the strengths and weaknesses of Stubby and Apache Axis are the opposite of each other.
One of the disadvantages of using Apache Axis is that the Jar files included in the package are external library dependencies. The Axis Jar files that were extracted onto your machine must go into a specific notes directory for external JAR files. Also, the java.policy file must exist on the Domino server (or Notes client if this is called from a Notes client) JVM and allow the proper security.
One of the advantages of using Apache Axis is that the SAX parser is more robust and can handle complex objects. There is a great writeup on using Apache Axis that is available on IBM developerWorks®.