com.ibm.soa.parlayx21.terminal_location
Interface TerminalLocationNotificationManager

All Superinterfaces:
java.rmi.Remote
All Known Subinterfaces:
TerminalLocationNotificationManager_RI
All Known Implementing Classes:
TerminalLocationNotificationManagerBindingStub, TerminalLocationNotificationManagerProxy

public interface TerminalLocationNotificationManager
extends java.rmi.Remote

Set up notifications for terminal location events using geographical based definitions.


Method Summary
 void endNotification(java.lang.String correlator)
          The application may end a notification (either type) using this operation.
 void startGeographicalNotification(SimpleReference reference, java.net.URI[] addresses, float latitude, float longitude, float radius, float trackingAccuracy, EnteringLeavingCriteria criteria, boolean checkImmediate, TimeMetric frequency, TimeMetric duration, java.lang.Integer count)
          Notifications of location changes are made available to applications.
 void startPeriodicNotification(SimpleReference reference, java.net.URI[] addresses, int requestedAccuracy, TimeMetric frequency, TimeMetric duration)
          Periodic notifications provide location information for a set of terminals at an application defined interval.
 

Method Detail

startGeographicalNotification

void startGeographicalNotification(SimpleReference reference,
                                   java.net.URI[] addresses,
                                   float latitude,
                                   float longitude,
                                   float radius,
                                   float trackingAccuracy,
                                   EnteringLeavingCriteria criteria,
                                   boolean checkImmediate,
                                   TimeMetric frequency,
                                   TimeMetric duration,
                                   java.lang.Integer count)
                                   throws java.rmi.RemoteException,
                                          PolicyException,
                                          ServiceException

Notifications of location changes are made available to applications. The number and duration of notifications may be requested as part of the setup of the notification or may be governed by service policies, or a combination of the two.

If checkImmediate is set to true, then the notification will be set up, and then the current value of the terminal location will be checked. If the terminal location is within the radius provided and the criteria is Entering or is outside the radius and the criteria is Leaving, a notification will be sent to the application. This notification will count against the count requested. This addresses the case where the location of the device changes during the time the notification is being set up, which may be appropriate in some applications.

The correlator provided in the reference must be unique for this Web Service at the time the notification is initiated, otherwise a fault (SVC0005) will be returned to the application.

If the frequency requested is more often than allowed by the service policy, then the value in the service policy will be used. If the duration requested exceeds the time allowed in the service policy, then the value in the service policy will be used. If the notification period (duration) ends before all of the notifications (count) have been delivered, then the notification terminates. In all cases, when the notifications have run their course (by duration or count), an end of notifications message will be provided to the application.

Service policies may govern what count values can be requested, including maximum number of notifications allowed and whether unlimited notifications can be requested (for example, either by not specifying the optional count message part or by specifying it with a value a count of zero). If the count value provided requested is not in policy, a fault (POL0004 or POL0005 as appropriate) will be returned.

The criteria will be met when the terminal enters the area defined as the circle of the radius provided around the point provided (latitude, longitude). The trackingAccuracy provided will determine how fine grained is the determination of where the terminal is located. A trackingAccuracy with a high value (coarse grained tracking) may result in more or less notifications (false or missed notifications) than actual entries and exits from the area defined.

Service policies govern what values can be provided for trackingAccuracy, including a minimum number (in meters) that can be requested. If the value provided is not within policy, a fault (POL0230) will be returned.

Referenced faults

ServiceException from ES 202 391-1 [2]:
  * SVC0001: Service error.
  * SVC0002: Invalid input value.
  * SVC0004: No valid addresses.
  * SVC0005: Duplicate correlator.
  * SVC0006: Invalid group.

PolicyException from ES 202 391-1 [2]:
  * POL0001: Policy error.
  * POL0003: Too many addresses.
  * POL0004: Unlimited notifications not supported.
  * POL0005: Too many notifications requested.
  * POL0006: Groups not allowed.
  * POL0007: Nested groups not allowed.
  * POL0009: Invalid frequency requested.
  * POL0230: Requested accuracy not available
  * POL0231: Geographic notification not available.

Parameters:
reference -

common: SimpleReference Notification endpoint definition

addresses - xsd:anyURI [0..unbounded] Addresses of terminals to monitor
latitude - xsd:float Latitude of centre point
longitude - xsd:float Longitude of centre point
radius - xsd:float Radius of circle around centre point in meters
trackingAccuracy - xsd:float Number of meters of acceptable error in tracking distance
criteria - EnteringLeavingCriteria Indicates whether the notification should occur when the terminal enters or leaves the target area
checkImmediate - xsd:boolean Check location immediately after establishing notification
frequency - common:TimeMetric Maximum frequency of notifications (can also be considered minimum time between notifications)
duration - common:TimeMetric Length of time notifications occur for, do not specify to use default notification time defined by service policy
count - xsd:int

Maximum number of notifications., do not specify f For no maximum, either do not specify this part or specify a value of zero.

Throws:
java.rmi.RemoteException
PolicyException
ServiceException

startPeriodicNotification

void startPeriodicNotification(SimpleReference reference,
                               java.net.URI[] addresses,
                               int requestedAccuracy,
                               TimeMetric frequency,
                               TimeMetric duration)
                               throws java.rmi.RemoteException,
                                      PolicyException,
                                      ServiceException

Periodic notifications provide location information for a set of terminals at an application defined interval. The accuracy requested is the desired accuracy for the response. If the accuracy requested is not supported, a fault (POL0230) will be returned to the application.

Referenced faults

ServiceException from ES 202 391-1 [2]:
  * SVC0001: Service error.
  * SVC0002: Invalid input value.
  * SVC0004: No valid addresses.
  * SVC0005: Duplicate correlator.
  * SVC0006: Invalid group.

PolicyException from ES 202 391-1 [2]:
  * POL0001: Policy error.
  * POL0003: Too many addresses.
  * POL0006: Groups not allowed.
  * POL0007: Nested groups not allowed.
  * POL0009: Invalid frequency requested.
  * POL0230: Requested accuracy not available.
  * POL0232: Periodic notification not available.

Parameters:
reference - common: SimpleReference Notification endpoint definition
addresses - xsd:anyURI [1..unbounded] Addresses of terminals to monitor
requestedAccuracy - xsd:int Accuracy of location requested in meters
frequency - common:TimeMetric Maximum frequency of notifications (can also be considered minimum time between notifications)
duration - common:TimeMetric Length of time notifications occur for, do not specify to use default notification time defined by service policy
Throws:
java.rmi.RemoteException
PolicyException
ServiceException

endNotification

void endNotification(java.lang.String correlator)
                     throws java.rmi.RemoteException,
                            PolicyException,
                            ServiceException

The application may end a notification (either type) using this operation.

Until this operation returns, notifications may continue to be received by the application.

An end of notification (LocationEndRequest) message will not be delivered to the application for a notification ended using this operation.

Referenced faults

ServiceException from ES 202 391-1 [2]:
  * SVC0001: Service error.
  * SVC0002: Invalid input value.

PolicyException from ES 202 391-1 [2]:
  * POL0001: Policy error.

Parameters:
correlator - xsd:string Correlator of request to end
Throws:
java.rmi.RemoteException
PolicyException
ServiceException


Copyright © 2003 IBM Corp. All Rights Reserved.