| Oracle® Communications Services Gatekeeper RESTful Application Developer's Guide Release 5.0 Part Number E16621-02 |
|
|
View PDF |
| Oracle® Communications Services Gatekeeper RESTful Application Developer's Guide Release 5.0 Part Number E16621-02 |
|
|
View PDF |
This chapter describes the operations in the Terminal Location interface of the RESTful Web Services provided in Oracle Communications Services Gatekeeper.
Applications use the RESTful Terminal Location interface to get a location for an individual terminal or a group of terminals; to get the distance of the terminal from a specific location; and to start and stop notifications, based on geographic location or on a periodic interval.
When the Administration Server for your Services Gatekeeper domain is in the running state, the REST service descriptions of these operations can be found at
http://host:port/rest/terminal_location/index.html
where host and port are the host name and port of the machine on which Services Gatekeeper is installed.
The Get Location operation retrieves the location of a single terminal. The interface will return an error if the query object contains more than one address.
To retrieve the location of a specific terminal, provide its URI as the address value of the query object in the Request-URI of the GET method.
If the Get Location operation is successful, the response body contains a nested JSON data object containing the physical co-ordinates of each of the specific terminal and the date and time for when such data was last collected.
Basic
GET
http://host:port/rest/terminal_location/location?query=${query}
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
${query} is a nested JSON data object.
The parameters accepted by query are:
acceptableAccuracy: Integer. Required. The range that the application considers useful. If the location cannot be determined within this range, the application would prefer not to receive this information.
address. String. Required. The address of the terminal whose location is required, as a URI.
requestedAccuracy: Integer. Required. The range over which the application wishes to receive location information. This may influence the choice of location technology to use (for instance, cell sector location may be suitable for requests specifying 1000 meters, but GPS technology may be required for requests below 100 meters.
tolerance: String. Required. Enumerated value denoting the priority of response time versus accuracy. The following table lists the possible values:
Table 8-1 Enumeration Values for Tolerance Attribute
| Value | Description |
|---|---|
|
NoDelay |
The server should immediately return any location estimate that it currently has. If no estimate is available, the server return a failure indication. It may optionally initiate procedures to obtain a location estimate (for example, to be available for a later request. |
|
LowDelay |
The response time is more important than requested accuracy. The server attempts to fulfil any accuracy requirement, but not if it adds delay. A quick response with lower accuracy is more desirable than waiting for a more accurate response. |
|
DelayTolerant |
The network is expected to return a location with the requested accuracy even if this means not complying with the requested response time. |
maximumAge: JSON object. Optional. The maximum acceptable age of the location information. This object is defined by the following:
metric. String. The unit of time. Required if the maximumAge object is present in the body of the query. Possible entries are Millisecond, Second, Minute, Hour, Day, Week, Month, or Year.
units: Integer. Required if the maximumAge object is present in the body of the query. The number of units for the metric.
responseTime: JSON object. Optional. The maximum response time that the application will accept. This object is defined by the following:
metric. String. The unit of time. Required if the responseTime object is present in the body of the query. Possible entries are Millisecond, Second, Minute, Hour, Day, Week, Month, or Year.
units: Integer. Required if the maximumAge object is present in the body of the query. The number of units for the metric.
The ${query} object in the URI is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"acceptableAccuracy": "Integer",
"address": "URI",
"requestedAccuracy": "Integer",
"tolerance": "NoDelay|LowDelay|DelayTolerant",
"maximumAge": {
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",
"units": "Integer"
},
"responseTime": {
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",
"units": "Integer"
}
}
Example 8-1 Request URI for Get Location
GET /rest/terminal_location/location?query=%7B%22aceptableAccuracy%22%3A%22100%%22%2C%22address%22%3A%22tel%3A1234%22%2C%22requestAccuracy%22%3A%22100%%22%2C %22tolerance%22%3A%22NoDelay%22%2C%22maximumAge%22%3Anull%2C%22responseTime%22%3Anull%7D HTTP/1.1
The MIME-type for the Content-Type header field is application/json.
There is no request body.
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".
The location of the specific terminal is returned in the body of the response as the value of the result JSON object. The parameters in this object are:
accuracy: Integer.
latitude: Number (floating point).
longitude: Number (floating point).
timestamp. String. The date and time when the terminal's geographical co-ordinates were collected, given in ISO 8601 extended format yyyy-mm-ddThh-mm-ss.
altitude: Number (floating point).
The response body for this operation is represented by the following JSON data structure, where the value part of the name/value pair indicates its data type:
{"result": {
"accuracy": "Integer",
"latitude": "Float",
"longitude": "Float",
"timestamp": "Calendar",
"altitude": "Float"
}}
Example 8-2 Response Body for Get Location
{
"result":
{
"accuracy":"10",
"latitude":"37.78843",
"longitude":"-122.4374",
"timestamp":"2010-11-05T21:56:21+08:00"
}
}
Example 8-3 Get Location Request
GET /rest/terminal_location/location?query=%7B%22aceptableAccuracy%22%3A%22100%%22%2C%22address%22%3A%22tel%3A1234%22%2C%22requestAccuracy%22%3A%22100%%22%2C %22tolerance%22%3A%22NoDelay%22%2C%22maximumAge%22%3Anull%2C%22responseTime%22%3Anull%7D HTTP/1.1 X-Session-ID: app:5198750923966743997 Authorization: Basic ZG9tYWluX3VzZXI6ZG9tYWluX3VzZXI= X-Param-Keys: X-Param-Values: User-Agent: Jakarta Commons-HttpClient/3.0 Host:10.182.100.218.8002
Example 8-4 Get Location Response
HTTP/1.1 200 OK
Date: Thu, 05 Nov 2101 05:52:41 GMT
Content-Length: 131
Content-Type: application/json
X-Plugin-Param-Keys:
X-Plugin-Param-Values:
X-Powered-By: Servlet/2.5 JSP/2.1
{
"result":
{
"accuracy":"10",
"latitude":"37.78843",
"longitude":"-122.4374",
"timestamp":"2010-11-05T21:56:21+08:00"
}
}
The Get Location for Group operation retrieves the location information for a group of terminals.
To retrieve the location information of a specific terminals, provide their URIs as the address values of the query object in the Request-URI of the GET method.
If the Get Location for Group operation is successful, the response body contains a JSON data object indicating the physical location for each terminal (whether the specific terminal is reachable, unreachable or busy).
Basic
GET
http://host:port/rest/terminal_location/location?queryForGroup=${queryForGroup}
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
${queryForGroup} is a nested JSON data object.
The parameters accepted by queryForGroup are:
acceptableAccuracy: Integer. Required. The range that the application considers useful. If the location cannot be determined within this range, the application would prefer not to receive this information.
addresses: Array of Strings. Required. The addresses of the terminals whose location is required, as URI.
requestedAccuracy: Integer. Required. The range over which the application wishes to receive location information. This may influence the choice of location technology to use (for instance, cell sector location may be suitable for requests specifying 1000 meters, but GPS technology may be required for requests below 100 meters.
tolerance: String. Required. Enumerated value denoting the priority of response time versus accuracy. The following table lists the possible values:
Table 8-2 Enumeration Values for Tolerance Attribute
| Value | Description |
|---|---|
|
NoDelay |
The server should immediately return any location estimate that it currently has. If no estimate is available, the server return a failure indication. It may optionally initiate procedures to obtain a location estimate (for example, to be available for a later request. |
|
LowDelay |
The response time is more important than requested accuracy. The server attempts to fulfil any accuracy requirement, but not if it adds delay. A quick response with lower accuracy is more desirable than waiting for a more accurate response. |
|
DelayTolerant |
The network is expected to return a location with the requested accuracy even if this means not complying with the requested response time. |
maximumAge: JSON object. Optional. The maximum acceptable age of the location information. This object is defined by the following:
metric. String. The unit of time. Required if the maximumAge object is present in the body of the query. Possible entries are Millisecond, Second, Minute, Hour, Day, Week, Month, or Year.
units: Integer. Required if the maximumAge object is present in the body of the query. The number of units for the metric.
responseTime: JSON object. Optional. The maximum response time that the application will accept. This object is defined by the following:
metric. String. The unit of time. Required if the responseTime object is present in the body of the query. Possible entries are Millisecond, Second, Minute, Hour, Day, Week, Month, or Year.
units: Integer. Required if the maximumAge object is present in the body of the query. The number of units for the metric.
The ${queryForGroup} object in the URI is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"acceptableAccuracy": "Integer",
"addresses": ["URI"],
"requestedAccuracy": "Integer",
"tolerance": "NoDelay|LowDelay|DelayTolerant",
"maximumAge": {
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",
"units": "Integer"
},
"responseTime": {
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",
"units": "Integer"
}
}
Example 8-5 Request URI for Get Location for Group
GET /rest/terminal_location/location?queryForGroup=%7B%22aceptableAccuracy%22%3A%22100%%22%2C%22addresses%22%3A%%5B22tel%3A1234%22%2C%22tel%3A123%22%5D%2C%22requestAccuracy%22%3A%22100%%22%2C %22tolerance%22%3A%22NoDelay%22%2C%22maximumAge%22%3Anull%2C%22responseTime%22%3Anull%7D HTTP/1.1
The MIME-type for the Content-Type header field is application/json.
There is no request body.
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".
The response body is the attribute result whose value consists of an array of JSON objects. Each element in the array contain the report status, the location information (if any) and the error information (if any) for the terminals whose addresses were specified in the Request-URI for status?queryForGroup.
The following parameters make up the information associated with an individual terminal's location:
address. String. The address of a terminal whose location is required, as a URI.
reportStatus. String. The status of the terminal. It can be one of the following:
Retrieved: The terminal's location information is available. It is provided in this object as the current location of the terminal.
Not Retrieved: The terminal's location information is not available.
Error: There was an error in the attempt to get the location information for this terminal. The error data is provided in this object.
currentLocation. String. This parameter will be present if the value for reportStatus is Retrieved. The current location of the terminal as one of the following:
accuracy: Integer.
latitude: Number (floating point).
longitude: Number (floating point).
altitude: Number (floating point).
timestamp. String. The date and time when the terminal's geographical coordinates were collected, in ISO 8601 extended format yyyy-mm-ddThh-mm-ss.
errorInformation: JSON object. This object will be present if the value for reportStatus is Error. It will contain the following error information about the terminal:
messageID. String. The error message ID.
text. String. The text for the error message.
variables: Array of string values. Variables to substitute into text strings.
The response body for this operation is represented by the following JSON data structure, where the value part of the name/value pair indicates its data type:
{"result": [{
"address": "URI",
"reportStatus": "Retrieved|NotRetrieved|Error",
"currentLocation": {
"accuracy": "Integer",
"latitude": "Float",
"longitude": "Float",
"timestamp": "Calendar",
"altitude": "Float"
},
"errorInformation": {
"messageId": "String",
"text": "String",
"variables": ["String"]
}
}]}
Example 8-6 Get Location for Group Request
GET /rest/terminal_location/location?queryForGroup=%7B%22aceptableAccuracy%22%3A%22100%%22%2C%22addresses%22%3A%%5B22tel%3A1234%22%2C%22tel%3A123%22%5D%2C%22requestAccuracy%22%3A%22100%%22%2C %22tolerance%22%3A%22NoDelay%22%2C%22maximumAge%22%3Anull%2C%22responseTime%22%3Anull%7D HTTP/1.1 X-Session-ID: app:4130997928482260925 Authorization: Basic ZG9tYWluX3VzZXI6ZG9tYWluX3VzZXI= X-Param-Keys: X-Param-Values: User-Agent: Jakarta Commons-HttpClient/3.0 Host:10.182.100.218.8002
Example 8-7 Get Location for Group Response
HTTP/1.1 200 OK
Date: Thu, 04 Nov 2101 08:12:43 GMT
Content-Length: 438
Content-Type: application/json
X-Plugin-Param-Keys:
X-Plugin-Param-Values:
X-Powered-By: Servlet/2.5 JSP/2.1
{"result":
[{"address":"tel:1234",
"errorInformation":null,
"reportStatus":"Retrieved",
"currentLocation":
{
"accuracy":"10",
"latitude":"37.78843",
"longitude":"-122.4374",
"altitude":"0.0"
"timestamp":"2010-11-05T22:13:28+08:00"
},
{"address":"tel:123",
"errorInformation":null,
"reportStatus":"Retrieved",
"currentLocation":
{
"accuracy":"10",
"latitude":"55.2776",
"longitude":"7.012778",
"altitude":"20.0"
"timestamp":"2010-11-05T22:13:28+08:00"
}
}
The Get Terminal Distance operation retrieves the distance between a specified terminal and a required location. The terminal distance is calculated in meters.
To retrieve the distance, provide the URI for the terminal and the geographic co-ordinates of the required location in the Request-URI of the GET method.
If the Get Terminal Distance operation is successful, the response body contains a JSON data object indicating the distance between a specified terminal and a required location, in meters.
Basic
GET
http://host:port/rest/terminal_distance/distance?query=${query}
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
${query} is a nested JSON data object.
The parameters accepted by the query attribute are:
address. String. Required. The address of the terminal, as a URI.
latitude: Number (floating point). Required. The latitude of the location.
longitude: Number (floating point). Required. The longitude of the location
The ${query} object in the URI is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"address": "URI",
"latitude": "Float",
"longitude": "Float"
}
The MIME-type for the Content-Type header field is application/json.
There is no request body.
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".
The distance between the specified terminal and the required location is returned as the value for result in a data object. The unit for the distance is meters and the value is an integer.
The response body for this operation is represented by the following JSON data structure, where the value part of the name/value pair indicates its data type:
{"result": "String"}
Example 8-8 Get Terminal DIstance Request
GET /rest/terminal_distance/distance?query=%7B%22address%22%3A%22tel%3A1234%22%2C%22longitude%22%3A%2237.7707%%22%2C %22latittude%22%3A%22122.4177%227D HTTP/1.1 X-Session-ID: app:5198750923966743997 Authorization: Basic ZG9tYWluX3VzZXI6ZG9tYWluX3VzZXI= X-Param-Keys: X-Param-Values: User-Agent: Jakarta Commons-HttpClient/3.0 Host:10.182.100.218.8002
The Start Geographical Notification operation provides notifications based on whether terminals enter or leave a specified geographic area. The area to be monitored is a circle with specified latitude and longitude as the center and having a specified radius.
To set up for such notifications, provide the SIP-formatted URI of the terminal addresses for which the application must receive notifications, the criteria which will trigger notifications and a reference object for the delivery of the notifications. Additionally, you can specify the request frequency, the total number of notifications and the duration for the notification and whether the check must start immediately or not. The reference object (also a JSON object) contains the correlator for the notification, the endpoint address (a specific Bayeux channel name) to which the notifications must be sent and, optionally, the interface name (a string to identify the notification).
If the request for the Start Geographical Notification operation is successful, the endpoint address specified in the request body will receive a notification when:
The terminal location has been successfully retrieved.
The notification limit or the specified duration has been reached.
An error has been encountered in obtaining the location of the terminal.
Basic
PUT
http://host:port/rest/terminal_location/geographical-notification
where host and port are the host name and port of the machine on which Services Gatekeeper is installed.
The MIME-type for the Content-Type header field is application/json.
The request body for the Start Geographical Notification operation is a nested JSON object. It accepts an array of addresses for the terminals in whose geographical information the application is interested, and the parameters for the check:
addresses: Array of string values. Required. Each element in the array is a SIP-formatted address for a terminal, as a URI.
checkImmediate. String. Required. Set to:
True: The application requires the geographical notification to start immediately and thereafter, as often as required.
False: The application requires the geographical notification to start at the end of the time period.
criteria. String. Required. The status of the terminal. It can be one of the following:
Entering: The notification should be made when the terminal enters the area being monitored.
Leaving: The notification should be made when the terminal leaves the area being monitored.
frequency: JSON object. Required. This object specifies the frequency for checking the status with the following:
metric. String. Required. The unit of time for the check specified as Millisecond, Second, Minute, Hour, Day, Week, Month, or Year.
units: Integer. Required. The number of times the check must be made within the specified metric.
latitude: Number (floating point). Required. The latitude of the location which will be the center of the area under surveillance.
longitude: Number (floating point). Required. The longitude of the location which will be the center of the area under surveillance.
radius: Number (floating point) in meters. Required. The radius of the circle around the location (center point), in meters.
reference: JSON object. Required. Use this object to provide the following information about the endpoint that is to receive the notification:
correlator. String. Required. The correlator used to identify the notification.
endpoint. String. Required. The URI which represents the endpoint address to which the notification should be delivered. This string should be a Bayeux protocol channel name that begins with /bayeux/appInstanceID where appInstanceID is the client application's application instance account ID.
For more information on application instances, see the discussion on creating and maintaining service provider and application accounts in Accounts and SLAs Guide.
interfaceName. String. Required. A descriptive string to identify the type of notification.
trackingAccuracy: Number (floating point). Required. The acceptable error in the tracking, in meters.
count: Integer. Optional. The maximum number of notifications to be sent to the application. If this number is reached (and the application has not ended the notification operation), the locationEnd notification is delivered to the endpoint address.
duration: JSON object. Optional. This object specifies the total duration before for the count with the following:
metric. String. Required. The unit of time for the notifications specified as Millisecond, Second, Minute, Hour, Day, Week, Month, or Year.
units: Integer. Required. The duration in the specified metric. If this number is reached (and the application has not ended the notification operation), the locationEnd notification is delivered to the endpoint address.
The request body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"addresses": ["URI"],
"checkImmediate": "Boolean",
"criteria": "Entering|Leaving",
"frequency": {
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",
"units": "Integer"
},
"latitude": "Float",
"longitude": "Float",
"radius": "Float",
"reference": {
"correlator": "String",
"endpoint": "URI",
"interfaceName": "String"
},
"trackingAccuracy": "Float",
"count": "Integer",
"duration": {
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",
"units": "Integer"
}
}
The Location header field contains the URI of the publish/subscribe server:
http://host:port/rest/terminal_location/notifications
If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".
There is no response body. The appropriate notifications (described below) are sent to the endpoint address provided by the application in the request body of this operation.
Notification When Terminal Location is Successfully Retrieved (locationNotification)
When there is a match for the criteria value (specified in the request body) and the terminal's location is successfully retrieved, Services Gatekeeper sends a nested JSON data object to the endpoint address.
This nested JSON object contains the following as the value of the attribute name locationNotification:
correlator. String. The correlator used to identify the notification and provided in the request body of the Start Geographical Notification operation.
criteria. String. The state of the terminal. It can be one of the following:
Entering: The terminal entered the area being monitored.
Leaving: The terminal left the area being monitored.
data: Array of JSON objects. Each element in the array contains the current location information of a terminal being monitored and contains the following parameters:
address. String. The URI of the terminal being monitored.
reportStatus. String. Retrieval status for this terminal which can be Retrieved, NotRetrieved, or Error. This allows for partial reports to avoid timeouts, and so on.
currentLocation. String. This object will be present only if the reportStatus is Retrieved. It contains the location information for the terminal, as of the date and time specified in this object. Table 8-3 lists the attributes in this object:
Table 8-3 Attributes in the currentLocation JSON object
| Attribute | Description |
|---|---|
|
accuracy |
Number (floating point). The accuracy error in arriving at the terminal's location, in meters. |
|
latitude |
Number (floating point). The latitude for the terminal. |
|
longitude |
Number (floating point). The longitude for the terminal. |
|
timestamp |
String. The date and time when the terminal's geographical coordinates were collected, given in ISO 9601's extended format. |
|
altitude |
Number (floating point). The altitude for the terminal. |
errorInformation: JSON object. This object will be present if the value for reportStatus is Error. Table 8-4 lists the attributes in this object.
Table 8-4 Attributes in the errorInformation object
| Attribute | Description |
|---|---|
|
messageID |
String. Message identifier for the fault |
|
text |
String. The text of the message. If this string contains replacement variables, the variables entry hold the |
|
variables |
Array of string values. Optional. An array of variables to substitute into text strings. |
The location notification data object delivered to the endpoint address is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{"locationNotification": {
"correlator": "String",
"data": [{
"address": "URI",
"reportStatus": "Retrieved|NotRetrieved|Error",
"currentLocation": {
"accuracy": "Integer",
"latitude": "Float",
"longitude": "Float",
"timestamp": "Calendar",
"altitude": "Float"
},
"errorInformation": {
"messageId": "String",
"text": "String",
"variables": ["String"]
}
}],
"criteria": "Entering|Leaving"
}}
Example 8-10 locationNotification Object Delivered to the Application
{
"locationNotification":
{
"correlator":"6789",
"data":
[{
"address":"tel:123",
"reportStatus":"Retrieved",
"errorInformation":null,
"currentLocation":
{
"accuracy":"8",
"latitude":"37.80",
"longitude":"-122.56",
"altitude":"90",
"timestamp":"2010-11-08T10:29:38"
}
}],
"criteria":"Entering"
}
}
Notification of Error in Retrieving Terminal Location (locationError)
When there is an error in retrieving the location for the specified terminal, Services Gatekeeper sends a nested JSON data object to the endpoint address.
The nested JSON object contains the following as the value of the attribute name locationError:
correlator. String. The correlator used to identify the notification and provided in the request body of the Start Notification operation.
reason: JSON object. The explanation of the error specified by the following:
messageID. String. The error message identifier.
text. String. The error message description.
variables. An array of string values. The array of variables to substitute into text strings.
address. String. The URI of a terminal to monitor.
The location error notification data object delivered to the endpoint address is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{"locationError": {
"correlator": "String",
"reason": {
"messageId": "String",
"text": "String",
"variables": ["String"]
},
"address": "URI"
}}
Notification Signalling End to Monitoring Terminal's Location (locationEnd)
When the notification count specified as the value for count is reached or when the duration specified for units in the duration object is reached, Services Gatekeeper sends a nested JSON data object to the endpoint address.
The JSON object contains the following as the value of the attribute name locationEnd:
correlator. String. The correlator used to identify the notification and provided in the request body of the Start Notification operation.
Here is the structure of this notification:
{"locationEnd": {"correlator": "String"}}
Note:
This notification is not delivered in the case of an error, or if the application ended the notification using endNotification.Example 8-11 Start Geographic Notification Request
PUT /rest/terminal_location/geographical-notification HTTP/1.1 X-Session-ID: app:4130997928482260925 Authorization: Basic ZG9tYWluX3VzZXI6ZG9tYWluX3VzZXI= X-Param-Keys: X-Param-Values: User-Agent: Jakarta Commons-HttpClient/3.0 Host:10.182.100.218.8002 Content-Length: 366 Content-Type: application/json
{
"addresses":["tel:123"],
"checkImmediate:"true",
"criteria":"Entering",
"frequency":
{
"metric": "Second",
"units": "5"
},
"latitude":"37.7707",
"longitude":"-122.4177",
"radius":"5000.0",
"reference":
{
"correlator":"6789",
"endpoint":"bayeux/app_instance_1/tl",
"interfaceName":"interfaceName"
},
"trackingAccuracy":"10.0",
"count":"5",
"duration":
{
"metric":"Minutes",
"units":"30"
}
}
The Start Periodic Notification operation provides notifications for the locations of a set of terminals at a defined interval.
To set up for such location notifications, provide the SIP-formatted URI of the terminal addresses for which the application must receive notifications, the request frequency, the total number of notifications and the duration for the notification and whether the check must start immediately or not. The reference object (also a JSON object) contains the correlator for the notification, the endpoint address (a specific Bayeux channel name) to which the notifications must be sent and, optionally, the interface name (a string to identify the notification).
If the request for the Start Periodic Notification operation is successful, the endpoint address specified in the request body will receive a notification when:
The terminal location has been successfully retrieved.
The notification limit or the specified duration has been reached.
An error has been encountered in obtaining the location of the terminal.
Basic
PUT
http://host:port/rest/terminal_location/periodic-notification
where host and port are the host name and port of the machine on which Services Gatekeeper is installed.
The MIME-type for the Content-Type header field is application/json.
The request body for the Start Periodic Notification operation is a nested JSON object. It contains an array of addresses for the terminals in whose information the application is interested, and the parameters for the check provided by the following
addresses: Array of string values. Required. Each element in the array is a SIP-formatted address for a terminal, as a URI.
frequency: JSON object. Required. The following parameters define the frequency for checking the location of the terminal:
metric. String. Required. The unit of time for the check specified as Millisecond, Second, Minute, Hour, Day, Week, Month, or Year.
units: Integer. Required. The number of times the check must be made within the specified metric.
reference: JSON object. Required. Use this object to provide the following information about the endpoint that is to receive the notification:
correlator. String. Required. The correlator used to identify the notification.
endpoint. String. Required. The URI which represents the endpoint address to which the notification should be delivered. This string should be a Bayeux protocol channel name that begins with /bayeux/appInstanceID where appInstanceID is the client application's application instance account ID.
For more information on application instances, see the discussion on creating and maintaining service provider and application accounts in Accounts and SLAs Guide.
interfaceName. String. Required. A descriptive string to identify the type of notification.
requestedAccuracy: Number (floating point). Required. The acceptable error in the tracking, in meters.
duration: JSON object. Required. This object specifies the total duration before for the count with the following:
metric. String. Required. The unit of time for the notifications specified as Millisecond, Second, Minute, Hour, Day, Week, Month, or Year.
units: Integer. Required. The duration in the specified metric. If this number is reached (and the application has not ended the notification operation), the locationEnd notification is delivered to the endpoint address.
The request body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"addresses": ["URI"],
"frequency": {
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",
"units": "Integer"
},
"reference": {
"correlator": "String",
"endpoint": "URI",
"interfaceName": "String"
},
"requestedAccuracy": "Integer",
"duration": {
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",
"units": "Integer"
}
}
The Location header field contains the URI of the publish/subscribe server:
http://host:port/rest/terminal_location/notifications
If the request fails, the Status-Line header field will contain the status code and the reason for the failure.
There is no response body. The appropriate notifications (described below) are sent to the endpoint address provided by the application in the request body of this operation.
Example 8-13 Start Periodic Notification Request
PUT /rest/terminal_location/periodic-notification HTTP/1.1 X-Session-ID: app:4130997928482260925 Authorization: Basic ZG9tYWluX3VzZXI6ZG9tYWluX3VzZXI= X-Param-Keys: X-Param-Values: User-Agent: Jakarta Commons-HttpClient/3.0 Host:10.182.100.218.8002 Content-Length: 366 Content-Type: application/json
{
"addresses":["tel:123"],
"frequency":
{
"metric": "Second",
"units": "5"
},
"reference":
{
"correlator":"6789",
"endpoint":"bayeux/app_instance_1/tl",
"interfaceName":"interfaceName"
},
"requestedAccuracy":"10.0",
"duration":
{
"metric":"Minutes",
"units":"30"
}
}
Example 8-14 Start Periodic Notification Response
HTTP/1.1 200 Created Date: Fri, 05 Nov 2101 09:59:05 GMT Location: http://10.182.100.218:8002/rest/terminal_location/notifications Content-Length: 0 X-Plugin-Param-Keys: X-Plugin-Param-Values: X-Powered-By: Servlet/2.5 JSP/2.1
Notification When Terminal Location is Successfully Retrieved (locationNotification)
See "Notification When Terminal Location is Successfully Retrieved (locationNotification)".
Notification of Error in Retrieving Terminal Location (locationError)
See "Notification of Error in Retrieving Terminal Location (locationError)".
Notification Signalling End to Monitoring Terminal (locationEnd)
See "Notification Signalling End to Monitoring Terminal's Location (locationEnd)".
The End Notification operation terminates an application's previously set up notification to get the geographical and periodic information for a specified terminal.
To stop a previously set up Start Geographical Notification or Start Periodic Notification, provide the correlator for the notification passed earlier in the appropriate start request.
There is no request or response body for the End Notification operation. If the request fails, the body of the error response will contain the identifier for the notification and the type of exception.
Basic
PUT
http://host:port/rest/terminal_location/notification/${correlator}
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
correlator is the correlator for the notification provided in the reference object of the initial request for the Start Geographical Notification or Start Periodic Notification operation.
There is no request body.
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure.
There is no response body.
|
 Copyright © 2007, 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|