WADL Generation
The WADL generation feature allows the generation of a WADL document from a
sample REST request uri. The uri analysis in RestDescribe.Wadl.Analyzer creates
a RestDescribe.Wadl.ApplicationNode (the root element of a WADL document) and
its child nodes. The application node is passed to the RestDescribe.Wadl.WadlXml
class, where a System.Xml.XmlDocument is generated, that can be returned as a
string.
During the generation process a sample request to the service is issued in order
to guess the result format. Based on the result a response/representation
element describing the format is added to the WADL document.
The result handling code in a workflow activity class (see below) is generated
according to the mediaType attribute of the response/representation element.
Currently application/xml and application/json are supported. For easier
integration in a workflow a json result is converted to xml.
How to generate a WADL document:
1. Start the service: use the exe in <project
root>\Service\bin\Debug\Service.exe or right click the project in Visual Studio
and select Debug - Start new instance
2. Start the client: use the exe in <project root>\Client\bin\Debug\Client.exe
or right click the project in Visual Studio and select Debug - Start new
instance
3. Select function 1
4. Enter a sample REST uri, e.g.
http://search.yahooapis.com/NewsSearchService/V1/newsSearch?appid=YahooDemo&query=madonna&results=5&language=en
5. Select the HTTP method type. (Currently GET and POST requests are supported
in the Workflow Code Generation component)
6. Enter a file name for the generated wadl document, e.g. yahoo.wadl.xml
7. An XML document containing the WADL description for the provided url is
written to the directory wadlOutput\
Workflow Activity Code Generation
The Windows Workflow Foundation is a Microsoft Framework for building workflow
applications, comparable to BPEL based workflows.
Though not being a standardized, open source driven technology as BPEL, the
Windows Workflow Foundation is extendable through custom component development. By generating special C# classes (derived from
System.Workflow.ComponentModel.Activity) a RESTful web service can be integrated
into a Windows Workflow application. The code is generated first and can be used
in the graphical designer after its compilation.
Source code generation is implemented using the System.Codedom namespace.
How to generate an Activity class:
1. Start the service: use the exe in <project
root>\Service\bin\Debug\Service.exe or right click the project in Visual Studio
and select Debug - Start new instance
2. Start the client: use the exe in <project root>\Client\bin\Debug\Client.exe
or right click the project in Visual Studio and select Debug - Start new
instance
3. Select function 2
4. Enter the path to a WADL document, e.g. wadlOutput\yahoo.wadl.xml
5. The generated C# source files are written to the directory code\
6. Add the source files to a workflow activity project (e.g. RestActivity) in
Visual Studio
A custom activity consists of two source files: e.g. CustomActivity1.cs
(containing service parameter properties and the request code) and
CustomActivity1.Designer.cs (a standard class needed by the Workflow Designer).
After successful compilation the generated activities are available in the
workflow toolbox under its project name RestActivity. The project includes two
demo workflows using three generated activities. Open Workflow1.xoml or
Workflow3.xoml for a graphical view.
 |
|
Figure 1: A sample workflow, calling ebay's item search and displaying the results based on the price of the returned items
|
The customActivity11 component of the workflow is an instance of the generated
activity class. It has so called dependency properties, providing access to the
service call parameters (in the lower right corner of the standard designer
view).
 |
|
Figure 2: Dependency properties representing the service input parameters
|
The types of the properties enable a rudimentary static type checking. Typically
strings and integer types are differentiated (depending on the type estimation
during the WADL generation), although the RestDescribe.CodeGeneration.TypeMapper
class supports Boolean and Double value types too.
The WantedElement property allows the specification of a certain XML element,
whose content is returned within an XmlNodeList in the WantedNodes property.
WantedNodesLength provides the length of this list, that can be used to iterate
over the list in a while loop for example.
The whole result document of a service call can be accessed through the static
(to accomplish
thread safety) XmlDoc property . The return type of XmlDoc is
always XmlDocument - JSON formatted results are converted to xml in the
execution method of an activity.
Using the generated custom activities, the integration of REST services in a
workflow application is quite easy from the service invocation view. Calling a
service is just a matter of dragging the generated activity into a workflow and
specifying the name of the WantedElement from the result document (see
WantedNodes). Other parameters are filled with values from the example-uri, used
for the initial WADL generation.
Result handling is not so easy and requires programming skills. The very
practical property binding feature of the designer, allowing the binding of a
result property of one activity to an input property of an other activity, lacks
the possibility to access list elements dynamically. It is not possible to
access the elements of an array (for example an array of certain result
elements) using a counter variable. A code activity within the loop (see
codeActivity in sample Workflow3) to access the XML structure programatically is
the pretty unsatisfying workaround.
Technical Notes
WSDL URLs
http://localhost:8080/RestDescribe/Service?wsdl ,
http://localhost:8080/RestDescribe/Service?wsdl=wsdl0.
Minimal debugging of the wadl generation component can be done using the
wcftestclient utility (available in a visual studio command prompt), providing
the wsdl url as command line argument.
Data length
Depending on the length of the generated WADL document / source code the return
value of a service call can exceed xml message buffer limits, causing a runtime
exception. To adjust the message buffer limits programatically a
BasicHttpBinding is instantiated (code example below) which is passed to the
endpoint constructors of service and client (RestDescribe.Client.Program,
RestDescribe.Service.Program) :
var binding = new
BasicHttpBinding(BasicHttpSecurityMode.None);
binding.MaxReceivedMessageSize = 256 * 1024;
binding.ReaderQuotas.MaxStringContentLength = 64 * 1024;