Package com.ibm.soa.parlayx21.terminal_status

Terminal Status.

See:
          Description

Interface Summary
TerminalStatus Request the status for a terminal or set of terminals.
TerminalStatus_RI  
TerminalStatusHome  
TerminalStatusNotification Notification interface to which notifications are delivered.
TerminalStatusNotification_RI  
TerminalStatusNotificationHome  
TerminalStatusNotificationManager Set up notifications for terminal status changes.
TerminalStatusNotificationManager_RI  
TerminalStatusNotificationManagerHome  
TerminalStatusNotificationManagerService  
TerminalStatusNotificationService  
TerminalStatusService  
 

Class Summary
RetrievalStatus Enumeration of the status items that are related to an individual retrieval in a set.
Status List of possible status values.
StatusData Data structure containing device identifier and its status.
StatusData_Deser  
StatusData_Helper  
StatusData_Ser  
StatusInformation A simplified terminal status data structure used in the TerminalNotification interface.
StatusInformation_Deser  
StatusInformation_Helper  
StatusInformation_Ser  
TerminalStatusBindingStub  
TerminalStatusNotificationBindingStub  
TerminalStatusNotificationManagerBindingStub  
TerminalStatusNotificationManagerProxy  
TerminalStatusNotificationManagerServiceInformation  
TerminalStatusNotificationManagerServiceLocator  
TerminalStatusNotificationProxy  
TerminalStatusNotificationServiceInformation  
TerminalStatusNotificationServiceLocator  
TerminalStatusProxy  
TerminalStatusServiceInformation  
TerminalStatusServiceLocator  
 

Package com.ibm.soa.parlayx21.terminal_status Description

Terminal Status.

Common Data Types

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

Scope

The present document is part 8 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 Status 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".

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 Status provides access to the status of a terminal through:
  * Request for the status of a terminal.
  * Request for the status of a group of terminals.
  * Notification of a change in the status of a terminal.

The status of a terminal can be expressed as reachable, unreachable or busy - however not all terminals distinguish a busy status, so applications should be able to adapt to what information is available (using the service properties to determine available information).

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 TerminalStatus interface uses the namespace: http://www.csapi.org/wsdl/parlayx/terminal_status/v2_12

The TerminalStatusNotificationManager interface uses the namespace: http://www.csapi.org/wsdl/parlayx/terminal_status/notification_manager/v2_12

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

The data types are defined in the namespace: http://www.csapi.org/schema/parlayx/terminal_status/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 status query

Pattern: Request / Response.

When an application is interested in determining the status of a terminal device, it may provide a terminal device address, and receive the status for the device requested.

Figure 1

Terminal status group query

Pattern: Request / Response.

When an application is interested in determining the status of a set of terminal devices, it may provide an array of terminal device addresses, including network managed group addresses, and receive the status for the set of devices requested.

Figure 2

Terminal status notification

Pattern: Application Correlated Multiple Notification.

An application can be notified of a change in the status of terminal devices. When the status of a terminal device changes, a notification message will be sent to the application.

Figure 3

Terminal Status Notification with Check Immediate

In some applications, the terminal status notification will be used to watch for a specific status change. An example is a 'call when available' service, where the terminal status is checked and determined to be not reachable or busy, and a notification is set up to notify the application when the terminal becomes reachable. Between the time that the original status determination and the time the notification is set up, the terminal status could change to reachable, thus the notification on change to reachable would not be sent.

Using the check immediate flag, after the notification is established, the value of the terminal status will be determined, and if the criteria is matched then a notification will be sent immediately. The following sequence diagram shows this scenario.

Figure 4

This sequence shows:
  * The Enterprise Application checks the status of a terminal, and receives its status (in this scenario receiving Unreachable or Busy).
  * The Enterprise Application generates a correlator, and starts a notification with criteria defined to notify the Enterprise Web Service when the terminal state becomes Reachable and the check immediate flag set to true.
  * Sets up the notification to monitor terminal status changes.
  * Check the current status of the terminal, and determine if the status matches the criteria.
  * In this case, the criteria matches, 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 startNotification 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.

XML Schema data type definition

Status enumeration

List of possible status values.


Reachable Terminal is reachable
Unreachable Terminal is not reachable
Busy Terminal is busy

RetrievalStatus enumeration

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


Retrieved Status retrieved, with result in currentStatus element
NotRetrieved Status not retrieved, currentStatus is not provided (does not indicate an error, no attempt may have been made)
Error Error retrieving status.

StatusData structure

Data structure containing device identifier and its status. 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 status information applies
reportStatus RetrievalStatus

Status of retrieval for this address
currentStatus Status NoYes

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

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

StatusInformation structure

A simplified terminal status data structure used in the TerminalNotification interface.


address xsd:anyURI

Address of the terminal device to which the status information applies.
currentStatus Status

Status of terminal.

Web Service interface definition

Referenced faults

None.

Fault definitions

PolicyException

POL0200: Busy criteria not supported


messageId POL0200
text Busy criteria is not supported
variables None

Service policies

Service policies for this service.


BusyAvailable xsd:boolean Can busy be returned as a status or be a trigger
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)
MaximumNotification Duration common:TimeMetric Maximum amount of time a notification may be set up for
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 part in the startNotificationRequest message or by specifying a value of zerospecify zero in notification count requested)
GroupSupport xsd:boolean Groups may be included with addresses
NestedGroupSupport xsd:boolean Are nested groups supported in group definitions



Copyright © 2003 IBM Corp. All Rights Reserved.