Introduction#

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.

Casual users should visit the Try Orc page, where you can find a number of interactive demos of Web service scripting. Feel free to modify the demos and create your own scripts (which you may share with others via the WikiLab).

Eventually you may need to go beyond the demos, interfacing to new Web services or using the existing services in more sophisticated ways. The remainder of this document addresses that need.

Protocols Supported#

Web services use a variety of protocols, so there are a variety of ways to contact them. Most boil down to creating some kind of Java wrapper for the service and calling that. Refer to the Orc User Guide's Using Java Classes section for more information on how Java integrates with Orc.

Java APIs#

Some Web services provide Java APIs specifically for the service. For example, Google Calendar. In these cases we just use the Java API from Orc, either directly or via a small Java wrapper which simplifies the interface. For example: orc.lib.net.GoogleCalendar

REST#

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 we 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. We provide some libraries to assist with, for example, converting JSON into an Orc object structure. Examples:

SOAP RPC#

We have a generic site which allows you to connect to SOAP RPC (specifically rpc/encoded) services, without writing any Java wrappers (we use libraries like Apache Axis to generate Java wrappers on-demand): orc.lib.net.Webservice

A good place to find examples is http://www.xmethods.net. How to use a service from xmethods.net in Orc:

  1. Find the RPC "Style" service which does what you want.
  2. Click on the name of the service.
  3. Click on "View RPC Profile" for a summary of the methods available.
  4. Construct instances of the service by passing the WSDL URL to the Webservice site.
  5. Call the methods as you would with any Java object. The JAX-RPC specification has complete details on how SOAP operations and data types are represented in Java, which may sometimes introduce surprises. For example, method names always begin with a lower-case letter, even if the corresponding operation does not.

Example:

include "net.inc"
{-
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)

Downloading and Running Examples#

As with the core Orc distribution, you can either download a prepackaged JAR, or check out the code in Eclipse. In the case of Web services, we generally recommend the latter approach, since many of the services are poorly documented and it may help to view their source code.

Some 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.

Prepackaged JAR#

  1. Download the orc-*.*.*.zip and orc-sites-*.*.*.zip from Google Code.
  2. Unzip both downloads: this will create two new directories which contain the necessary JARs and some examples.
  3. To run examples, your classpath must include the core orc jar, the orc-sites jar, and their respective lib directories. E.g.: java -cp orc-2.0.0/orc-2.0.0.jar:orc-2.0.0/lib/\*:orc-sites-2.0.0/orc-sites-2.0.0.jar:orc-sites-2.0.0/lib/\* orc.Orc orc-sites-2.0.0/examples/google.orc

Source code from SVN#

The Web service examples are kept in a separate SVN module to avoid bloating the core Orc distribution. Follow the Developer's Quick Start twice: first follow the directions as written to check out OrcScala, and the second time check out the project name "OrcSites" instead (OrcSites depends on OrcScala).

  • Java code for examples: OrcSites/src/orc/lib/net
  • Orc include files for examples: OrcSites/src/orc/inc/net.inc
  • Orc examples: OrcSites/examples

To run the Web services examples inside Eclipse, you can create a "Run" menu item for this purpose. This is essentially the same process described in Developer's Quick Start, but using the OrcSites module and including the examples/ directory in the classpath:

  1. (In Eclipse) Go to Run -> Run ...
  2. Right-click Java Application and select New
  3. Fill out the Main form as follows: Name: OrcSites Project: OrcSites Main class: orc.Orc
  4. Click the Arguments tab and fill out Program arguments: ${resource_loc}
  5. Click the Classpath tab, click "User Entries", and click "Advanced ..."
  6. Select "Add Folders" and click OK
  7. Choose the "OrcSites/examples" folder and click OK
  8. Click Apply

Now you should create any necessary .properties files in the OrcSites/examples directory, by copying *.sample.properties and modifying it appropriately.

Now to run an example:

  1. Select the example source file in Eclipse.
  2. Go to Run -> Run ..., select OrcSites, and click Run (after doing this once, you can use the dropdown menu of the "run" icon in the toolbar as a shortcut).

Add new attachment

Only authorized users are allowed to upload new attachments.
« This page (revision-8) was last changed on 06-Feb-2009 09:02 by John Thywissen