This chapter describes the Oracle Communications Services Gatekeeper Parlay X 2.1 Terminal Location/Mobile Location Protocol (MLP) communication service in detail.
The Parlay X 2.1 Terminal Location/MLP communication service exposes the Parlay X 2.1 Terminal Location application interfaces.
The communication service acts as an LCS -MLS client to a location server using MLP over HTTP.
For the exact version of the standards that the Parlay X 2.1 Terminal Location/MLP communication service supports for the application-facing interfaces and the network protocols, see Services Gatekeeper Statement of Compliance.
Services Gatekeeper connects to the location server using HTTP. It always acts as a single LCS/MLS client to the location server. It can be configured to act in Standard Location or Emergency Location Immediate mode on the node level.
Using the Terminal Location communication service, an application can:
Ask for the location of one or many terminals by polling.
Ask for the distance between a specified terminal and a specified position.
Sign up to be notified when a terminal enters or leaves a specified geographical area.
Receive notifications when the terminal enters or leaves the specified geographical area.
Sign up to be notified periodically about the location of a terminal.
Receive periodic location notifications about the location of a terminal.
Note:
By default this communication service supports the Point and EllipticalArea data shapes from the MLP specification. Contact your Oracle Support representative for information on using more of the MLP data shapes.The application can specify a number of parameters concerning the nature of the notification. These include:
Requested accuracy
Accepted accuracy
Accepted response time
Maximum age of location data
Tolerance, which expresses the priority of response time versus accuracy
Minimum frequency of notifications
Duration of notifications
Maximum number of notifications
The nature of the information available as well as the accuracy of the location provided, the response times, and the frequency of notification are all dependent on the specifics of the protocol and network node used. Not all networks or protocols support all operations.
If an application directly queries Services Gatekeeper for the location of a terminal or group of terminals, Services Gatekeeper sends the request to the network node. The location information is sent back synchronously in the response to the request.
If an application registers for periodic or geographically-defined notifications, information for the application (which may or may not include the location data for one or more terminals) arrives at Services Gatekeeper from the network. The notification is passed on to the application. If the application acknowledges the reception of the notification, Services Gatekeeper acknowledges the reception of the notification to the network. If the application does not acknowledge the reception of the notification, Services Gatekeeper does not acknowledge the reception of the notification to the network.
See the discussion about understanding Parlay X 2.1 terminal location precision in Services Gatekeeper Application Developer's Guide for information on terminal location precision.
For information about the SOAP-based interface for the Parlay X 2.1 Terminal Location/MLP communication service, see the discussion about Parlay X 2.1 Part 9: Terminal Location interfaces in Services Gatekeeper Application Developer's Guide.
For information about the RESTful Audio Call interface, see the discussion of Terminal Location in Services Gatekeeper System Administrator's Guide.
The RESTful Service Short Messaging interfaces provide RESTful access to the same functionality as the SOAP-based interfaces. The internal representations are identical, and for the purposes of creating SLAs, reading CDRs, and so on, they are the same.
The Parlay X 2.1 Terminal Location/MLP communication service generates event data records (EDRs), charging data records (CDRs), alarms, and statistics to assist system administrators and developers in monitoring the service.
See "Events, Alarms, and Charging" for more information.
Table 11-1 lists IDs of the EDRs created by the Parlay X 2.1 Terminal Location/MLP communication service.
Terminal Location/MLP - specific CDRs occur under the following conditions:
When the response to a polling request (of whatever type) is successfully delivered to the application.
When a notification is received from the network.
Table 11-2 maps methods invoked from either the application or the network to the transaction types collected by the Services Gatekeeper statistics counters.
Method names for network-initiated requests are specified by the internal Services Gatekeeper name, which is not necessarily the same as the message from the network.
This section lists the parameters that can be tunneled.
Defines the MLP <name_area>
element.
Complements the existing Parlay X 2.1 functionality for startGeographicalNotification with support for named areas. The startGeographicalNotification operation is defined in theTerminalLocationNotificationManager interface.
Valid for application-initiated requests only.
When this parameter key is used to define the area, the latitude, longitude, and radius parameters provided by an application are not used.
Can be set using parameter tunneling
String
<param key="terminal_location.name_area" value="Sausalito" />
Defines the <start_time>
and <stop_time
> MLP elements.
Complements the existing Parlay X 2.1 functionality for startGeographicalNotification with support for explicit start and stop times.
Valid for application-initiated requests only.
The utc_off attribute is used in both elements.
String
The time is expressed in UTC format: yyyy-MM-ddThh:mm:ss[+|-]HH:MM using the definitions in Table 11-3.
<param key="terminal_location.start_time" value="2008-09-26T16:15:00+08:00"/> <param key="terminal_location.stop_time" value="2008-09-26T19:15:00+08:00"/>
This parameter represents a set of keys in which the prefix is terminal_location.polygon.point. and the suffix n is a number in the range of 1–15.
Defines the MLP <x>
and <y>
elements within the <coord>
element. The <coord>
elements are contained by the <LinearRing>
. The <LinearRing>
element is contained by the <outerBoundaryIs>
and <polygon>
elements.
Can be set using parameter tunneling.
Each terminal_location.polygon.point key value is expressed in the format x:y where:
x corresponds to the <x>
element
y corresponds to the <y>
element
x and y are expressed as decimal degrees.
<xparams> <param key="terminal_location.polygon.point.1" value="6.999:43.564" /> <param key="terminal_location.polygon.point.2" value="7.027:43.564" /> <param key="terminal_location.polygon.point.3" value="7.027:43.564" /> <param key="terminal_location.polygon.point.4" value="6.999:43.564" /> </xparams>
This section describes the properties and workflow for the Parlay X 2.1 Terminal Location/MLP plug-in instance.
Table 11-4 lists the technical specifications for the communication service.
Table 11-4 Properties for Parlay X 2.1 Terminal Location/MLP
Property | Description |
---|---|
Managed object in Administration Console |
To access the managed object, select domain_name, then OCSG, then server_name, then Communication Services, then plugin_instance_id, in that order. |
MBean |
Domain=com.bea.wlcp.wlng Name=wlng_nt InstanceName=same as the network protocol instance_id assigned when the plug-in instance is created Type=com.bea.wlcp.wlng.plugin.terminallocation.mlp.management.TerminalLocationMLPMBean |
Network protocol plug-in service ID |
Plugin_px21_terminal_location_mlp |
Network protocol plug-in instance ID |
The ID is assigned when the plug-in instance is created. See the discussion about configuring and managing the plug-in manager in Services Gatekeeper System Administrator's Guide. |
Supported Address Scheme |
tel |
Application-facing interfaces |
com.bea.wlcp.wlng.px21.plugin.TerminalLocationPlugin com.bea.wlcp.wlng.px21.plugin.TerminalLocationNotificationManagerPlugin com.bea.wlcp.wlng.px21.callback.TerminalLocationNotificationCallback |
Service type |
TerminalLocation |
Exposes to the service communication layer a Java representation of: |
Parlay X 2.1 Part 9: Terminal Location |
Interfaces with the network nodes using: |
MLP 3.0/3.2 |
Deployment artifact: NT EAR wlng_nt_terminal_location_px21.ear |
Plugin_px21_terminal_location_mlp.jar, px21_terminal_location_service.jar, and terminal_location_mlp.war |
Deployment artifact: AT EAR: Normal wlng_at_terminal_location_px21.ear |
px21_terminal_location.war, px21_terminal_location_callback.jar and rest_terminal_location.war |
Deployment artifact: AT EAR: SOAP Only wlng_at_terminal_location_px21_soap.ear |
px21_terminal_location.war and px21_terminal_location_callback.jar |
Following is an outline for configuring the plug-in using the Administration Console or an MBean browser.
Create one or more instances of the plug-in service. See the discussion about configuring and managing the plug-in manager in Services Gatekeeper System Administrator's Guide. Use the plug-in service ID listed in the "Properties for Parlay X 2.1 Terminal Location/MLP"section.
Using the Administration Console or an MBean browser, select the MBean for the plug-in instance. The MBean display name is the same as the plug-in instance ID given when the plug-in instance was created.
Configure the fields of the TerminalLocationMLPMBean:
characterEncoding
cleanupInterval
decimalDegreesToDMSH
maxDuration
mlpVersionSupported
mlpLocationEstimates
mlpPushAddr
mlpRequestType
mlpServerUrl
mlpSrsName
mlpVersionSupported
msidType
password
requestor
requestTimeout
serviceId
username
xmlDoctypeTagUsage
Specify heartbeat behavior. See the discussion on configuring heartbeats in Services Gatekeeper System Administrator's Guide.
Set up the routing rules to the plug-in instance. See the discussion about configuring and managing the plug-in manager in Services Gatekeeper System Administrator's Guide. Use the plug-in instance ID and address schemes listed in the "Properties for Parlay X 2.1 Terminal Location/MLP"section.
If required, create and load a node SLA. For details see defining global node and service provider group node SLAs and managing SLAs in Services Gatekeeper Portal Developer's Guide.
Provision the service provider accounts and application accounts. For information, see Services Gatekeeper Portal Developer's Guide.
For a description of the attributes and operations of the TerminalLocationMLPMBean MBean, see the "All Classes" section of Services Gatekeeper OAM Java API Reference.