7-launching_TITAN_Java_projects.adoc 12.6 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
= Launching TITAN Java Projects
:figure-number: 42

This chapter describes the launching modes of TITAN Java projects.

After building a TITAN Java project, it is ready to be launched as a Java project.
In Eclipse, every aspect of the launch can be configured, for example, different environmental settings can be created by creating different launch configurations, without modifying the system environment variables, so different test environments can be created.

NOTE: Right now the Java side of the TITAN Test Executor is supported as a Java application native to Eclipse. It as executed with the same limitations and benefits.

Adam Knapp's avatar
Adam Knapp committed
11
WARNING: The execution of TITAN Java projects (the Java side of the Test Executor) is done as Eclipse native Java applications. It is not yet fully integrated to the usual Interface elements like Views that support the execution of the binaries of the C side of the TITAN Test Executor.
12
13
14
15

[[launching-modes-supported-by-the-TITAN-Executor-plug-in-for-TITAN-Java-Projects]]
== The Launching Modes Supported by the TITAN Executor Plug-in for TITAN Java Projects

Adam Knapp's avatar
Adam Knapp committed
16
The TITAN Executor can operate in single or in parallel mode.
17

balaskoa's avatar
balaskoa committed
18
19
From the point of view there are 2 ways to execute TITAN Java projects: 
from Eclipse as Java projects and executing exported jar files.
20
21
22

=== Executing TITAN Java Projects from Eclipse

Adam Knapp's avatar
Adam Knapp committed
23
24
To execute TITAN Java projects inside Eclipse requires the creation of a Launch configuration. For TITAN Java Projects the TITAN Native Java launch configuration mode is necessary that supports both the single and parallel execution modes. Launch configurations can be created, modified and deleted in the *Create, manage, and run configuration* dialog window. It can be opened in numerous ways as detailed in <<creating-launch-configuration,Creating Launch Configuration>>:

Adam Knapp's avatar
Adam Knapp committed
25
* using the *Run as* option in pop-up menu of the *Project explorer* (<<Figure-4-F7,Figure 7>>),
Adam Knapp's avatar
Adam Knapp committed
26

Adam Knapp's avatar
Adam Knapp committed
27
* using the *Launch Commands* on the toolbar (<<Figure-4-F8,Figure 8>>).
28

Adam Knapp's avatar
Adam Knapp committed
29
Furthermore, a default launch configuration can be created using launch shortcuts. It works the same way as described in <<creating-launch-configuration,Creating Launch Configuration>>, however the TITAN Native Java launching mode requires less option, i.e.:
30

Adam Knapp's avatar
Adam Knapp committed
31
. A new launch configuration is made.
32

Adam Knapp's avatar
Adam Knapp committed
33
. The project and configuration file paths are initialized.
34

Adam Knapp's avatar
Adam Knapp committed
35
. Finally the newly created launch configuration is launched automatically in parallel execution mode.
36

Adam Knapp's avatar
Adam Knapp committed
37
The launch configuration created using launch shortcuts is automatically added to favorite list under the *Launch Commands* (<<Figure-4-F8,Figure 8>>).
38

Adam Knapp's avatar
Adam Knapp committed
39
NOTE: It is encouraged to use the launch shortcuts to reduce the number of possible mistakes. The generated launch configuration is still editable in the *Create, manage, and run configuration* dialog window (see below).
40

Adam Knapp's avatar
Adam Knapp committed
41
=== Basic Main Controller Options Page of the Launch Configuration
42

Adam Knapp's avatar
Adam Knapp committed
43
44
[[Figure-7-F43]]
image::images/7_F43.png[title="Basic Main Controller options page"]
45

Adam Knapp's avatar
Adam Knapp committed
46
On this page it is possible to set:
47

Adam Knapp's avatar
Adam Knapp committed
48
* The name of the project.
49
+
Adam Knapp's avatar
Adam Knapp committed
50
Filling this field is mandatory. The entered name is checked for validity. The project's root folder is used during the automatically filling of the other fields. The path variables are relative to the project's root supporting the portability of the project as whole. If you enter the name of a valid project with TITAN nature (or select one by browsing, as can be seen on <<Figure-13,Figure 13>>), the configuration file will be filled in automatically.
51

Adam Knapp's avatar
Adam Knapp committed
52
NOTE: It is encouraged to use the *Browse Workspace* button to select a valid project from the workspace that simplifies the filling of the other fields, as well as reduces the possible mistakes. 
53

Adam Knapp's avatar
Adam Knapp committed
54
* The path of the configuration file.
55
+
Adam Knapp's avatar
Adam Knapp committed
56
Please note that not only the existence but also the validity of the configuration file is evaluated here. If a problem was found while trying to process the configuration file, the launch process will be interrupted here. Please note that this evaluation is done every time this configuration page becomes active, meaning that switching to and from this page can take some time. The entered file path is checked for validity.
57

Adam Knapp's avatar
Adam Knapp committed
58
* Execute automatically
59
+
Adam Knapp's avatar
Adam Knapp committed
60
Whether the user wish to start executing the configuration file automatically when the launcher is started. Please note that this option is turned on by default.
61

Adam Knapp's avatar
Adam Knapp committed
62
63
64
* Execute in single mode
+
Whether the user wish to start executing the TITAN Java project in single or in parallel mode. Please note that this option is turned off by default.
65

Adam Knapp's avatar
Adam Knapp committed
66
All fields can be filled in either by entering the proper values, or via browsing for them.
67

Adam Knapp's avatar
Adam Knapp committed
68
If you press *Apply* some other launch configurations will appear automatically according to the filled values in the *Create, manage, and run configuration* dialog window.
69

Adam Knapp's avatar
Adam Knapp committed
70
71
72
[NOTE]
====
During the filling Eclipse might ask for saving the modification.
73

Adam Knapp's avatar
Adam Knapp committed
74
75
Sometimes Eclipse automatically switches to one of the additionally created launch configuration after saving the TITAN Native Java launch configuration.
====
76

Adam Knapp's avatar
Adam Knapp committed
77
The functionality of other tab pages of the TITAN Native Java launch configuration matches the ones for JNI launch mode, see <<creating-launch-configuration,Creating Launch Configuration>>.
78

79
=== Executing TITAN Java project via exported JAR files
80

81
This subsection describes how to export a TITAN Java project into a JAR file and how to set up the automatic JAR export for the project. Finally, the execution of the project via CLI is presented.
82

83
84
85
==== Exporting TITAN Java project into JAR file using wizard

It is possible to export TITAN Java project into a single JAR file and use it as executables. This feature is provided by the in-built *Runnable JAR file* export wizard of the Eclipse IDE.
86
87
88
89
90
91
92

To export a .jar file from a TITAN Java project:

1. Select the project in the navigator/project explorer view.

2. In the right click menu, select *Export...*.

Adam Knapp's avatar
Adam Knapp committed
93
3. In the window appearing select *Java / Runnable JAR file* and than *Next* (see <<Figure-7-F46,below>>).
94
95
96
97
+
[[Figure-7-F46]]
image::images/7_F46.png[title="Export wizard"]

Adam Knapp's avatar
Adam Knapp committed
98
4. Configure the export (see <<Figure-7-F47,below>>).
99
100
101
102
103
104
+
[[Figure-7-F47]]
image::images/7_F47.png[title="Export wizard for JAR file"]
+
The following options are available:

105
106
107
* *Launch Configuration*: select the launch configuration that configures the execution for this JAR file. This will set the class to be used for execution, i.e. the main class defined by the selected launch configuration will be the default entry point of the exported JAR file.

NOTE: Only launch configurations of Java application type are available for selection here. If such configuration is not created previously, you have to create one to continue.
108
109
110

* *Export destination*: select the file into which the export should be done.

111
* *Library handling*: It is possible to configure how the libraries are handled in the resulting jar. We recommend selecting the *Package required libraries into generated JAR*.
112
113
114

5. Select *Finish*.

115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
==== Automated exporting TITAN Java project into JAR file

In most cases, the manual JAR export using the Runnable JAR file export wizard is sufficient. However, in certain use case it is more convenient to automate this procedure especially when working with relatively small projects that content is often modified and JAR export is needed.

To turn on the automated JAR export, first navigate to the project properties page:

1. Select the project in the navigator/project explorer view.

2. In the right click menu, select *Properties*.

Then, the default target has to be set and the path of the JAR file has to be specified:

1. In the left tab, select *TITAN Project Property (Java)*.

2. Select *Java target creation attributes* tab.

3. Select *Executable JAR* from the drop-down list as the default target.

4. Specify the path of the JAR file in the text box.

5. Finally, apply the new settings.

[[Figure-7-automated_jar_export]]
image::images/7_automated_jar_export.png[title="Turning on automated JAR export"]

As a result, 'jarbuild.xml' ANT build script will appear in the project's root and a new ANT builder is specified for the project.
To build the JAR file, the project has to be built as usual (Right click on the project/Build Project).
At the end of the build process, the ANT will create the executable JAR according to the 'jarbuild.xml'.

[NOTE]
====
If there is no change in the project, the build process will not start (even if the executable JAR file does not exist).

The automated JAR build procedure can be customized on demand. The generated ANT build script describes the JAR building attributes. While the newly added ANT builder automatically executes this ANT build script.
====

To turn off the automated JAR export, just set the default target to *Class files*. 

153
154
==== Executing with JAR files in single mode

155
156
The Java side of the TITAN Test Executor, in the case of the exported JAR files, follows the same procedures as the C side does described in the User Guide for TITAN TTCN-3 Test Executor<<8-references.adoc#_3, [3]>>.
However, there are some differences related to executing JAR files. The executable JAR file contains the host controller for both in single and parallel mode.
157
158
159
160

For example executing a generated executable, in single mode, on the C side:
[source]
----
161
./helloWorld.exe config.cfg
162
163
----

164
Executing an exported JAR file, in single mode, on the Java side, use the following command:
165
166
[source]
----
167
168
169
170
171
172
java -jar jar_file.jar config_file.cfg
----
For example:
[source]
----
java -jar helloWorld.jar config.cfg
173
174
----

175
176
177
178
179
180
181
182
183
184
185
186
187
If the parallel execution mode is specified as the default entry point of the executable JAR, the following command should be used:
[source]
----
java -cp jar_file.jar org.eclipse.titan.{name of project}.generated.Single_main config_file.cfg
----
For example:
[source]
----
java -cp helloWorld.jar org.eclipse.titan.helloWorld.generated.Single_main config.cfg
----

NOTE: During the JAR export process, the selected launch configuration determines the default entry point of the executable JAR file, i.e. either single or parallel execution mode will be started by the 'java -jar' command.

188
189
==== Executing with JAR files in parallel mode

190
The Java side of the TITAN Test Executor, in the case of the exported JAR files, follows the same procedures as the C side does described in the User Guide for TITAN TTCN-3 Test Executor<<8-references.adoc#_3, [3]>>.
191
192
193
194
195
With differences related to executing Java files.

To execute test suites in parallel mode first the Main Controller needs to be started:
[source]
----
196
$ ./mctr_cli.exe config.cfg
197
198
199

*************************************************************************
* TTCN-3 Test Executor - Main Controller 2                              *
200
* Version: 7.2.1                                           *
Adam Knapp's avatar
Adam Knapp committed
201
* Copyright (c) 2000-2021 Ericsson Telecom AB                           *
202
203
204
205
206
207
* All rights reserved. This program and the accompanying materials      *
* are made available under the terms of the Eclipse Public License v2.0 *
* which accompanies this distribution, and is available at              *
* https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.html            *
*************************************************************************

208
Using configuration file: config.cfg
209
210
211
212
213
214
215
216
217
MC@HU-00000227: Listening on TCP port 7339.
MC2>
----

It will tell us, that it accepts connections on the localhost machine, on the port number 7339.

To connect to it, in parallel mode, on the C side:
[source]
----
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
./helloWorld.exe localhost 7339
----

Executing an exported JAR file, in parallel mode, on the Java side:
[source]
----
java -jar jar_file.jar mctr_ip mctr_port
----
For example:
[source]
----
java -jar helloWorld.jar localhost 7339
----

If the single execution mode is specified as the default entry point of the executable JAR, the following command should be used:
[source]
----
java -cp jar_file.jar org.eclipse.titan.{name of project}.generated.Parallel_main mctr_ip mctr_port
----
For example:
[source]
----
java -cp helloWorld.jar org.eclipse.titan.helloWorld.generated.Parallel_main localhost 7339
241
242
----

243
244
245
246
247
248
249
[NOTE]
====
The automated JAR export feature builds JAR files in parallel execution mode by default.

Alternatively, the Java based host controller can be started using the 'ttcn3_start' script in parallel mode.
It works the same way as starting an executable generated by the C side of the TITAN Test Executor.
For example:
250
251
[source]
----
252
./ttcn3_start helloWorld.jar config.cfg
253
----
254
====
255
256
257
258
259
260
261

==== Tips

It is possible to provide Java VM arguments when executing exported jar files.
For example:
[source]
----
262
java -Xmx1024m -jar helloWorld.jar config.cfg
263
----