In IBM® Rational® DOORS®,
the implementation of version 2 of the OSLC Requirements Management
(RM) specification includes a service that you can use to run Rational DOORS DXL
scripts by using HTTP protocol.
Rational uses
technology based on Open Services for Lifecycle Collaboration (OSLC)
to provide integration with Rational and
non-Rational tools.
Rational DOORS supplements
the standard OSLC capabilities with an OSLC DXL service that you can
use to run
Rational DOORS DXL
scripts across HTTP. The service is based on the concept of a DXL
script library. The process to use the service is as follows:
- The user looks up the required OSLC DXL script.
- The user calls the script to package the required parameters in
the OSLC call. If you submit a GET request for the DXL service URI,
the response contains help information about the script, as supplied
by the author. If you submit a PUT request with optional parameters
for the DXL service URI, the service is invoked.
- The script is run on an interoperation server.
- The results are posted.
The scripts that are controlled and customized by the Rational DOORS administrator,
who can decide which DXL scripts are exposed across the service interface.
The administrator can lock the ability to call certain functions that
might be regarded as a potential security risk, such as "runDXL".
Certain DXL, such as user interface widgets, will never be
supported.
Because service discovery is protected by OAuth,
if you use the OSLC DXL service, you must authenticate by typing your
user name and password.
The typical steps for using the OSLC
DXL service are as follows:
- Create a DXL script.
- Install the DXL script as a service.
- Locate the service through service discovery.
- Call the service.
- Extract the return value from the response.
Example
- Create a DXL file named helloWorld.inc that
contains this code:
void getHelloString(string language)
{
string hello = null
if ("French" == language)
{
hello = "Bonjour le monde"
}
else if ("Finnish" == language)
{
hello = "Hei maailma"
}
else if ("Latin" == language)
{
hello = "Ave mundi"
}
else
{
hello = "Hello world"
}
setDxlServiceResult hello
print hello "\n"
}
- Copy the helloWorld.inc file into the /addins/services directory.
The default location of this directory is C:\Program Files
(x86)\IBM\Rational\DOORS\9.5\lib\dxl\addins\services.
- Open a Rational DOORS client
and log in as the administrator.
- To install the DXL, open a DXL window and type the following DXL
code. A service named helloWorld is created.
OSLCDXLService os = null
string err = null
string dxlCode = "#include <addins/services/helloWorld.inc>\n"
err = addOrUpdateOSLCDXLService("helloWorld", "Hello world in several languages", dxlCode, "getHelloString")
if (!null err)
{
print err
}
else
{
print "Installed Service\n"
}
- Call the service. The URI is like this example: http://servername:portnumber/dwa/rm/dxl/helloWorld
- Set both the accept and content-type headers to
this entry: application/rdf+xml
- Make sure that the request content is like this code:
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:doors="http://jazz.net/doors/xmlns/prod/jazz/doors/2.0/">
<doors:Arguments>
<doors:arguments>English</doors:arguments>
</doors:Arguments>
</rdf:RDF>
- To pass arguments to the service, use the <doors:arguments> element.
Enter a string in the element text that represents the required arguments.
The DXL service transforms that string into the arguments that are
required by the services DXL function. The earlier example shows a
single parameter, English, that is passed to
the getHelloString function. If a DXL function
expects two parameters, the request looks like this example:
<doors:Arguments>
<doors:arguments>English,French</doors:arguments>
</doors:Arguments>
The receiving DXL service splits the comma-separated list
into the separate English and French strings.
- If you have arguments that are not of the string type, you must
convert them into the appropriate type by using DXL. For example,
if an argument is an integer, you can use the intOf operation
to convert the string that was extracted from the comma-separated
list into an int type value. Then, you can pass the value into the
method.
The response content is like this code:
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:doors="http://jazz.net/doors/xmlns/prod/jazz/doors/2.0/">
<doors:DxlServiceResult rdf:about="http://my-desktop:8080/dwa/rm/dxl/helloWorld>
<doors:result>Hello world</doors:result>
</doors:DxlServiceResult>
</rdf:RDF>
The service does not perform any marshalling. Arguments are
specified in a string format, from which the DXL script extracts values
and then converts them into the expected individual parameters.