Menu

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.

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 several 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:

Global Reservation Identifier (int, 0 or 1)  - should only be input by an IDC when forwarding a createReservation request

Start Time (long) -time to start the reservation in seconds since midnight, January 1, 1970 UTC.

End Time (long) - time to end the reservation in seconds since midnight, January 1, 1970 UTC.

bandwidth (int) - bandwidth to be reserved in Mbps. (mega bits per second)

description (string) - description of the purpose of the reservation.

Path Info:

pathSetupMode (string)

"timer-automatic" means that the reserved circuit will be instantiated by the scheduler process

"signal-xml" means the user will signal to instantiate the reserved circuit

pathType (string, 0 or 1) should be input as "loose", paths input from users are treated as suggestions.

path (CtrlPlanePathContent, 0 or 1) Contains only domain ingress and egress links

hop (0 or more)

domainIdRef (string, 0 or 1)

nodeIdRef (string, 0 or 1)

portIdRef (string, 0 or 1)

linkIdRef (string, 0 or 1)

layer2Info (layer2Info) (one of layer2 or layer 3 info must be input)

srcVtag (string, 0 or 1) can be a number, a range of numbers (3000-4000) or "any"

destVtag (string, 0 or 1) can be a number, a range of numbers (3000-4000) or "any"

srcEndpoint (string) The ingress link. May be a topology identifier, IPaddr or Host Name. If it looks like a name, the DNS server will be called to resolve it to an IPAddr. Given an IPAddr, a lookup server will be called to find its topology identifier.

destEndpoint (string) The egress link . May be a topology identifier, IPaddr or Host Name. If it looks like a name, the DNS server will be called to resolve it to an IPAddr. Given an IPAddr, a lookup server will be called to find its topology identifier.

layer3Info (layer3Info) (one of layer2 or layer 3 info must be input)

srcHost (string) - may be DNS name, IPaddr or topology identifier. If it is a Host Name, the DNS will be used to resolve it to an IPaddr. If it a topology identifier, its IPaddr will be found from the topology database.
destHost (string) - may be DNS name, IPaddr or topology identifier, f it is a Host Name, the DNS will be used to resolve it to an IPaddr. If it a topology identifier, its IPaddr will be found from the topology database.
protocol (string, 0 or 1) - "UDP" or "TCP"
srcIpPort (int, 0 or 1) - port on the source host to use
destIpPort (int, 0 or 1) - port on the destination host to use
dscp (string, 0 or 1) - used by TeraPaths to set QoS bits

mplsInfo (mplsInfo, 0 or 1) specific to Cisco and Juniper routers

burstLimit (int) - in bits per second (bps) - maximum instantaneous burst allowed 

lspClass (string, 0 or 1) - forwarding class that the packets transiting the LSP will be set to (i.e. MPLS EXP bits)

Reply message parameters:

globalReservationId (string) - the reservation id  assigned to this reservation

token (string, 0 or 1) If the pathSetupMode was xml-signaled a token will be returned that may be used to signal circuit  setup and tear down.

status (string) - should be ACCEPTED

pathInfo ( pathInfo) - same format as described above, but all the hops have been filled in and resources reserved resulting in a confirmed SIDP.

Possible fault messages:

checkUser: no certSubject found in message - message was not signed correctly

checkUser invalid user

checkUser: no attributes for user  - user has no privileges

createReservation: permission denied

invalid parameters: null reservation, null login, null network layer information

pathfinder errors depending on which pathfinder is being used.

hop in path does NOT have an associated physical interface: [linkRef]

hop in path has maximum reservable capacity = 0: [linkRef]

Node [linkRef] oversubscribed:  RequiredCapacity > maximumReservableCapacity

createReservation interdomain error

failed to reach remote domain - the next domain in the path could not be reached.

AAAfaultMsg (same as above but from remote domain)

BSSfaultMsg (same as above but from remote domain)

 

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.

Request message parameters:

Global Reservation Id (string) - the reservation id returned by Create Reservation

Reply message parameters:

globalReservationId (string) - the reservation id

login (string) - login name of the owner of the reservation

status (string) -

SUBMITTED - reservation request has been submitted and a reply sent to the requester

ACCEPTED - reservation request has been accepted and the reservation is scheduled to be processed

INCREATE - reservation creation is in process

PENDING - reservation processing is complete and resources have been reserved, but the scheduled start time has not arrived yet (may have required inter-domain operations)

INSETUP - the circuits are being provisioned - (may require inter-domain operations)

ACTIVE - circuit is currently provisioned

INMODIFY - a modification requested by the user is in process (inter-domain operation)

INTEARDOWN - the end-to-end circuit is in the process of being torn-down (inter-domain operation)

FINISHED - end time has past, and circuit has been torn down

CANCELLED - reservation was canceled, circuit is not active

FAILED - Path may have failed to be setup because the required resources were not available, or a link that the circuit uses is down and the circuit may still be provisioned

See reservation state diagram

startTime (long) - reservation start time in seconds since midnight, January 1, 1970 UTC.

endTime (long) - reservation end time in seconds since midnight, January 1, 1970 UTC.

createTime (long) - time reservation was created in seconds since midnight, January 1, 1970 UTC.

bandwidth (int) - Bits per second (bps)

description (string) - the description of the reservation

pathInfo:  see above

 

Possible fault messages

checkUser errors

Reservation not found:

query reservation: permission denied

 

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.

Request message parameters:

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

resStatus (string) - zero or more of  ACTIVE, PENDING, FINISHED, CANCELLED, FAILED. If no status is input, all statuses will be matched.

sequence of 0 or 1

startTime (long) - reservations ending after this time

endTime (long) - reservations starting before this time

thus all reservations that are active within this interval

description (string, 0 or 1) - reservation descriptions must contain this string.

linkId (string, 0 or more) - reservations must contain these hops

vlanTag(vlanTag, 0 or more) - reservations must contain these vlanTags

resRequested (int, 0 or 1) - number of reservations to return. If not set, all reservations that match are returned.

resOffset (int, 0 or 1) - offset of first reservation to return. If not set, offset will be 0.

 

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

checkUser errors

listReservations: permission denied

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

globalReservationId (string) - the reservation id returned by Create Reservation

startTime(long) -time to start the reservation in seconds since midnight, January 1, 1970 UTC.

endTime(long) -time to end the reservation in seconds since midnight, January 1, 1970 UTC.

bandwidth (int) - bandwidth in Mbps

description (string) - description of purpose of reservation

pathInfo (PathInfoType)

Reply message parameters

reservationDetails (resDetails)  - the details for the modified reservation

 


5. Cancel Reservation

Request message parameters:

Global Reservation Id (string) - the reservation id returned by Create Reservation

Response message parameters:

status (string) - the new status of the reservation - it will be CANCELLED if the reservation was PENDING or PRECANCEL if the reservation was ACTIVE. For an ACTIVE reservation the scheduler must tear down the circuit before the reservation is changed to CANCELLED.

possible fault messages:

No current reservation with GRI

cancel reservation: permission denied

Trying to cancel a finished|failed|or already cancelled reservation

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:

payload (forwardPayload)

contentType (string) - one of "createReservation","modifyReservation", "cancelReservation", "queryReservation", "createPath", "refreshPath","modifyPath", "teardownPath"

one of the following elements as specified by the contentType parameter

createReservation (resCreateContent)

modifyReservation (resModifyContent)

cancelReservation (globalReservationId)

queryReservation (globalReservationId)

createPath (createPathContent)

refreshPath (refreshPathContent)

teardownPath (teardownPathContent)

payloadSender (string) - subject DN of the original requester. This is for information or logging of subsequent domains. This message is signed, authenticated and authorized by the forwarding IDC service.

Return message parameters:

contentType (string) - one of - one of "createReservation","modifyReservation", "cancelReservation", "queryReservation", "createPath", "refreshPath","modifyPath", "teardownPath"

one of the following elments as specified by the contentType parameter

createReservation (createReply)

modifyReservation (modifyResReply)

cancelReservation (string) -  new message status: CANCELLED or PRECANCEL

queryReservation (resDetails)

createPath (createPathResponseContent)

refreshPath (refreshPathResponseContent)

teardownPath (teardownPathResponseContent)

Possible fault messages:

failed to reach remote domain:

All the ones from the message being forwarded.


7. Get Network Topology

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

Request message parameters:

topologyType (string) - currently must have the value "all". In the future the values: "adjacentdomains","delta" or "internetworklinks" will be supported as well.

Request message parameters:

ctrplTopology - a nmwg topology description

Possible fault messages:

OSCARSSkeleton:getNetworkTopology: permission denied - need query permission on domains.

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:

token (string, 0 or 1) - must be input if you are not the creator of the reservation

globalReservationId (string) - the reservation id returned by Create Reservation

Request message parameters:

globalReservationId (string) - the reservation id that was input

status (string) - will be ACTIVE if the call succeeded.

Possible fault messages:

OSCARSSkeleton:createPath: permission denied  - you do not have signal permission

no reservations match request

Path setup mode is null

Path setup mode is not signal-xml

Path cannot be created. Invalid reservation specified.  - occurs if status is not PENDING

Path cannot be created. Reservation start time not yet reached.

Path cannot be created. Reservation end time has been reached.


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:

token (string, 0 or 1) - must be input if you are not the creator of the reservation

globalReservationId (string) - the reservation id returned by Create Reservation

Reply message parameters:

globalReservationId (string) - the reservation id that was input

status (string) - will be ACTIVE if the path is still valid, FAILED if the path is invalid

Possible fault messages

OSCARSSkeleton:refreshPath: permission denied  - you do not have signal permission

no reservations match request - if request not found, or is not mode xml-signal

Path cannot be refreshed.Reservation is not active. Please run createPath first.

A path failure has occurred. The path is no longer active. Reason:


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:

token (string, 0 or 1) - must be input if you are not the creator of the reservation

globalReservationId (string) - the reservation id returned by Create Reservation

Reply message parameters:

globalReservationId (string) - the reservation id that was input

status (string) - will be PENDING  if the teardown was successful but the reservation end time has not been reached. It will be FINISHED if it is later than the end time.

Possible fault messages

OSCARSSkeleton:refreshPath: permission denied  - you do not have signal permission

no reservations match request - if request not found, or is not mode xml-signal

Path cannot be refreshed.Reservation is not active. Please run createPath first.

A path failure has occurred. The path is no longer active. Reason: