home > User Manual > API User Manual

API User Manual

OSCARS version 0.5 September 2009

Web Service Interface (API)

The web service interface is defined by the OSCARS.wsdl , OSCARS.xsd and nmtopo-ctrlp.xsd
We provide a Java client-side interface class, net.es.oscars.client/Client.java, to setup, marshal parameters, send, receive and unmarshal the parameters. There is also a directory, examples/javaClients that has two command line programs for each message. One version prompts for arguments and the other (*CLI) take all the arguments from the command line. 

The functional interfaces are:

Note: (0 or 1) means that there can be 0 or 1 instances of the parameter, ( 0 or more) means 0 or unlimited instances are allowed. Otherwise there must be just one instance.

1. Create Reservation

Schedules a reservation. Path information may be specified in either layer 2 or layer 3 formats. Currently layer3 reservations are only supported by ESnet and so will only work when both the source and destination hosts are directly served by ESnet.

The path parameter comes in serveral varieties. An input path is considered Loose Interdomain Path (LIDP) where the hops are taken as suggestions. It may only contain domain ingress and egress links. Once the IDC(s) have chosen a path, it becomes a Strict Interdomain Path (SIDP). It may contain some abstract intradomain network elements. When the resources have been reserved, the path becomes a  confirmed SIDP.

Request message parameters:
Reply message parameters: Possible fault messages:

examples/javaClients/CreateRes.sh is a shell script that reads the input arguments from a property file and runs the CreateReservation.java program.

createRes.sh -pf examples.l1.properties

There are two example properties files: example.l2.properties (for a layer 2 reservation) and
example.l3.properties (for a layer 3 reservations) These file contain the createReservation parameters. Edit the url1 to point to your service host, and url2 for an alternative host. You can use https://localhost/axis2/OSCARS if you are running the examples on your server.
Edit the source, destination and ERO values for your host.

2. Query Reservation


Request message parameters:
Reply message parameters:

Possible fault messages

examples/javaClients/queryRes.sh will run the QueryReservationClient.  Edit queryRes.sh to set the URLs for the OSCARS host(s) in your domain. It will prompt for the GRI of the reservation that you want to query. Note that QueryReservationClient does not print out some of the pathInfo values.


3. List Reservations

Request message parameters:

The following may be set to limit the reservations that are returned.

Note that this may be called with no input parameters and is thus a good call to make for your first attempt to contact your server. It will test whether your keystores and permissions are correctly set up.

Reply message parameters:

An array of ResDetails - this is the same set of parameters that Query Reservation returns.

Possible fault messages
examples/javaClients/listRes.sh will call ListReservationsClient.java which will prompt for the input arguments. As usual edit listRes.sh to set the URLs for your server host.

4. Modify Reservation

This interface allows the modification of a scheduled or active reservation. Currently only the start and end time of the reservation may be changed. The rest of the parameters will be ignored.

Request message parameters
Reply message parameters
        reservationDetails (resDetails)  - the details for the modified reservation

5. Cancel Reservation


Request message parameters:
Response message parameters:
possible fault messages:
examples/javaClients/cancelRes.sh will call CancelReservationClient.java which will prompt for the input arguments. As usual edit cancelRes.sh to set the URLs for your server host.

6. Forward

This call is for use by an IDC only. It forwards a message that it has received to the next domain on the reservation path. It is called by the server class net.es.oscars.interdomain/Forwarder.

Request message parameters:
Return message parameters:
Possible fault messages:

7. Get Network Topology

Calls an IDC to get a global view of the domain's topology.

Request message parameters:
Request message parameters:
Possible fault messages:
examples/javaClients/getNetworkTopology.sh will call GetNetworkTopologyClient.java. As usual edit getNetworkTopology.sh to set the URLs for your server host.

8. Create Path

Causes all the IDCs on the path to provision the path for a previously scheduled reservation whose start time has been reached. The reservation must have been created with a pathSetupMode of "xml-signal".

Request message parameters:
Request message parameters: Possible fault messages:


9. Refresh Path

Checks to see if the path of a scheduled reservation is still valid. Checks local path
first and if it is ok  then forwards the refreshPath request. If the local path has failed it forwards a teardown message. If the forwardResponse indicates an downstream error the local path is removed and the exception passed upstream.

Request message parameters:
Reply message parameters:

Possible fault messages

10 . Teardown Path

Will teardown an ACTIVE reservation. Removes local path
first and then forwards request. If there is a failure in the local path
the teardown the request is still forwarded and the exception is reported
upstream. The reservation status is reset to PENDING
if the reservation end time has not been reached, so that the path could still rebuilt.

Request message parameters:
Reply message parameters:

Possible fault messages