The Parlay X Terminal Location over MLP describes
how as part of the implementation each individual Web service operation
will be mapped to the interfaces provided by the MLP Protocol.
Call flows
Call flows are provided for the
following request and response major code paths:
- Maps incoming Parlay X parameters to MLP parameters.
- Maps the response MLP values to Parlay X understandable parameters.
The following is an example call flow showing how calls
to the Service Platform components are
invoked. In this example the call flow begins when the Parlay X 2.1
Terminal Location Requests and the corresponding HTTP requests to
the backend Location server are synchronous operations:
- The Web service client request is received by the TWSS Access Gateway.
- The SOAP request is forwarded to the Web service implementation.
- The Web service implementation receives the request and validates
the input parameters. It then converts the input parameters from Parlay
X data structures to parameters that are understandable by MLP.
- An HTTP URL connection with the MLP server is opened. The connection
is used for both request and response flows.
Note: For triggered notification
operations, the notification data will be stored in a database table
and updated when changes take place.
- The HTTP URL connection receives the response data. A Callback
Servlet listens for the triggered response messages for notification
requests.
- The retrieved response objects (Response and Error) are converted
to Parlay X data structures.
- The response from the location-based synchronous operation is
forwarded to the Access Gateway,
which passes the response to the Web service client.
- The triggered notification operation sends the response/notification
information to the notification endpoint.
- The database table is updated with the current status.
The HTTP connections are used for both the request and response
flows. All Terminal Location notification requests are intended to
be triggered by an event or based on a periodic timer. The callback
responses are received asynchronously from the MLP location server
and are then processed by a Callback Servlet in order to deliver the
notification to a third-party application.
Interfaces
- TerminalLocation
- getLocation
- Retrieves the location of a single terminal. The accuracy requested is
the desired accuracy for the response. The acceptable accuracy is the limit
acceptable to the requester. The URI provided is for a single terminal.
- getLocationForGroup
- Retrieves the location of a group of terminals. Its function is the same
as GetLocation, except that a group URI is expected as input.
- getTerminalDistance
- Determines the distance of a single terminal from a location. The URI
provided cannot be a group URI.
- TerminalLocationNotificationManager
- startGeographicalNotification
- Registers an application server to receive a notification when
a terminal enters or exits an area specified by a longitude, latitude,
and radius.
Note: This implementation is provided only when the MLP
3.2 specification is selected. If MLP 3.1 is selected as the default,
the request is ignored and a corresponding error message is returned
to the Web service client.
Note: MLP provides the following
format for specifying both duration and frequency: ddhhmmss.
As a result, the maximum possible value is 99 days, 23 hours, 59 minutes,
and 59 seconds.
- startPeriodicNotification
- Registers an application server to receive a notification at some
given interval.
Note: This implementation is provided for both MLP
3.1 and MLP 3.2 specifications.
Note: MLP provides the following
format for specifying both duration and frequency: ddhhmmss.
As a result, the maximum possible value is 99 days, 23 hours, 59 minutes,
and 59 seconds.
- endNotification
- De-registers an application server from receiving notifications.
- TerminalLocationNotification
- locationNotification
- Sent to an application when a notification is received.
- locationError
- Sent to an application when a notification error occurs.
- locationEnd
- Indicates that the notifications have ended for this application; called
when the duration or count for notifications has been completed.
Supported MLP shapes
Versions 3.1 and 3.2
of the MLP protocol define various shapes for representing geographical
areas in which a mobile subscriber can be located. The following shapes
are supported by this Web service implementation:
- Point
- CircularArea
- CircularArcArea
- EllipticalArea
- LineString
- LinearRing
- Box
- Polygon
- MultiPoint
Refer to the MLP specification for the precise definitions
of these shapes.
Usage records
The
interfaces for
Parlay X Terminal Location over MLP generate
usage records as follows.
Interface |
Usage records written |
TerminalLocation: getLocation |
1 usage record per operation |
TerminalLocation: getLocationForGroup |
1 usage record per URI target in the group |
TerminalLocation: getTerminalDistance |
1 usage record per target |
TerminalLocationNotificationManager: startGeographicalNotification |
1 usage record per target |
TerminalLocationNotificationManager: startPeriodicNotification |
1 usage record per target |
TerminalLocationNotificationManager: endNotification |
1 usage record per operation |
TerminalLocationNotification: locationNotification |
None |
TerminalLocationNotification: locationError |
None |
TerminalLocationNotification: locationEnd |
None |
For more details, refer to the topic Usage
records for Parlay X Terminal Location over MLP.