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