Package com.ibm.soa.parlayx21.terminal_location

Terminal Location.

See:
          Description

Interface Summary
TerminalLocation Request the location for a terminal.
TerminalLocation_RI  
TerminalLocationHome  
TerminalLocationNotification Notification interface to which notifications are delivered.
TerminalLocationNotification_RI  
TerminalLocationNotificationHome  
TerminalLocationNotificationManager Set up notifications for terminal location events using geographical based definitions.
TerminalLocationNotificationManager_RI  
TerminalLocationNotificationManagerHome  
TerminalLocationNotificationManagerService  
TerminalLocationNotificationService  
TerminalLocationService  
 

Class Summary
DelayTolerance Enumeration of the delay tolerance items that forms part of the location request.
EnteringLeavingCriteria Indicator for whether the notification is related to entering an area or leaving an area.
LocationData Data structure containing device address, retrieval status and location information.
LocationData_Deser  
LocationData_Helper  
LocationData_Ser  
LocationInfo Location information represented as a coordinate.
LocationInfo_Deser  
LocationInfo_Helper  
LocationInfo_Ser  
RetrievalStatus Enumeration of the location items that are related to an individual retrieval in a set.
TerminalLocationBindingStub  
TerminalLocationNotificationBindingStub  
TerminalLocationNotificationManagerBindingStub  
TerminalLocationNotificationManagerProxy  
TerminalLocationNotificationManagerServiceInformation  
TerminalLocationNotificationManagerServiceLocator  
TerminalLocationNotificationProxy  
TerminalLocationNotificationServiceInformation  
TerminalLocationNotificationServiceLocator  
TerminalLocationProxy  
TerminalLocationServiceInformation  
TerminalLocationServiceLocator  
 

Package com.ibm.soa.parlayx21.terminal_location Description

Terminal Location.

Common Data Types

For common data types associated with this package see Common Data Types.

Scope

The present document is part 9 of the Stage 3 Parlay X 2 Web Services specification for Open Service Access (OSA).

The OSA specifications define an architecture that enables application developers to make use of network functionality through an open standardized interface, for example, the OSA APIs.

The present document specifies the Terminal Location Web Service. The following are defined here:
  * Name spaces.
  * Sequence diagrams.
  * Data definitions.
  * Interface specification plus detailed method descriptions.
  * Fault definitions.
  * Service Policies.
  * WSDL Description of the interfaces.

References

The following documents contain provisions which, through reference in this text, constitute provisions of the present document.
  * References are either specific (identified by date of publication and/or edition number or version number) or nonspecific.
  * For a specific reference, subsequent revisions do not apply.
  * For a non-specific reference, the latest version applies.

Referenced documents which are not found to be publicly available in the expected location might be found at http://docbox.etsi.org/Reference.

[1] W3C Recommendation (2 May 2001): "XML Schema Part 2: Datatypes".

NOTE: Available at http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/.

[2] ETSI ES 202 391-1: "Open Service Access (OSA); Parlay X 2 Web Services; Part 1: Common".

[3] ISO 6709: "Standard representation of latitude, longitude and altitude for geographic point locations".

Definitions and abbreviations

Definitions

For the purposes of the present document, the terms and definitions given in ES 202 391-1 [2] apply.

Abbreviations

For the purposes of the present document, the abbreviations defined in ES 202 391-1 [2] apply.

Detailed service description

Terminal Location provides access to the location of a terminal through:
  * Request for the location of a terminal.
  * Request for the location of a group of terminals.
  * Notification of a change in the location of a terminal.
  * Notification of terminal location on a periodic basis.
  * Location is expressed through a latitude, longitude, altitude and accuracy.

When a request for a group of terminals is made, the response may contain a full or partial set of results. This allows the service to provide results based on a number of criteria including number of terminals for which the request is made and amount of time required to retrieve the information. This allows the requester to initiate additional requests for those terminals for which information was not provided.

Namespaces

The Terminal Location interface uses the namespace: http://www.csapi.org/wsdl/parlayx/terminal_location/v2_12

The TerminalLocationNotificationManager interface uses the namespace: http://www.csapi.org/wsdl/parlayx/terminal_location/notification_manager/v2_23

The TerminalLocationNotification interface uses the namespace: http://www.csapi.org/wsdl/parlayx/terminal_location/notification/v2_12

The data types are defined in the namespace: http://www.csapi.org/schema/parlayx/terminal_location/v2_12

The 'xsd' namespace is used in the present document to refer to the XML Schema data types defined in XML Schema [1]. The use of the name 'xsd' is not semantically significant.

Sequence diagrams

Terminal location query

Pattern: Request / Response.

For an application to determine the location of a terminal device, it provides a terminal device address and desired accuracy, and receives the location for the device requested.

Figure 1

Terminal location group query

Pattern: Request / Response.

When an application requires the locations of a set of terminal devices, it may provide an array of terminal device addresses, including network managed group addresses, and receive the location data for the set of devices requested.

Figure 2

Terminal location notification

Pattern: Application Correlated Multiple Notification.

An application can be notified of a terminal device entering or leaving a geographical area. When a matching event occurs; a notification message will be sent to the application.

Figure 3

Terminal location notification with check immediate

In some applications, the terminal location notification will be used to watch for a specific location change. An example is a 'call when present' service, where the terminal location is checked and determined to be outside the target area, and a notification is set up to notify the application when the terminal enters the target area. Between the time of the original location determination and the time the notification is set up, the terminal could move into the target area, thus the notification on entry into the target area would not be sent.

Using the check immediate flag, after the notification is established, the terminal location will be determined, and if the terminal is in the target area, then a notification will be sent immediately. The following sequence diagram shows this scenario.

Figure 4

This sequence shows:
  * The Enterprise Application checks the location of a terminal, and receives its location (in this scenario determining that the terminal is outside the target area).
  * The Enterprise Application generates a correlator, and starts a notification with criteria defined to notify the Enterprise Web Service when the terminal enters the target area and the check immediate flag set to true.
  * Sets up the notification to monitor terminal location.
  * Check the current location of the terminal, and determine if the terminal lies inside the target area.
  * In this case, the terminal is in the target area, and a notification is delivered to the Enterprise Web Service.
  * The count of notifications is incremented and compared to the notification count limit.
  * In this case, a single notification was requested, and the end notification message is sent.
  * The startGeographicalNotification operation completes.

This scenario includes the full set of interactions in one sequence, which also shows that the notifications can be received concurrent with the creation of the notification.

Terminal location periodic notification

Pattern: Application Correlated Multiple Notification.

An application can be notified of a terminal device location on a periodic basis. At each interval, a notification message will be sent to the application.

Figure 5

XML Schema data type definition

Latitude and Longitude values

Latitude and longitude values used in the present document follow the conventions of the ISO 6709 [3] specification, as it applies to latitudes and longitudes specified using decimal degrees.

Latitude values are expressed as floating point numbers in the range -90,0000 to +90,0000, using decimal degrees (as opposed to minutes and seconds). Positive values indicate locations north of and on the equator. Negative values indicate locations south of the equator.

Longitude values are expressed as floating point numbers in the range -180,0000 to +180,0000, using decimal degrees (as opposed to minutes and seconds). Positive values indicate locations east of and on the prime meridian (Greenwich). Negative values indicate locations west of the prime meridian up to the 180th meridian.

Accuracy values

Two accuracy values are used in some of the operations. These values express the desire of the application for the location information to be provided by the Web Service. The choice of values may influence the price that the Service Provider charges.
  * The 'requested accuracy' expresses the range in 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 1 000 meters, but GPS technology may be required for requests below 100 meters).
  * The 'acceptable accuracy' expresses the range that the application considers useful, if the location cannot be determined within this range, then the application would prefer not to receive the information. For instance, a taxi tracking service to determine the closest taxi to a person may not be useful if the accuracy cannot be provided within 1 000 meters to provide prompt service. This will also reduce customer satisfaction issues, since results that are not useful can be handled appropriately for billing (for example, Service Provider may choose not to bill for these).

The ‘maximum_age’ expresses the maximum age of location information that the application considers useful. This can be used by the service provider to supply cached location information rather than always to do a direct network location request.

The ‘response time’ expresses the expected response time from an application point of view. If the network is unable to respond within the desired time frame, the application would prefer not to have the information as it may no longer be useful.

The ‘tolerance’ expresses the priority of response time versus accuracy. If the application is delay tolerant the network is expected to return a location with the requested accuracy even if this means not complying with the requested response time. The application can also indicate that it is more important that the location information is returned within the requested time even if this implies that the requested accuracy can not be fulfilled. An indication of ‘no delay’ implies that the application expects the service provider to return any current location estimate immediately.

In triggered notifications, a tracking accuracy is defined. This accuracy refers not to the accuracy for the area being checked against, but rather for the accuracy of the technology used to track the terminal. For instance, a fine grained tracking accuracy would be suitable for tracking the terminal entering a specific location, like a person arriving at a destination building. A coarse grained tracking accuracy would be appropriate for determining when a person has arrived at a city after a plane trip or a truck is in the vicinity of a warehouse.

EnteringLeavingCriteria enumeration

Indicator for whether the notification is related to entering an area or leaving an area.


Entering Terminal is entering an area
Leaving Terminal is leaving an area

LocationInfo structure

Location information represented as a coordinate.


address xsd:anyURI

Address of the terminal device to which the location information applies
latitude xsd:float

Location latitude
longitude xsd:float

Location longitude
altitude xsd:float

Location altitude
accuracy xsd:int

Accuracy of location provided in meters
timestamp xsd:dateTime

Date and time that location was collected

RetrievalStatus enumeration

Enumeration of the location items that are related to an individual retrieval in a set.


Retrieved Location retrieved, with result in currentLocation element
NotRetrieved Location not retrieved, currentLocation is not provided (does not indicate an error, no attempt may have been made)
Error Error retrieving location

LocationData structure

Data structure containing device address, retrieval status and location information. As this can be related to a query of a group of terminal devices, the reportStatus element is used to indicate whether the information for the device was retrieved or not, or if an error occurred.


address xsd:anyURI

Address of the terminal device to which the location information applies
reportStatus RetrievalStatus

Status of retrieval for this terminal device address
currentLocation LocationInfo NoYes

Location of terminal. It is only provided if reportStatus=Retrieved.
errorInformation common:ServiceError

If reportStatus=Errorreport status is error, this is the reason for the error. Error due to privacy verification will be expressed as POL0002 in the ServiceError

DelayTolerance enumeration

Enumeration of the delay tolerance items that forms part of the location request.


NoDelay

The server should immediately return any location estimate that it currently has. If no estimate is available, the server shall return the failure indication and may optionally initiate procedures to obtain a location estimate (for example, to be available for a later request).
LowDelay

Fulfillment of the response time requirement takes precedence over fulfillment of the accuracy requirement. The server shall return any current location estimate with minimum delay. The server shall attempt to fulfill any accuracy requirement, but in doing so shall not add any additional delay (for example, a quick response with lower accuracy is more desirable than waiting for a more accurate response).
DelayTolerant

Fulfillment of the accuracy requirement takes precedence over fulfillment of the response time requirement. If necessary, the server should delay providing a response until the accuracy requirement of the requesting application is met. The server shall obtain a current location with regard to fulfilling the accuracy requirement.

Web Service interface definition

Fault definitions

ServiceException

SVC0200: Accuracy out of limit


messageId SVC0200
text Accuracy of location is not within acceptable limit
variables None

PolicyException

POL0230: Requested accuracy not supported


messageId POL0230
text Requested accuracy is not supported
variables None

POL0231: Geographic notification not available


messageId POL0231
text Geographic notification is not available
variables None

POL0232: Periodic notification not available


messageId POL0232
text Periodic notification is not available
variables None

Service policies

Service policies for this service.


MinimumAccuracy xsd:int Minimum value for requested accuracy
MinimumAcceptableAccuracy xsd:int Minimum value for acceptable accuracy
MinimumTrackingAccuracy xsd:int Minimum value for tracking accuracy
GeographicalNotificationAvailable xsd:boolean Can notifications be set on a geography
PeriodicNotificationAvailable xsd:boolean Can a periodic notification be set up
AltitudeAlwaysAvailable xsd:boolean Is altitude available for all location responses
AltitudeSometimesAvailable xsd:boolean Is altitude available for some or all location responses (if AltitudeAlwaysAvailable is true, this is also true)
MaximumNotificationAddresses xsd:int Maximum number of addresses for which a notification can be set up
MaximumNotificationFrequency common:TimeMetric Maximum rate of notification delivery (also can be considered minimum time between notifications)
MaximumNotificationDuration common:TimeMetric Maximum amount of time for which a notification can be set up
MaximumCount xsd:int Maximum number of notifications that may be requested
UnlimitedCountAllowed xsd:boolean Allowed to specify unlimited notification count (for example, either by not specifying the optional count message part in startGeographicalNotificationRequest or by specifying a value of zero in notification count requested)
GroupSupport xsd:boolean Groups URIs may be used
NestedGroupSupport xsd:boolean Are nested groups supported in group definitions



Copyright © 2003 IBM Corp. All Rights Reserved.