com.ibm.soa.parlayx21.terminal_location
Interface TerminalLocation

All Superinterfaces:
java.rmi.Remote
All Known Subinterfaces:
TerminalLocation_RI
All Known Implementing Classes:
TerminalLocationBindingStub, TerminalLocationProxy

public interface TerminalLocation
extends java.rmi.Remote

Request the location for a terminal.


Method Summary
 LocationInfo getLocation(java.net.URI address, int requestedAccuracy, int acceptableAccuracy, TimeMetric maximumAge, TimeMetric responseTime, DelayTolerance tolerance)
          This operation is intended to retrieve the location for a single terminal.
 LocationData[] getLocationForGroup(java.net.URI[] addresses, int requestedAccuracy, int acceptableAccuracy, TimeMetric maximumAge, TimeMetric responseTime, DelayTolerance tolerance)
          The getLocationForGroup operation initiates a retrieval activity, where one or more terminals, or groups of terminals, may have their locations determined.
 int getTerminalDistance(java.net.URI address, float latitude, float longitude)
          This operation is intended to determine the distance of a terminal from a location.
 

Method Detail

getLocation

LocationInfo getLocation(java.net.URI address,
                         int requestedAccuracy,
                         int acceptableAccuracy,
                         TimeMetric maximumAge,
                         TimeMetric responseTime,
                         DelayTolerance tolerance)
                         throws java.rmi.RemoteException,
                                PolicyException,
                                ServiceException

This operation is intended to retrieve the location for a single terminal. The accuracy requested is the desired accuracy for the response. The acceptable accuracy is the limit acceptable to the requester. If the accuracy requested cannot be supported, a fault (POL0230) will be returned to the application. If the accuracy of the location is not within the acceptable accuracy limit, then the location will not be returned, instead a fault (SVC0200) will be returned. The URI provided is for a single terminal, not a group URI. If a group URI is provided, a fault will be returned to the application.

If tolerance is indicated this affects the priority of accuracy, response time and maximum acceptable age.

Referenced faults

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

PolicyException from ES 202 391-1 [2]:
  * POL0001: Policy error.
  * POL0002: Privacy error.
  * POL0006: Groups not allowed.
  * POL0230: Requested accuracy not supported.

Parameters:
address - xsd:anyURI Address of the terminal device for which the location information is requested
requestedAccuracy - xsd:int Accuracy of location information requested
acceptableAccuracy - xsd:int Accuracy that is acceptable for a response
maximumAge - common:TimeMetric Maximum acceptable age of the location information that is returned
responseTime - common:TimeMetric Indicates the maximum time that the application can accept to wait for a response
tolerance - DelayTolerance Indicates the priority of response time versus accuracy
Returns:
result LocationInfo Location of the terminal for which location information was requested
Throws:
java.rmi.RemoteException
PolicyException
ServiceException

getTerminalDistance

int getTerminalDistance(java.net.URI address,
                        float latitude,
                        float longitude)
                        throws java.rmi.RemoteException,
                               PolicyException,
                               ServiceException

This operation is intended to determine the distance of a terminal from a location. The URI provided is for a single terminal, not a group URI. If a group URI is provided, a fault will be returned to the application.

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.
  * POL0002: Privacy error.
  * POL0006: Groups not allowed.

Parameters:
address - xsd:anyURI Address of terminal to check
latitude - xsd:float Latitude of the location to measure from
longitude - xsd:float Longitude of the location to measure from
Returns:
result xsd:int Distance from terminal to the location specified in meters

Throws:
java.rmi.RemoteException
PolicyException
ServiceException

getLocationForGroup

LocationData[] getLocationForGroup(java.net.URI[] addresses,
                                   int requestedAccuracy,
                                   int acceptableAccuracy,
                                   TimeMetric maximumAge,
                                   TimeMetric responseTime,
                                   DelayTolerance tolerance)
                                   throws java.rmi.RemoteException,
                                          PolicyException,
                                          ServiceException

The getLocationForGroup operation initiates a retrieval activity, where one or more terminals, or groups of terminals, may have their locations determined. 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. If the location retrieved is not within the acceptable accuracy limit, then the location data will contain a ServiceError (SVC0200).

If tolerance is indicated this affects the priority of accuracy, response time and maximum acceptable age.

The Web Service may return a result set that does not include complete information, allowing the Web Service implementation to choose to deliver a partial set of results to accommodate other conditions, such as avoiding timeouts. In this case, a result will be marked NotRetrieved for each address for which a location retrieval was not attempted.

Referenced faults

ServiceException from ES 202 391-1 [2]:
  * SVC0001: Service error.
  * SVC0002: Invalid input value.
  * SVC0004: No valid addresses.
  * 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.
  * POL0230: Requested accuracy not supported.

Parameters:
addresses - xsd:anyURI [1..unbounded] List of URIs to get location for, including group URIs
requestedAccuracy - xsd:int Accuracy of location requested in meters
acceptableAccuracy - xsd:int Accuracy that is acceptable for a response in meters
maximumAge - common:TimeMetric Maximum acceptable age of the location information that is returned
responseTime - common:TimeMetric Indicates the maximum time that the application can accept to wait for a response
tolerance - DelayTolerance Indicates the priority of response time versus accuracy
Returns:
result LocationData [1..unbounded] Set of results for the request
Throws:
java.rmi.RemoteException
PolicyException
ServiceException


Copyright © 2003 IBM Corp. All Rights Reserved.