Web Service Basics

Mechanisms

Creating a WebApp Project

In the Visual DataFlex Studio, select File => New => Project => Web Project and follow the wizard's instructions.

---

Creating a Web Service Object

In the Visual DataFlex Studio, select File => New => Web Object => Web Service Object and follow the wizard's instructions.

The psDocumentation property will be automatically set to some default text, but you should replace this with a description of your own service, as this will appear in the WSDL <documentation> element describing the service. There are several other properties which it now a good idea to set:

• psServiceURI - this should be set to a unique URI; a good choice is something like "http://yourDomainName/projectName/serviceName - there is no requirement that it actually exist as a valid internet URL
• psServiceName - this will be used to name the exposed web service object (.wso) and hence will be part of the "endpoint" URL of your service, so chose it with care
• psServiceTitle - this will appear as the "display" name of the service in the human-readable HTML interface to the service

---

Defining XML Documents

Assuming that you are using Visual DataFlex's default Document Style of web service, you will generally need to define the XML documents that are passed to and from your service's operations. If these are anything other than simple data types (String, Integer, etc.) then you will need to define them as Structs. An example of such a thing would be:

Struct OrderDetail
   Integer LineNo
   String  ItemCode
   Number  Price
   Integer Quantity
End_Struct  // OrderDetail

Struct PurchaseOrder
   String  OrderNum
   String  CustomerID
   Date    OrderDate
   Number  OrderTotal
   OrderDetail[] Details
   String  PayMethod
End_Struct  // PurchaseOrder

Struct OrderResponse
   Boolean Accepted
   String  RejectReason
   Integer OrderNum
   String  Reference
   Date    DeliveryDate
End_Struct  // OrderResponse

---

Defining Web Service Operations

These documents are then used in web service methods (Functions or Procedures) like this:

Function GoodsOrder PurchaseOrder Ord Returns OrderResponse
  OrderResponse Resp

  Get ProcessOrder Ord to Resp.Accepted

  If Not Resp.Accepted Get psOrderError to Resp.RejectReason
  Else Begin
     Get piOrdNum   to Resp.OrderNum
     Get psRef      to Resp.Reference
     Get pdDelivery to Resp.DeliveryDate
  End

  Function_Return Resp
End_Function  // GoodsOrder

(Here it is assumed that there is also defined a Function ProcessOrder, which does all of the hard work, taking the PurchaseOrder data and returning a boolean result - and setting various properties as it does so.)

---

Publishing an Operation

In the Code Explorer pane of the Visual DataFlex Studio, right-click on the method (Function or Procedure) and select "Published" from the context menu. This will cause (a) the "Published" context-menu item to subsequently appear "checked", (b) a globe to appear next to the method's icon in Code Explorer and (c) the two lines:

{ Published = True  }
{ Description = ""  }
Function GoodsOrder PurchaseOrder Ord Returns OrderResponse

to appear above the method declaration line. The Description should then be filled-in with something meaningful, as this will form the <documentation> element in the WSDL describing the method (operation in web service terminology). If you later chose to "unpublish" the method (uncheck "Published" on the context menu), the "True" will change to "False", however you could also just delete the two lines in braces, at the cost of losing anything you had written into the "Description" there.

---

Creating a Web Service Client

In order to create a Visual DataFlex web service client you must have access to the service's WSDL in some form. This might be directly from the service itself - in Microsoft .Net or Visual DataFlex services this is the service's URL with "WSDL" appended as a query string: something like http://server/someService/service.wso?WSDL - or it might be an XML file provided by the service's developer or publisher which you have saved to a locally acessible file: C:\Services\Docs\someServiceWSDL.xml - or it might be an XML/WSDL file statically published on a web site: http://server/services/wsdl/someService.xml.

In the Visual DataFlex Studio, select File => New => Class => Client Web Service Class. This will run the Web Service Client Class Generator. Into its "WSDL URL" window paste (or type) the location (of whatever type) of the service's WSDL, then click the "Parse" button. If this succeeds, then the "Generate Class" button will become available and can be clicked to create the client. You should generally accept the default name and group.

Using a Web Service Client Class

The class created above will (by default) then appear within the Visual DataFlex Studio on the Class Palette pane under the "Web Services" group. From there it can be dragged and dropped onto a visual component (a View or whatever) in the Studio's "Designer", creating an object of that class within the component.

If you are working on a component that cannot be modelled in the Designer (either because it is a non-visual component like a Business Process or for some other reason) then you can still do the same thing: just drag the class onto the blank Designer page - it will be saying "No Objects to Model".

Or you can do it manually:

Use cWSServiceName.pkg

Object oCallItWhatYouWant is a cWSServiceName
End_Object  // oCallItWhatYouWant

This object - which we can think of as a "stub" or "proxy" for the web service itself - can then have its methods (which will map onto the operations of the service) invoked, passing them the appropriate data, to invoke the service itself, and receive any returned data from it.