JAIN(tm) SIP

Technology Compatibility Kit (TCK) Specification

Copyright - 2000 Sun Microsystems, Inc. All rights reserved.
901 San Antonio Road, Palo Alto, California 94043, U.S.A.

This product and related documentation are protected by copyright and distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product or related documentation may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any.

RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the United States Government is subject to the restrictions set forth in DFARS 252.227-7013 (c)(1)(ii) and FAR 52.227-19.

The product described in this manual may be protected by one or more U.S. patents, foreign patents, or pending applications.

TRADEMARKS

Sun, the Sun logo, Sun Microsystems, Java, Java Compatible, JavaBeans, Solaris,Write Once, Run Anywhere, JDK, Java Development Kit, and JavaStation are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and certain other countries. UNIX is a registered trademark in the United States and other countries, exclusively licensed through X/Open Company, Ltd. All other product names mentioned herein are the trademarks of their respective owners.

THIS PUBLICATION IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THE PUBLICATION. SUN MICROSYSTEMS, INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS PUBLICATION AT ANY TIME.

• 1.0 Introduction
• 2.0 Objectives and scope
• 3.0 Initial set up for TCK
• 4.0 Sending Events from Listener to Provider
• 5.0 Test Results
• 6.0 Test Cases
• 7.0 Appendix
• 8.0 Abstract

1.0 Introduction

Java APIs for the Intelligent Network (JAIN) Framework brings Service Portability and Network Convergence into the Telephony Network. JAIN encompasses a standard set of interfaces for service creation and a number of standard interfaces for service execution. This document, which is is part of the JAIN SIP 0.6 Specification, outlines the requirements of the JAIN SIP Technology Compatability Kit.

The purpose of this document is to detail the test cases, for the Technology Compatibility Kit relevant to the JAIN SIP API Protocol. The Technology Compatibility Kit (TCK) tests an implementation of the JAIN SIP interfaces for compliance with the JAIN SIP Specification. The purpose of the JAIN SIP TCK is to verify that a Java SIP implementation is compatible with the JAIN SIP API Specification. The test cases outlined in this document are based on the JAIN SIP API Specification requirements that are specific to the remit of the TCK. This document also details the initial architectural set up required for the TCK.

The TCK will have also have the ability to run against the JAIN SIP Reference Implementation (RI). The RI will emulate the functions of a SIP stack (but will not be a SIP stack) in order to verify the requirements in this specification. The intention of the RI is not to implement a SIP stack or to replace vendor SIP stacks. The purpose of the RI is to provide a means to verify that JAIN applications are compatible with their appropriate JAIN specification. The requirements for the RI are outlined in the JAIN SIP API Reference Implementation Requirements Specification document.
 
 

A test program written using JDK1.2 will be used during the tests. It is necessary to apply the following requirements as listed in the JAIN SIP Requirements Specification.

1. The JAIN SIP API specification is implemented over a JAIN compliant protocol stack or over the Reference Implementation.
2. Java Virtual Machine

3.0 Initial set up for TCK

• The TCK has a Log file which is created when you exit from the TCK. The log file can be found in the directory from where it was started. The name of the file will look simillar to this "SipReport-V0.6-20000717154751" The number at the end is Year, Month, Day of month, Hour, Min, Second. To create this report, firstly run the TCK, once this is done click the Report button, then exit the report window "TCK Output Results". Finally exit the TCK and the log file will be created.
• The TestSuite class and the JAIN Listener are supplied by the TCK.  The Listener implements the JainSipListener interface. From the TestSuite JAVA class a JAIN Listener is instantiated.
• The user shall be prompted for the path name of the JAIN SIP implementation.
• The getInstance method of the Singleton JAIN IP Factory object is invoked.
• The createJainSipStack method of the JAIN IP Factory instance is invoked.  This method returns the  JainSipStackImpl, i.e. the JAIN SIP Stack Implemenatation.
• The createProvider method of JainSipStackImpl  is invoked. It returns the Vendor's JAIN SIP Provider implementation.
• The Provider registers the Listener implementation as an Event Listener, using the addJainSipListener method of the Vendor's implementation of the JainSipProvider interface, [see Figure 3.1].

The TCK interfaces with either the Reference Implementation (RI) or a Vendor Specific Implementation of the JAIN SIP API, specifically the 'JainSipStack' interface and the 'JainSipProvider' interface.
The RI or the Vendor Specific Implementation will be refered to as the vendor throughout the document.

After the initial setup, the JAIN TCK Listener should be capable of sending and receiving Events, see Section 4.0. The TCK test cases can then be run.

4.1 Caller and callee addresses
 

Messages are sent from the Listener to the Provider and addressed to the callee.  The callee's  address is the same as the caller's address except for the user name. The TCK uses the following addresses (with the host, port and transport being determined by the first ListeningPoint of the JainSipStack implementation):

    sip:caller@<host>:<port>;transport=<transport>
    sip:callee@<host>:<port>;transport=<transport>

Therefore any messages sent from the Listener will be expected to be routed through the SIP stack and back to the same Listener (i.e. the callee).

The messages will be passed from the Listener to the JAIN SIP Provider Implementation and into the SIP stack.  These messages are considered local to the SIP stack because the destination node has the sameIP address as the SIP stack.  In effect the TCP or UDP layer of the SIP stack will recognise that the messages are local and pass the messages back up the stack to the Provider.   The messages are then routed back to the Listener. [See Figure 4.1]

Consequently as messages  travel only as far as the TCP or UDP layer before they are routed back up the SIP stack, and only one SIP stack is required in order to run the TCK test cases.
 

Figure 4.1 JAIN SIP API TCK Message routing.

4. 2 Method invocations

• The TCK Listener both creates Messages and lets the Provider create Messages via the Provider's appropriate sendXXX method.
• The manner in which the Provider's implementation handles the received Messages in order to interface with the SIP stack is the responsibility of the Vendor.
• To pass received a Message to the Listener the Provider will be required to invoke the Listener's appropriate processXXX method.
• The Listener appropriately handles the received Messages according to the test case being run.

 

As a result of the running the TCK a Test Report is produced. The TCK report includes a success status for each test. In addition a detailed execution trace will be output.

If all test cases are passed the JAIN SIP Implementation will be considered JAIN Compliant.

REQ-CR-01-01: A JAIN SIP Implementation shall be compatible after passing the TCK.

Many of the Test Cases, which are based on the JAIN SIP API specification requirements applicable to the scope of the TCK, will be effectively passed if the TCK setup architecture is adhered to and Messages can be routed successfully  from Listener to destination. However the test cases outlined will individually test all appropriate aspects of the TCK and a report will be generated.

The JAIN SIP TCK will only test a 1:1 Provider / Listener relationship. A future release of the JAIN SIP TCK may test a multiple Provider / Listener relationship.

The test cases in this section consist of a Test Case name and a reference number, Test purpose and a Test result required for a success.

The TCK Test Report [see section 5.0] will individually list results based on each test case.
 
 

Test Reference	Test Case
6.1	Stack can store stack name
6.2	Stack has at least one ListeningPoint
6.3	Stack has no Providers when created
6.4	Stack can create Provider
6.5	Stack cannot create multiple Providers using same ListeningPoint
6.6	Stack cannot create Provider with listeningPoint it does not own
6.7	Stack can remove Provider
6.8	Stack throws IllegalArgumentExceptions if null argument is passed to any of its methods
6.9	Provider has reference to its Stack
6.10	Provider has reference to its ListeningPoint
6.11	Provider can add Listener
6.12	Provider can remove Listener
6.13	Provider generates new CallIdHeaders correctly
6.14	Provider generates new CSeq numbers correctly
6.15	Provider returns Messages to Listener equal to messages Listener sent
6.16	Provider maps transaction ids to Messages correctly
6.17	Provider constructs Messages correctly
6.18	Provider handles unrecognised methods and headers
6.19	Provider throws TransactionDoesNotExistException if user refers to a non-existent transaction
6.20	Provider throws IllegalArgumentException if null argument is passed to any of its methods
6.21	Provider only sends AckMessage if success ResponseMessage has been received for corresponding InviteMessage
6.22	Provider only sends CancelMessage if no final ResponseMessage has been received for corresponding RequestMessage

Table 6.2 Test Case Index

6.1.1 Test purpose

Verify that the implementation of JainSipStack can store a stack name as given by the user.

6.1.1 Test procedure

The TCK attempts to set the stack name of the JainSipStack implementation using the setStackName method, retrieves the value using the getStackName method, and then compares the two values.

6.1.3 Test result

The test result is true if the value returned by the getStackName method is equal to the value passed to the setStackName method; false otherwise.
 
 

6.2.1 Test purpose

Verify that the implementation of JainSipStack has at least one ListeningPoint when created (since adding ListeningPoints is not allowed in the JAIN SIP API).

6.2.2 Test procedure

The TCK attempts to retrieve the ListeningPoints owned by the JainSipStack implementation by calling the getListeningPoints method.

6.2.3 Test result

The test result is true if the method returns an array of one or more ListeningPoints. The test result is false if the method throws a ListeningPointUnavailableException, or if it returns an empty array of ListeningPoints.
 

 
6.3.1 Test purpose

Verify that the implementation of JainSipStack has no JainSipProviders attached when it is created.

6.3.2 Test procedure

The TCK attempts to retrieve the JainSipStack implementation's list of JainSipProviders using the getProviders method.

6.3.3 Test result

The test result is true if the method throws a SipException, indicating that there are no JainSipProviders attached. The test result is false if a SipException is not thrown (even if the method returns an empty array of JainSipProviders).

 
6.4.1 Test purpose

Verify that the implementation of JainSipStack can create a JainSipProvider object.

6.4.2 Test procedure

The TCK attempts to create a JainSipProvider object by calling the createProvider method of the JainSipStack implementation. (The TCK uses the first ListeningPoint of the JainSipStack as the argument to the method). The TCK then attempts to retrieve the JainSipStack implementation's list of JainSipProviders using the getProviders method.

6.4.3 Test result

The test result is true if the createProvider method throws no Exception, returns a JainSipProvider, and the getProviders method returns an array of JainSipProviders containing only the JainSipProvider returned from the createProvider method. The test result is false if either method throws an Exception, if the createProvider method returns null, or if the getProviders method returns an empty array or an array containing the wrong object, or an array with more than one element.
 
 

 
6.5.1 Test purpose

Verify that the implementation of JainSipStack cannot create multiple JainSipProvider objects based on the same ListeningPoint.

6.5.2 Test procedure

The TCK attempts to create another JainSipProvider object by calling the createProvider method of the JainSipStack implementation. (The TCK uses the first ListeningPoint of the JainSipStack again as the argument to the method). The TCK then attempts to retrieve the JainSipStack implementation's list of JainSipProviders using the getProviders method.

6.5.3 Test result

The test result is only true if the createProvider method throws a ListeningPointUnavailableException and the getProviders method returns an array containing only the first JainSipProvider created. Test result is false otherwise.
 

 
6.6.1 Test purpose

Verify that the implementation of JainSipStack cannot create JainSipProvider objects based ListeningPoint it does not own.

6.6.2 Test procedure

The TCK attempts to create another JainSipProvider object by calling the createProvider method of the JainSipStack implementation. (The TCK uses a new ListeningPoint with a port one higher than the port of the first ListeningPoint of the JainSipStack as the argument to the method). The TCK then attempts to retrieve the JainSipStack implementation's list of JainSipProviders using the getProviders method.

6.6.3 Test result

The test result is only true if the createProvider method throws a ListeningPointUnavailableException and the getProviders method returns an array containing only the first JainSipProvider created. Test result is false otherwise.
 
 

 
6.7.1 Test purpose

Verify that the implementation of JainSipStack can remove a JainSipProvider object.

6.7.2 Test procedure

The TCK attempts to remove a JainSipProvider object by calling the removeProvider method of the JainSipStack implementation. (The TCK uses the first JainSipProvider created as the argument to the method). The TCK then attempts to retrieve the JainSipStack implementation's list of JainSipProviders using the getProviders method. (Note that the TCK creates another JainSipProvider based on the first ListeningPoint of the JainSipStack after this test - for use in later tests)

6.7.3 Test result

The test result is only true if the createProvider method throws no Exception and the getProviders method throws a SipException indicating there are no longer any JainSipProviders. Test result is false otherwise.

 
6.8.1 Test purpose
 

Verify that the implementation of JainSipStack throws IllegalArgumentExceptions whenever a null argument is passed to any of its methods.

6.8.2 Test procedure

The TCK calls every method of the JainSipStack implementation that takes an Object as an argument, passing null instead of an Object in each case. The TCK keeps track of the number of method calls made, and the number of IllegalArgumentExceptions thrown.

6.8.3 Test result

The test result is only true if the number of method calls equals the number of IllegalArgumentExceptions thrown. The test result is false otherwise.
 
 
 

 
6.9.1 Test purpose

Verify that the implementation of JainSipProvider maintains a reference to the JainSipStack it is associated with.

6.9.2 Test procedure

The TCK calls the getStack method of the JainSipProvider implementation and compares the result with the JainSipStack object that was used to create the JainSipProvider.

6.9.3 Test result

The test result is true only if the result of the getStack method is equal to the JainSipStack implementation used to create the JainSipProvider. The test result is false otherwise.
 
 
 

 
6.10.1 Test purpose

Verify that the implementation of JainSipProvider maintains a reference to the ListeningPoint it is associated with.

6.10.2 Test procedure
The TCK calls the getListeningPoint method of the JainSipProvider implementation and compares the result with the ListeningPoint object that was used to create the JainSipProvider.

6.10.3 Test result

The test result is true only if the result of the getListeningPoint method is equal to the ListeningPoint used to create the JainSipProvider. The test result is false otherwise.

 
6.11.1 Test purpose

Verify that the implementation of JainSipProvider can add a JainSipListener to itself.

6.11.2 Test procedure

The TCK Sender attempts to add itself as a JainSipListener to the JainSipProvider implementation using its addJainSipListener method.

6.11.3 Test result

The test result is true if no Exception is thrown by the addJainSipListener method. The test result is false otherwise.

 
6.12.1 Test purpose

Verify that the implementation of JainSipProvider can remove a JainSipListener from itself.

6.12.2 Test procedure

The TCK Sender attempts to remove itself as a JainSipListener from the JainSipProvider implementation using its removeJainSipListener method.

6.12.3 Test result

The test result is true if no Exception is thrown by the removeJainSipListener method. The test result is false otherwise.
 
 
 

 
6.13.1 Test purpose

Verify that the implementation of JainSipProvider can generate new CallIdHeaders correctly.

6.13.2 Test procedure

The TCK attempts to retrieve two new CallIdHeaders generated by the JainSipProvider implementation by calling its getNewCallIdHeader method twice consecutively and storing the results of the two calls.

6.13.3 Test result

The test result is true only if the two method calls throw no Exceptions, return two CallIdHeaders with the same host but with different local-ids, and the host is equal to the host of the JainSipProvider's ListeningPoint. The test result is false otherwise..
 
 

 
6.14.1 Test purpose

Verify that the implementation of JainSipProvider can generate new CSeq numbers correctly.

6.14.2 Test procedure

The TCK attempts to retrieve two new CSeq numbers generated by the JainSipProvider implementation by calling its getNewCSeqNumber method twice consecutively and storing the results of the two calls. (Note the first CallIdHeader generated in test 6.13 is passed as the argument to both method calls).

6.14.3 Test result

The test result is true only if the two method calls throw no Exceptions, return two positive numbers, and the second number is one greater than the first. The test result is false otherwise.
 
 

 
6.15.1 Test purpose

Verify that the implementation of JainSipProvider returns Messages to Listener that are equal to the Messages sent. This checks the implementation's construction of Messages is correct.

6.15.2 Test procedure

The TCK will keep an separate ordered lists of all sent and received Messages throughout the duration of the tests. The lists are compared after all tests have been executed.

6.15.3 Test result

The test result is true if the number of sent Messages equals the number of received Messages, and each received Message equals its corresponding sent Message. (They are compared using the equals method of the Message class). The test result is false otherwise.
 
 
 

 
6.16.1 Test purpose

Verify that the implementation of JainSipProvider maps transaction ids to Messages correctly.

6.16.2 Test procedure

The TCK constructs one of each type of Message (e.g. InviteMessage) and calls its corresponding send method (e.g. sendInvite) that takes a user-constructed Message. Then the TCK attempts to retrieve the Message associated with the transaction id returned by the send method (using get{Client|Server}Transaction{Request|Response} methods). The constructed and retrieved Messages are then compared.

6.16.3 Test result

The test result is true only if none of the method calls throw an Exception, and each constructed Message is equal to the retrieved Message. (They are compared using the equals method of the Message class). The test result is false otherwise.
 
 
 

 
6.17.1 Test purpose

Verify that the implementation of JainSipProvider constructs Messages correctly.

6.17.2 Test procedure

The TCK constructs one of each type of Message (e.g. InviteMessage) and calls its corresponding send method (e.g. sendInvite) that creates a Message automatically. Then the TCK attempts to retrieve the automaticlly constructed Message associated with the transaction id returned by the send method (using get{Client|Server}Transaction{Request|Response} methods). The user-constructed and provider-constructed Messages are then compared.

6.17.3 Test result

The test result is true only if none of the method calls throw an Exception, and each user-constructed Message is equal to the provider-constructed Message. (They are compared using the equals method of the Message class). The test result is false otherwise.
 
 

 
6.18.1 Test purpose

Verify that the implementation of JainSipProvider can handle unrecognised methods and headers. This essentially tests the implementations handling of generic Message and Header classes.

6.18.2 Test procedure

The TCK constructs three Messages as follows:

• One with recognised Headers and an unrecognised method.
• One with an unrecognised Header and a recognised method.
• One with an unrecognised Header and an unrecognised method.

The TCK then attempts to send these Messages using the appropriate send method of the JainSipProvider implementation.

6.18.3 Test result

The test result is only true if no method calls throw an Exception, and the Messages are received as sent. The test result is false otherwise.
 
 

 
6.19.1 Test purpose

Verify that the implementation of JainSipProvider throws a TransactionDoesNotExistException if a user attempts to refer to a non-existent transaction.

6.19.2 Test procedure

The TCK attempts to invoke each method on the JainSipProviderImplementation that takes either a client or server transaction id as a parameter. The TCK uses a transaction id that it knows has not been used by the JainSipProvider implementation. Since transaction ids are positive integers, a negative integer is the appropriate choice for the TCK to use as a transaction id. The TCK keeps count of the number of method calls and the number of TransactionDoesNotExistExceptions thrown.

6.19.3 Test result

The test result is true only if the number of method calls equals the number of TransactionDoesNotExistExceptions thrown. The test result is false otherwise.
 
 

 
6.20.1 Test purpose
 

Verify that the implementation of JainSipProvider throws IllegalArgumentExceptions whenever a null argument is passed to any of its methods.

6.20.2 Test procedure

The TCK calls every method of the JainSipProvider implementation that takes an Object as an argument, passing null instead of an Object in each case. The TCK keeps track of the number of method calls made, and the number of IllegalArgumentExceptions thrown.

6.20.3 Test result

The test result is only true if the number of method calls equals the number of IllegalArgumentExceptions thrown. The test result is false otherwise.
 
 

 
6.21.1 Test purpose

Verify that the implementation of JainSipProvider only sends AckMessages if a success ResponseMessage has been received for a corresponding InviteMessage.

6.21.2 Test procedure

The TCK attempts to send AckMessages in the following situations:

• A non-success ResponseMessage has been received for a corresponding InviteMessage
• A success ResponseMessage has been received for a corresponding RequestMessage that is not an InviteMessage
• A non-success ResponseMessage has been received for a corresponding RequestMessage that is not an InviteMessage
• A success ResponseMessage has been received for a corresponding InviteMessage

6.21.3 Test result

The test result is only true if a SipException is thrown in the first three sendAck method calls, and no Exception is thrown in the fourth sendAck method call. The test result is false otherwise.
 
 

 
6.22.1 Test purpose

Verify that the implementation of JainSipProvider only sends CancelMessages if a no final ResponseMessage has been received for a corresponding RequestMessage.

6.22.2 Test procedure

The TCK attempts to send CancelMessages in the following situations:

• No ResponseMessage has been received for a corresponding RequestMessage
• A provisional ResponseMessage has been received for a corresponding RequestMessage
• A final ResponseMessage has been received for a corresponding RequestMessage

6.22.3 Test result

The test result is only true if no Exception is thrown in the first two sendCancel method calls, and a SipException is thrown in the third sendCancel method call. The test result is false otherwise.
 
 

7.0 Appendix 

Abbreviations

This document details the Technology Capability Kit specification requirements for which an implementation of JAIN interfaces must pass in order to be considered compliant to the JAIN Specification. The purpose of the JAIN TCK is to verify that a Java SIP protocol implementation is compatible to the JAIN SIP Specification.