API User Manual
OSCARS
version 0.4 September
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:
- 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.
2. Query
Reservation
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) -
- ACCEPTED - reservation request has been accepted and the
reservation is scheduled to be processed
- PENDING/RESERVED
- 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
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.
- 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
- 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
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 elments as specified by the
contentType
parameter
- 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:
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. Initiate
Topology
Pull
Tells an IDC to update its topology. Causes the IDC to pull the
complete topologies for all the domains in its domain tables, and to
update the topology tables with the results. For a description of the
topology tables see the Topology section in the
developers manual.
Request message parameters:
- topologyType
(string) - currently
ignored and set to "all" in the getNetworkTopology calls.
Request message parameters:
- resultMsg (string) -
SUCCESS if the all the domains have been updated. Otherwise it will
contain all the topology exception messages.
Possible fault messages:
- OSCARSSkeleton:initiateTopologyPull: permission denied -
need modify permission on domains.
- No local domain has been specified - this is an internal error in
the domains database
examples/javaClients/initiateTopologyPull.sh
will call InitiateTopologyPullClient.java. As usual edit
initiateTopologyPull.sh to
set the URLs for your server host.
9. 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.
10. 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:
11. 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: