Creating a Web Service

Using the Web Service Wizard

The Web Service Wizard generates a simple stub.

1. Click File > New.

   This displays the New dialog box.

2. Click the General tab.

3. Click New Web Service and then click OK.

   This displays a wizard.

4. Enter values for the package name, class name, and web service name. These are required.

5. Optionally edit the namespace URI (or change this initial value later). This is the XML namespace, not the InterSystems IRIS namespace.

6. Optionally type a list of method names, on separate lines.

7. Click OK.

Now, you have a new web service class that contains stubs for the web methods. For example:

/// MyApp.StockService
Class MyApp.StockService Extends %SOAP.WebService 
{

/// Name of the WebService.
Parameter SERVICENAME = "StockService";

/// TODO: change this to actual SOAP namespace.
/// SOAP Namespace for the WebService
Parameter NAMESPACE = "https://tempuri.org";

/// Namespaces of referenced classes will be used in the WSDL.
Parameter USECLASSNAMESPACES = 1;

/// TODO: add arguments and implementation.
/// Forecast
Method Forecast() As %String [ WebMethod ]
{
   ;Quit "Forecast"
}

}

Using the SOAP Wizard with an Existing WSDL

In some cases, the WSDL has been designed already and it is necessary to create a web service that matches the WSDL; this is known as WSDL-first development. In InterSystems IRIS, there are three steps to this development:

1. Use the SOAP Wizard to read the WSDL and to generate the web service and all supporting classes.

   This wizard can also generate web client classes (which is more common).

   For information on using this wizard, see Using the SOAP Wizard. Follow the steps described in that section and also select the Create Web Service option within the wizard.

   Or use the %SOAP.WSDL.ReaderOpens in a new tab class as described in Using the %SOAP.WSDL.Reader Class.

2. Examine the generated classes to see if you need to change any %StringOpens in a new tab values in the method signatures.

   When the wizard reads a WSDL, it assumes that any string-type input or output can be represented in InterSystems IRIS as %StringOpens in a new tab, which is not always true. In rare cases, some strings might exceed the maximum length string limit.

   See Adjusting the Generated Classes for Extremely Long Strings.

3. Edit the methods in the generated web service so that they perform the desired actions.

   Each method is initially a stub like the following example:

   Method Add(a As Test.ns2.ComplexNumber, b As Test.ns2.ComplexNumber) As Test.ns2.ComplexNumber 
   [ Final, SoapAction = "https://www.mynamespace.org/GSOAP.AddComplexWS.Add", 
   SoapBindingStyle = document, SoapBodyUse = literal, WebMethod ]
   {
    // Web Service Method Implementation Goes Here.
   }

   

   The wizard includes compiler keywords such as Final and SoapBindingStyle. You should not change the values of these keywords.

If the WSDL includes WS-Policy elements, the wizard also generates a configuration class for the web service. The default configuration class name is the web service name, with Config appended to it. For information on WS-Policy, see Securing Web Services.

Subclassing an Existing InterSystems IRIS Web Service

You can create a web service by creating a subclass of an existing InterSystems IRIS web service class and then adding the SOAPMETHODINHERITANCE parameter to your class as follows:

PARAMETER SOAPMETHODINHERITANCE = 1;

The default for this parameter is 0. If this parameter is 0, your class does not inherit the web methods as web methods. That is, the methods are available as ordinary methods but cannot be accessed as web methods within the web service defined by the subclass.

If you set this parameter to 1, then your class can use web methods defined in any superclasses that are web services.