Web Service Basics: Difference between revisions
m added to basics |
Added procedure for adding WS client to non-visual component or adding manually |
||
Line 81: | Line 81: | ||
====Using a Web Service Client Class==== | ====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. | 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. | 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. | ||
[[Category:Web Services]] [[Category:Basics]] | [[Category:Web Services]] [[Category:Basics]] |
Latest revision as of 17:48, 23 November 2007
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.