From bf54e8a1345673496518437421d1653e6b9db6cf Mon Sep 17 00:00:00 2001
From: Kristof Szabados <Kristof.Szabados@ericsson.com>
Date: Sun, 5 May 2019 16:25:37 +0200
Subject: [PATCH] some more Java side documentation updates.

Signed-off-by: Kristof Szabados <Kristof.Szabados@ericsson.com>
---
 .../1-about_the_document.adoc                 |   8 ++
 .../2-ttcn-3_limitations_in_this_version.adoc |  15 +++
 .../4-ttcn3_language_extensions.adoc          | 104 ++++++++++++++++++
 .../JavaReferenceGuide.adoc                   |  11 +-
 4 files changed, 130 insertions(+), 8 deletions(-)
 create mode 100644 usrguide/java_referenceguide/2-ttcn-3_limitations_in_this_version.adoc
 create mode 100644 usrguide/java_referenceguide/4-ttcn3_language_extensions.adoc

diff --git a/usrguide/java_referenceguide/1-about_the_document.adoc b/usrguide/java_referenceguide/1-about_the_document.adoc
index bc7c0197f..235dcb37d 100644
--- a/usrguide/java_referenceguide/1-about_the_document.adoc
+++ b/usrguide/java_referenceguide/1-about_the_document.adoc
@@ -9,6 +9,14 @@ The purpose of this document is to provide detailed information on writing compo
 
 This document is intended for programmers of TTCN–3 test suites, using the prototype Java code generator provided in the plugins, with information in addition to that provided in the <<_13, TITAN User Guide>>, <<_16, API Technical Reference>> and <<_27, Programmers' Technical Reference Guide>>. It is recommended that the programmer reads the TITAN User Guide before reading this document.
 
+== Naming Convention
+
+This document uses the expressions "C side" and "Java side" in relation to the TITAN TTCN-3 Toolset and Test Executor.
+
+*C side* is used to reference the "original" part of the TITAN TTCN-3 Toolset available from command line. The compiler, makefile generator, the libraries users need to link their executables to during build time.
+
+*Java side* is used to reference the part of the TITAN TTCN-3 Toolset supporting compiling TTCN-3 and ASN.1 code into Java classes via Java source code and the runtime libraries needed for this form of building.
+
 == Typographical Conventions
 
 This document uses the following typographical conventions:
diff --git a/usrguide/java_referenceguide/2-ttcn-3_limitations_in_this_version.adoc b/usrguide/java_referenceguide/2-ttcn-3_limitations_in_this_version.adoc
new file mode 100644
index 000000000..58113d069
--- /dev/null
+++ b/usrguide/java_referenceguide/2-ttcn-3_limitations_in_this_version.adoc
@@ -0,0 +1,15 @@
+= TTCN-3 Limitations in this Version
+:toc:
+
+The present Test Executor is an implementation of TTCN–3 Core Language standard (<<13-references.adoc#_1, [1]>>) with support of ASN.1 (<<13-references.adoc#_3, [3]>>). However, the TTCN–3 language constructs detailed in <<13-references.adoc#_27, [27]>> are not supported in the current version of the Test Executor on both the C and the Java side.
+The following list extend that list, with the TTCN–3 language constructs that are not supported, in addition, in the current version of the Java side of the Test Executor.
+
+When applicable, the relevant clause of the standard text (<<13-references.adoc#_1, [1]>>) is given within parentheses after each limitation. The list of ASN.1 related limitations can be found in chapter *4.25*.
+
+* The `update`, `interleave`, `label`, `goto` statements are not yet supported. (19.7, 19.8, 20.4 and 22.3.1 in <<13-references.adoc#_1, [1]>>)
+* The `hostId` predefined function is not yet supported.
+
+* Additionally the `start_profiler`, `stop_profiler`, `string2ttcn` TITAN extensions are also not yet supported on the Java side.
+* The `profilerrunning` TITAN extension is also not supported.
+* Concatenating template strings is not yet supported on the Java side.
+* Type compatibility is not yet supported on the Java side.footnote:[except record of/set of types for certain element types, see section 4.32.2]
diff --git a/usrguide/java_referenceguide/4-ttcn3_language_extensions.adoc b/usrguide/java_referenceguide/4-ttcn3_language_extensions.adoc
new file mode 100644
index 000000000..1b66094a0
--- /dev/null
+++ b/usrguide/java_referenceguide/4-ttcn3_language_extensions.adoc
@@ -0,0 +1,104 @@
+[[ttcn-3-language-extensions]]
+= TTCN–3 Language Extensions
+:toc:
+:table-number: 3
+
+The Test Executor supports several non-standard additions to TTCN–3 Core Language, as detailed in <<13-references.adoc#_27, [27]>>, in order to improve its usability or provide backward compatibility with older versions.
+
+The following list contains the TTCN–3 language extensions that are not yet supported by the Java side of the Test Executor.
+The sections/feature not listed here are supported.
+
+
+[[ttcn-3-preprocessing]]
+== TTCN–3 Preprocessing
+
+Preprocessing of the TTCN-3 files with a C style preprocessor is supported by the Java side.
+
+Contrary to the C side, on the Java side preprocessing is supported by an internal pre-processor. That is the generated Java files will already have the pre-processable content pre-processed.
+
+Parameterized macros are not supported on the Java side.
+
+
+== Implicit Message Encoding
+
+Compared to the description in section 3.22 of <<13-references.adoc#_27, [27]>> the Java side has 2 major differences:
+Only RAW encoding is supported for now.
+the syntax to be used in Java differs slightly from the of used in {cpp}
+
+The TTCN–3 attribute `errorbehavior(INCOMPL_ANY:ERROR)`, for example, instead of being mapped to the following {cpp} statement
+[source]
+----
+TTCN_EncDec::set_error_behavior(TTCN_EncDec::ET_INCOMPL_ANY,
+  TTCN_EncDec::EB_ERROR);
+----
+
+is mapped to the following Java statement
+[source]
+----
+TTCN_EncDec.et_error_behavior(TTCN_EncDec.error_type.ET_INCOMPL_ANY,
+  TTCN_EncDec.error_behavior_type.EB_ERROR);
+----
+
+
+== RAW Encoder and Decoder
+
+The Java side supports the same RAW Encoder and Decoder features as the C side.
+
+
+== TEXT Encoder and Decoder
+
+The TEXT Encoder and Decoder is not yet supported on the Java side.
+
+== XML Encoder and Decoder
+
+The XML Encoder and Decoder is not yet supported on the Java side.
+
+== JSON Encoder and Decoder
+
+The XML Encoder and Decoder is not yet supported on the Java side.
+
+== OER Encoder and Decoder
+
+The OER Encoder and Decoder is not yet supported on the Java side.
+
+[[build-consistency-checks]]
+== Build Consistency Checks
+
+Executable test suites are typically put together from many sources, some of which (test ports, function libraries, etc.) are not written by the test writers themselves, but are developed independently. Sometimes, a test suite requires an external component with a certain feature or bug fix, or a certain minimum TITAN version. Building with a component which does not meet a requirement, or an old TITAN version, typically results in malfunction during execution or cryptic error messages during build. If version dependencies are specified explicitly, they can be checked during build and the mismatches can be reported.
+
+=== Version Information in TTCN-3 Files
+
+TITAN allows test writers to specify that a certain TTCN-3 module requires a minimum version of another TTCN-3 module or a minimum version of TITAN.
+
+The Java side of the toolset provides the same features as the C side for TTCN-3 level checking of consistency.
+
+=== Consistency Check in the Generated Code
+
+The java side offers different consistency checks compared to the C side, for the generated code.
+
+When connecting to the Main Controller in parallel mode, TITAN verifies that the Main Controller and the Java side binaries are of the exact same version of TITAN.
+This is done to ensure that, that both sides use the same communication protocol.
+
+What is not checked on the Java side or checked differently:
+* There is no platform check as Java is platform independent.
+* The Java runtime will check if it can execute the compiled code. Generally a Java runtime should be able to execute any Java code built using an earlier Java version.
+* During the compilation of the Java code, the Java compiler will check if it is able to compile all parts of the code.
+
+== Negative Testing
+
+Negative Testing is not yet supported on the Java side.
+
+== Differences between the Java side runtime, the C side Load Test Runtime and the C side Function Test Runtime
+
+The Java side was based on the Load Test runtime of the C side.
+For now it has the same features and limitations.
+
+Please note, that based on the differences between Java and {cpp}, the Java runtime should be treated as its own version of the runtime, when preparing for future developments.
+
+
+[[profiling-and-code-coverage]]
+== Profiling and code coverage
+
+The Java side does not yet support profiling and code coverage measuring support directly.
+
+For the time being we recommend using the tools built into Eclipse on the Java generated code (The Java side projects also behave as normal Java projects for Eclipse tooling), or other tools provided for Java.
diff --git a/usrguide/java_referenceguide/JavaReferenceGuide.adoc b/usrguide/java_referenceguide/JavaReferenceGuide.adoc
index 769994cc9..dcf180705 100644
--- a/usrguide/java_referenceguide/JavaReferenceGuide.adoc
+++ b/usrguide/java_referenceguide/JavaReferenceGuide.adoc
@@ -32,9 +32,6 @@ https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.html.
 The contents of this document are subject to revision without notice due to continued progress in methodology, design and manufacturing. Ericsson should have no liability for any error or damage of any kind resulting from the use of this document.
 
 ////
-TTCN-3 Limitations in this Version
-Clarifications to the TTCN-3 Standard
-TTCN–3 Language Extensions
 Supported ASN.1 Constructs and Limitations
 Compiling TTCN–3 and ASN.1 Modules
 XSD to TTCN-3 Converter ... kulso hivas
@@ -54,10 +51,9 @@ Mapping TTCN-3 Data Type to Java constructs
 
 ifdef::env-github,backend-html5[]
 * link:1-about_the_document.adoc[About the document]
-////
 * link:2-ttcn-3_limitations_in_this_version.adoc[TTCN-3 Limitations in this Version]
-* link:3-clarifications_to_the_ttcn-3_standard.adoc[Clarifications to the TTCN-3 Standard]
 * link:4-ttcn3_language_extensions.adoc[TTCN–3 Language Extensions]
+////
 * link:5-supported_asn1_constructs_and_limitations.adoc[Supported ASN.1 Constructs and Limitations]
 * link:6-compiling_ttcn3_and_asn1_modules.adoc[Compiling TTCN–3 and ASN.1 Modules]
 * link:7-the_run-time_configuration_file.adoc[The Run-time Configuration File]
@@ -79,10 +75,9 @@ endif::[]
 
 ifndef::env-github,backend-html5[]
 include::1-about_the_document.adoc[leveloffset=+1]
+include::2-ttcn-3_limitations_in_this_version.adoc[leveloffset=+1]
+include::4-ttcn3_language_extensions.adoc[leveloffset=+1]
 ////
-//include::2-ttcn-3_limitations_in_this_version.adoc[leveloffset=+1]
-//include::3-clarifications_to_the_ttcn-3_standard.adoc[leveloffset=+1]
-//include::4-ttcn3_language_extensions.adoc[leveloffset=+1]
 //include::5-supported_asn1_constructs_and_limitations.adoc[leveloffset=+1]
 //include::6-compiling_ttcn3_and_asn1_modules.adoc[leveloffset=+1]
 //include::7-the_run-time_configuration_file.adoc[leveloffset=+1]
-- 
GitLab