From OpenTTCN DocZone

OpenTTCN DocZone   Home | Developer's corner | Knowledge base | Working documents | Documentation | Tutorials | Training | How do I | Frequently asked questions | Technical support

Article's permanent URL

Creating simple TCI-TM application with SDK for Java

---

In this article we provide a short overview of the example TCI-TM application included into OpenTTCN SDK for Java distribution. While the example itself is quite self-descriptive, here we underline the basic principles behind its operation.

The example itself can be found in the examples\tcitm folder of the OpenTTCN SDK for Java distribution. Its full version can also be downloaded here.

Prerequisites

In order to try the example TCI-TM application you need to have an already existing test session containing a precompiled test suite. If you want to run a test case, you may also need to have an adapter up and running for the session in question.

OpenTTCN SDK for Java contains another example that can be used for this purpose. It is located in the examples\hello folder of the distribution.

Compiling example

Go to the examples\tcitm folder in the OpenTTCN SDK for Java distribution and type:

compile_tcitm.bat

You might need to adjust path settings in the script if you run it from your own directory.

Running example

Go to the examples\tcitm folder in the OpenTTCN SDK for Java distribution and type:

run_tcitm.bat

It will display you the list of options available for running the example, together with examples of their use.

You might need to adjust path settings in the script if you run it from your own directory.

TCI-TM example structure

The example source code consists of two Java files, Main.java and TciTMProvided.java.

Main.java contains all control logic of the application, like selecting a test session, introspecting session content and running test cases.

TciTMProvided.java contains a collection of mandatory callback handlers that handle notification events like log event arrival, notification of start and stop of a test case, request to provision a module parameter etc.

TCI-TM example explained

Initializing TCI-TM engine

The TCI-TM engine must be initialized before anything else can be done in the TCI-TM application:

StartHere.initialize();

StartHereTM.setCallbackHandler(new TciTMProvided());

Here TciTMProvided is our own TCI-TM callback handler that we have developed for this example. It is registered in the SDK using setCallbackHandler() function call.

Obtaining TCI-TM request server

Next we can acquire a reference to the TCI-TM request server singleton. It provides an implementation of all so-called TCI-TM "required" operations, what in practice means all operations served by the SDK / TE upon SDK user request:

org.etsi.ttcn.tci.TciTMRequired req =
    com.openttcn.sdk.tci.StartHereTM.getRequestServer();

Using the acquired request server we can do many things. We can browse session content or run test cases. But before we are able to do this, we need to select an OpenTTCN test session which we are going to work with.

Selecting active test session

((com.openttcn.sdk.tci.TciTMRequired) req).selectSession(sessionName);

Everything what we do next we will be doing within the scope of the selected session. Only one session can be selected at a time. You can select another session by calling this same operation with another session name.

Starting a test case

req.tciStartTestCase(tcName, parList);

Here req is the TCI-TM request server we obtained earlier, tcName is a test case name, and parList is the test case parameter list that can be null or empty. Note that tciStartTestCase() has non-blocking semantics, i.e. it does not block until the test case execution is complete. So we may have to wait until the tciTestCaseTerminated() callback is called in our TciTMProvided instance to indicate end of the test case.

Processing test log events

Our TciTMProvided.java contains the following implementation of the tciLog() callback operation. It is called by the SDK in the background whenever a new test log event arrives from the test execution. A test log event typically corresponds to a single TTCN-3 statement.

public void tciLog(
    org.etsi.ttcn.tri.TriComponentId testComponentId,
    String message) {

    try {

        java.io.PrintStream out =
            new java.io.PrintStream(System.out, true, "UTF-8");

        out.println(message);
    }
    catch (java.io.UnsupportedEncodingException e) {

        com.openttcn.sdk.core.CAPI.instance().
            otReportError("tciLog(): UnsupportedEncodingException.");
    }
}

Note that we could have simply had the following in the main body of our callback implementation as the only one statement:

System.out.println(message);

The purpose of our a bit more complex implementation is to output unicode characters to the terminal window correctly. Our implementation outputs them directly in UTF-8 encoding. The simplified variant, that is conventional System.out.println(...), would have output question marks in place of those unicode characters that are outside of the Basic Latin charset.

Catching other log-related events

Our TciTMProvided.java also contains other callback notification handlers that are related to log processing. It is left as an exercise to the reader to analyze the implementation details in the full source version:

public void tciTestCaseStarted(
    org.etsi.ttcn.tci.TciTestCaseId testCaseId,
    org.etsi.ttcn.tci.TciParameterList parameterList,
    Float timer) {

    ...
}

public void tciTestCaseTerminated(
    org.etsi.ttcn.tci.VerdictValue verdict,
    org.etsi.ttcn.tci.TciParameterList parameterList) {

    ...
}

public void tciControlTerminated() {

    ...
}

Running control part

req.tciStartControl();

Here req is the TCI-TM request server we obtained earlier. Note that tciStartControl() has non-blocking semantics, i.e. it does not block until control part execution is complete. So we may have to wait until the tciControlTerminated() callback is called in our TciTMProvided instance to indicate end of the control part execution.

Provisioning module parameters

Our example disables default TCI-TM module parameters provisioning mechanism for simplicity. It does so by setting FLAG_USE_PARAMETERS_FROM_REPOSITORY in Main.main():

((com.openttcn.sdk.tci.TciTMRequired) req).setFlags(
    com.openttcn.sdk.tci.TciTMRequired.FLAG_USE_PARAMETERS_FROM_REPOSITORY);

This forces the test execution to use OpenTTCN parameter repository as a primary source of module parameters rather than default TCI-TM supply mechanism.

Normally, the TCI-TM entity is responsible also for providing module parameters to the test execution on demand. This is done by implementing the tciGetModulePar() callback handler in the TciTMProvided class:

public org.etsi.ttcn.tci.Value tciGetModulePar(
    org.etsi.ttcn.tci.TciModuleParameterId parameterId) {

    ...
}

It is left as an exercise to the reader to analyze the implementation details of this callback handler in the full source version.

Using browsing capabilities

It is possible to get a list of module parameter declarations, list of test cases and individual test case descriptors for the currently selected session using standard TCI-TM browsing capabilities. It is also possible to get the list of test sessions. Here are relevant excerpts from the example code demonstrating TCI-TM introspection capabilities:

String[] sessionList =
    ((com.openttcn.sdk.tci.TciTMRequired) req).getSessionList();

...

// The following is done for the currently selected test session:

org.etsi.ttcn.tci.TciModuleParameterList
    moduleParList = req.tciGetModuleParameters(null);

...

org.etsi.ttcn.tci.TciTestCaseIdList
    testCaseIdList = req.tciGetTestCases();

...

// The following is done for the current test case:

org.etsi.ttcn.tci.TciParameterTypeList
    tcPars = req.tciGetTestCaseParameters(testCaseId);

...

org.etsi.ttcn.tri.TriPortIdList
    tcTSI = req.tciGetTestCaseTSI(testCaseId);