While we believe Orc is an excellent language for web service scripting, currently the library support for such tasks is at a proof-of-concept level. The web service libraries are not bundled with the core Orc distribution, do not have stable APIs, and are not officially documented. However this section should provide you with enough information to get started.

All Orc sites related to web services are bundled in a separate "OrcSites" library. As with the core Orc distribution, you can either download this library as a prepackaged JAR or check out the source code from the "OrcSites" module in version control. We generally recommend the latter approach, since the source code provides several examples which can be used as a basis for creating your own web service sites.

Within the OrcSites source code you will find:

Several of the examples require you to create .properties files and place them in your classpath. The simplest way to do this is to make sure the examples/ directory is in your classpath, and place the necessary .properties files there.

Web services use a variety of protocols, so there are a variety of ways to contact them. All of them boil down to creating a Java proxy site for the service and calling that. Previous sections explain how to implement such Java sites which can be called in Orc. Because web services tend to use blocking I/O, Java wrappers make frequent use of ThreadedSite and Kilim to ensure that web service calls don't block the Orc engine.

OrcSites includes a generic site orc.lib.net.Webservice which allows you to connect to any SOAP RPC (specifically rpc/encoded) service, without writing Java wrappers. Instead Apache Axis is used to generate Java wrappers on-demand.

http://www.xmethods.net is a good place to find examples of SOAP RPC services:

Example:

site orc.lib.net.Webservice
{-
Find documentation of this service at:
http://www.xmethods.net/ve2/WSDLRPCView.po?
key=uuid:BF3EFCDD-FCD4-8867-3AAC-068985E7CB89
-}
val service = Webservice(
  "http://www.ebob42.com/cgi-bin/"
  + "Romulan.exe/wsdl/IRoman")
service.intToRoman(451)

Many services use ad-hoc REST/XML protocols. Unfortunately, there is no REST equivalent to WSDL, so there's no way to automatically generate an API for REST services. We're not trying to solve this problem with Orc, but when the web services community reaches some kind of consensus, Orc will support it.

For now you must write a Java wrapper for each service which handles marshalling and unmarshalling the data. There's no reason such marshalling code couldn't be written in Orc, calling low-level HTTP and XML libraries directly, but there would be no advantage to doing so, so we let each language play to its strengths. OrcSites includes utility classes to assist with submitting requests and parsing responses.

OrcSites includes the following examples of this type of service: