From 0571933ceb074f493253604e7341851c1a3b7d9d Mon Sep 17 00:00:00 2001
From: Kristof Szabados <Kristof.Szabados@ericsson.com>
Date: Sat, 11 May 2019 17:46:39 +0200
Subject: [PATCH] add the adoc for encoding decoding.

Signed-off-by: Kristof Szabados <Kristof.Szabados@ericsson.com>
---
 .../4-encoding_and_decoding.adoc              | 305 ++++++++++++++++++
 1 file changed, 305 insertions(+)
 create mode 100644 usrguide/java_referenceguide/4-encoding_and_decoding.adoc

diff --git a/usrguide/java_referenceguide/4-encoding_and_decoding.adoc b/usrguide/java_referenceguide/4-encoding_and_decoding.adoc
new file mode 100644
index 000000000..efc171ec7
--- /dev/null
+++ b/usrguide/java_referenceguide/4-encoding_and_decoding.adoc
@@ -0,0 +1,305 @@
+= Encoding and Decoding
+
+:table-number: 2
+:toc:
+
+TITAN is equipped with several standard encoding/decoding mechanisms. A part of these functions reside in the core library, but the type-dependent part must be generated by the Java code generator. In order to reduce the code size and compilation time, the code generation for encoding functions (separately for different encoders) can be switched off if they are not needed. FIXME link a beallitasokra.
+
+To make it easier to use the encoding features, a unified common API was developed. With help of this API the behaviour of the test executor in different error situations can be set during coding. There is also a common buffer class. The details of the above mentioned API as well as the specific features of the certain encoders are explained in the following sections.
+
+[[the-common-API]]
+== The Common API
+
+The common API for encoders consists of three main parts:
+
+* A dummy class named `TTCN_EncDec` which encapsulates functions regarding error handling.
+
+* A buffer class named `TTCN_Buffer` which is used by the encoders to put data in, decoders to get data from.
+
+* The functions needed to encode and decode values.
+
+[[ttcn-encdec]]
+=== TTCN_EncDec
+
+`TTCN_EncDec` implements error handling functions.
+
+==== Setting Error Behavior
+
+There are lot of error situations during encoding and decoding. The coding functions can be told what to do if an error arises. To set the behaviour of test executor in a certain error situation the following function is to be invoked from the `TTCN_EncDec` class:
+[source, subs="+quotes"]
+static void set_error_behavior(final error_type p_et, final error_behavior_type p_eb);
+
+WARNING: As error_type and error_behavior_type are enums defined in TTCN_EncDec class, they have to prefixed with the class name (that is `TTCN_EncDec.`).
+An example usage:
+[source, subs="+quotes"]
+TTCN_EncDec.set_error_behavior(TTCN_EncDec.error_type.ET_ALL, TTCN_EncDec.error_behavior_type.EB_DEFAULT);
+
+The possible values of `error_type` are detailed in the sections describing the different codings. Some common error types are shown in the table below:
+
+.Common error types
+[width="100%",cols="30%,70%",options="header",]
+|=========================================================================================
+|ET_UNDEF |Undefined/unknown error.
+|ET_UNBOUND |Encoding of an unbound value.
+|ET_REPR |Representation error (for example, internal representation of integral numbers).
+|ET_ENC_ENUM |Encoding of an unknown enumerated value.
+|ET_DEC_ENUM |Decoding of an unknown enumerated value.
+|ET_INCOMPL_MSG |Decode error: incomplete message.
+|ET_INVAL MSG |Decode error: invalid message.
+|ET_CONSTRAINT |The value breaks some constraint.
+|ET_INTERNAL |Internal error. Error behaviour cannot be set for this.
+|ET_ALL |All error type. Usable only when setting error behaviour.
+|ET_NONE |No error.
+|=========================================================================================
+
+The possible values of `error_behavior_type` are shown in the table below:
+
+.Possible values of `error_behavior_t`
+
+[cols="30%,70%"]
+|=========================================================================
+|EB_DEFAULT |Sets the default error behaviour for the selected error type.
+|EB_ERROR |Raises an error if the selected error type occurs.
+|EB_WARNING |Gives a warning message but tries to continue the operation.
+|EB_IGNORE |Like warning but without the message.
+|=========================================================================
+
+==== Getting Error Behavior
+
+There are two functions: one for getting the current setting and one for getting the default setting for a particular error situation.
+[source]
+----
+static error_behavior_type get_error_behavior(final error_type p_et)
+static error_behavior_type get_default_error_behavior(final error_type p_et)
+----
+The using of these functions are straightforward: giving a particular `error_type` the function returns the current or default `error_behavior_type` for that error situation, respectively.
+
+==== Checking if an Error Occurred
+
+The last coding-related error and its textual description can be retrieved anytime. Before using a coding function, it is advisable to clear the "last error". This can be achieved by the following method:
+[source, subs="+quotes"]
+static void clear_error();
+
+After using some coding functions, it can be checked if an error occurred with this function:
+[source, subs="+quotes"]
+static error_type get_last_error_type();
+
+This returns the last error, or `ET_NONE` if there was no error. The string representation of the error can be requested with the help of this:
+[source, subs="+quotes"]
+static String get_error_str();
+
+WARNING: The above two functions do not clear the "last error" flag.
+
+[[ttcn-buffer]]
+=== TTCN_Buffer
+
+TTCN Buffer objects are used to store encoded values and to communicate with the coding functions. If encoding a value, the result will be put in a buffer, from which can be get. In the other hand, to decode a value, the encoded octet string must be put in a TTCN_Buffer object, and the decoding functions get their input from that.
+[source, subs="+quotes"]
+void clear();
+
+Resets the buffer, cleaning up its content, setting the pointers to the beginning of buffer.
+[source, subs="+quotes"]
+void rewind();
+
+Rewinds the buffer, that is, sets its reading pointer to the beginning of the buffer.
+[source, subs="+quotes"]
+int get_pos();
+
+Returns the (reading) position of the buffer.
+[source, subs="+quotes"]
+void set_pos(final int new_pos);
+
+Sets the (reading) position to pos, or to the end of buffer, if `pos > get_len()`.
+[source, subs="+quotes"]
+int get_len();
+
+Returns the amount of bytes in the buffer.
+[source, subs="+quotes"]
+char[] get_data();
+
+Returns a copy of the buffer starting from its start. You can read out `count` bytes beginning from this address, where `count` is the value returned by the `get_len()` member function.
+[source, subs="+quotes"]
+int get_read_len();
+
+Returns how many bytes are in the buffer to read.
+[source, subs="+quotes"]
+char[] get_read_data();
+
+Returns a copy of the buffer starting from the read position of data. `count` bytes can be read out beginning from this address, where count is the value returned by the `get_read_len()` member function.
+[source, subs="+quotes"]
+void put_c(final char c);
+
+Appends the byte `c` to the end of buffer.
+[source, subs="+quotes"]
+void put_s(final char[] cstr);
+
+Writes a string of bytes to the end of buffer.
+[source, subs="+quotes"]
+void put_os(final TitanOctetString p_os);
+
+Appends the content of the octet string to the buffer.
+
+[source, subs="+quotes"]
+void increase_length(final int size_incr);
+
+Increases the size of the buffer.
+[source, subs="+quotes"]
+void cut();
+
+Cuts (removes) the bytes between the beginning of the buffer and the read position. After calling this, the read position will be the beginning of buffer. As this function manipulates the internal data, pointers referencing to data inside the buffer will be invalid.
+[source, subs="+quotes"]
+void cut_end();
+
+Cuts (removes) the bytes between the read position and the end of the buffer. After calling this, the read position remains unchanged (that is, it will point to the end of the truncated buffer). As this function manipulates the internal data, pointers referencing to data inside the buffer will be invalid.
+
+=== Invoking the Coding Functions
+
+Every type class has members like these:
+
+[source]
+----
+public void encode(final TTCN_Typedescriptor p_td, final TTCN_Buffer p_buf,
+		 final coding_type p_coding, final int flavour);
+public void decode(final TTCN_Typedescriptor p_td,
+		final TTCN_Buffer p_buf, final coding_type p_coding, final int flavour);
+----
+
+Parameter `p_td` is a special type descriptor. Each type has its own descriptor, which contains the name of the type, and a lot of information used by the different encoding mechanisms. The names of the descriptors come from the name of the types: the appropriate type descriptor for type `XXX is XXX_descr_`.
+
+Parameter `p_buf` contains the encoded value. For details about using it, please consult the previous subsection.
+
+Parameter `p_coding` is the desired coding mechanism. As `coding_type` is defined in `TTCN_EncDec`, its value must be prefixed with `TTCN_EncDec.`. For the time being, this parameter may have one of the following valuesfootnote:[BER, TEXT and XER coding is not yet supported]:
+
+* CT_RAW RAW - coding;
+
+The `flavour` parameter is depending on the chosen coding.
+
+== BER
+BER encoding and decoding is not yet supported on the Java side.
+
+== RAW
+
+You can use the encoding rules defined in the section "RAW encoder and decoder" in the link:https://github.com/eclipse/titan.core/tree/master/usrguide/referenceguide[Programmer's Technical Reference] to encode and decode the following TTCN–3 types:
+
+* boolean
+
+* integer
+
+* float
+
+* bitstring
+
+* octetstring
+
+* charstring
+
+* hexstring
+
+* enumerated
+
+* record
+
+* set
+
+* union
+
+* record of
+
+* set of
+
+The compiler will produce code capable of RAW encoding/decoding for compound types if they have at least one `variant` attribute. +
+When a compound type is only used internally or it is never RAW encoded/decoded then the attribute `variant` has to be omitted. +
+ When a type can be RAW encoded/decoded but with default specification then the empty variant specification can be used: `variant ""`.
+
+[[error-situations-0]]
+=== Error Situations
+
+.RAW-coding errors
+
+[width="100%",cols="30%,70%",options="",]
+|============================================================================================================================================================
+|ET_LEN_ERR |During encoding: Not enough length specified in FIELDLENGTH to encode the value. During decoding: the received message is shorter than expected.
+|ET_SIGN_ERR |Unsigned encoding of a negative number.
+|ET_FLOAT_NAN |Not a Number float value has been received.
+|ET_FLOAT_TR |The float value will be truncated during double to single precision conversion.
+|============================================================================================================================================================
+
+[[api-0]]
+=== API
+
+The Java Application Programming Interface for RAW encoding and decoding is described in the following. It can be used for example in test port implementation, in external function implementation.
+
+[[encoding-0]]
+==== Encoding
+
+[source]
+----
+public void encode(final TTCN_Typedescriptor p_td, final TTCN_Buffer p_buf,
+		 final coding_type p_coding, final int flavour);
+----
+
+The parameter `p_coding` must be set to `TTCN_EncDec.CT_RAW`.
+
+[[decoding-0]]
+==== Decoding
+
+[source]
+----
+public void decode(final TTCN_Typedescriptor p_td,
+		final TTCN_Buffer p_buf, final coding_type p_coding, final int flavour);
+----
+
+The parameter `p_coding` must be set to `TTCN_EncDec.CT_RAW`.
+
+[[example-0]]
+=== Example
+
+Let us assume that we have a TTCN–3 module which contains a type named `ProtocolPdu`, and this module contains also two ports:
+[source]
+----
+type port MyPort1 message
+{
+  out ProtocolPdu;
+  in octetstring;
+}
+
+type port MyPort2 message
+{
+  out octetstring;
+  in ProtocolPdu;
+}
+----
+
+Then we can complete the port skeleton generated by the compiler as follows:
+[source]
+----
+protected void outgoing_send(final ProtocolPdu send_par) {
+	final TTCN_Buffer buffer = new TTCN_Buffer();
+	send_par.encode(Bug.ProtocolPdu_descr_, buffer, TTCN_EncDec.coding_type.CT_RAW, 0);
+	final TitanOctetString encodedData = new TitanOctetString();
+	buffer.get_string(encodedData);
+	incoming_message(encodedData);
+}
+
+protected void outgoing_send(final TitanOctetString send_par) {
+		TTCN_EncDec.set_error_behavior(TTCN_EncDec.error_type.ET_ALL, TTCN_EncDec.error_behavior_type.EB_WARNING);
+		final TTCN_Buffer buffer = new TTCN_Buffer();
+		buffer.put_os(send_par);
+		final ProtocolPdu pdu = new ProtocolPdu();
+		pdu.decode(Bug.ProtocolPdu_descr_, buffer, TTCN_EncDec.coding_type.CT_RAW, 0);
+		incoming_message(pdu);
+	}
+----
+
+== TEXT
+
+TEXT encoding and decoding is not yet supported on the Java side.
+
+[[xml-encoding-xer]]
+== XML Encoding (XER)
+
+XML encoding and decoding is not yet supported on the Java side.
+
+== JSON
+
+JSON encoding and decoding is not yet supported on the Java side.
-- 
GitLab