From 6e034fc3a709d20f98b7af58ed761de6f3ecd0ef Mon Sep 17 00:00:00 2001
From: Kristof Szabados <Kristof.Szabados@ericsson.com>
Date: Wed, 13 May 2020 14:02:28 +0200
Subject: [PATCH] add basic description for JSON coding.
Signed-off-by: Kristof Szabados <Kristof.Szabados@ericsson.com>
---
.../11-encoding_and_decoding.adoc | 169 +++++++++++++++++-
.../3-ttcn3_language_extensions.adoc | 5 +-
2 files changed, 167 insertions(+), 7 deletions(-)
diff --git a/usrguide/java_referenceguide/11-encoding_and_decoding.adoc b/usrguide/java_referenceguide/11-encoding_and_decoding.adoc
index 00a5b578a..251b85375 100644
--- a/usrguide/java_referenceguide/11-encoding_and_decoding.adoc
+++ b/usrguide/java_referenceguide/11-encoding_and_decoding.adoc
@@ -169,9 +169,10 @@ Parameter `p_td` is a special type descriptor. Each type has its own descriptor,
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]:
+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, XER and OER coding is not yet supported]:
-* CT_RAW RAW - coding;
+* CT_RAW - RAW coding;
+* CT_JSON - JSON coding;
The `flavour` parameter is depending on the chosen coding.
@@ -303,6 +304,166 @@ XML encoding and decoding is not yet supported on the Java side.
== JSON
-JSON encoding and decoding is not yet fully supported on the Java side.
+The encoding rules defined in the section "JSON Encoder and Decoder" of the link:https://github.com/eclipse/titan.core/tree/master/usrguide/referenceguide[Programmer's Technical Reference] can be used to encode and decode the following TTCN–3 types:
-Semantic checks for checking that the JSON attribute is used consistently is available, but code generation and runtime support is still missing.
+* anytype
+
+* array
+
+* bitstring
+
+* boolean
+
+* charstring
+
+* enumerated
+
+* float
+
+* hexstring
+
+* integer
+
+* objid
+
+* octetstring
+
+* record`, set
+
+* record of`, set of
+
+* union
+
+* universal charstring
+
+* verdicttype
+
+The rules also apply to the following ASN.1 types (if imported to a TTCN-3 module):
+
+* ANY
+
+* BIT STRING
+
+* BOOLEAN
+
+* BMPString
+
+* CHOICE, open type (in instances of parameterized types)
+
+* ENUMERATED
+
+* GeneralString
+
+* GraphicString
+
+* IA5String
+
+* INTEGER
+
+* NULL
+
+* NumericString
+
+* OBJECT IDENTIFIER
+
+* OCTET STRING
+
+* PrintableString
+
+* RELATIVE`-OID
+
+* SEQUENCE, SET
+
+* SEQUENCE OF, SET OF
+
+* TeletexString
+
+* UniversalString
+
+* UTF8String
+
+* VideotexString
+
+* VisibleString
+
+The compiler will produce code capable of JSON encoding/decoding for compound types if they have at least one JSON variant attribute or the `encode "JSON"` attribute (and, for compound types, all fields and elements of compound types also have a JSON variant attribute or the `encode "JSON"` attribute).
+
+The encoder and the decoder work with JSON data encoded in UTF-8 (described in link:https://tools.ietf.org/html/rfc3629[UTF-8, a transformation format of ISO 10646]), stored in an object of type `TTCN_Buffer`. Although the contents of this object can be retrieved (using the overloads of the `get_string` function) as an instance of `TitanOctetString`, `TitanCharString` or `TitanUniversalCharString`, it is recommended to use only the `TitanOctetString` representation. `TitanCharString` is not recommended, because UTF-8 is an 8-bit encoding so the buffer may contain bytes with values over 127, which are not valid characters for a TTCN-3 `charstring` (which is implemented by `TitanCharString`, see <<5-mapping_ttcn3_data_types_to_c+\+_constructs.adoc#Charstring, Charstring>>). `TitanUniversalCharString` must not be used because its internal representation is not UTF-8.
+
+[[error-situations-3]]
+=== Error Situations
+
+There are no extra error situations apart from the ones in <<the-common-API, The Common API>>.
+
+[[api-3]]
+=== API
+
+The Application Programming Interface for JSON encoding and decoding is described in the following.
+
+[[encoding-3]]
+==== Encoding
+
+[source]
+----
+void encode(final TTCN_Typedescriptor p_td, final TTCN_Buffer p_buf,
+ final coding_type p_coding, final int flavour) const;
+----
+
+The parameter `p_coding` must be set to `TTCN_EncDec.CT_JSON`.
+
+[[decoding-3]]
+==== Decoding
+
+[source]
+----
+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_JSON`.
+
+[[example-3]]
+=== Example
+
+Let us assume that we have a TTCN–3 module which contains a type named `ProtocolPdu`, and this module also contains 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:
+[source]
+----
+void MyPort1.outgoing_send(final ProtocolPdu send_par)
+{
+ final TTCN_Buffer buffer = new TTCN_Buffer();
+ send_par.encode(ProtocolPdu.ProtocolPdu_descr_, buffer, TTCN_EncDec.coding_type.CT_JSON, 0);
+ final TitanOctetString encodedData = new TitanOctetString();
+ buffer.get_string(encodedData);
+ incoming_message(encodedData);
+}
+
+void MyPort2.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_JSON, 0);
+ incoming_message(pdu);
+}
+----
+
+== OER
+
+OER encoding and decoding is not yet supported on the Java side.
diff --git a/usrguide/java_referenceguide/3-ttcn3_language_extensions.adoc b/usrguide/java_referenceguide/3-ttcn3_language_extensions.adoc
index 0087e9437..710c45423 100644
--- a/usrguide/java_referenceguide/3-ttcn3_language_extensions.adoc
+++ b/usrguide/java_referenceguide/3-ttcn3_language_extensions.adoc
@@ -53,11 +53,10 @@ The TEXT Encoder and Decoder is not yet supported on the Java side.
The XML Encoder and Decoder is not yet supported on the Java side.
+[[JSON-Encoder-and-Decoder]]
== JSON Encoder and Decoder
-The JSON Encoder and Decoder is not yet fully supported on the Java side.
-
-Semantic checks for checking that the JSON attribute is used consistently is available, but code generation and runtime support is still missing.
+The Java side supports the same RAW Encoder and Decoder features as the C side.
== OER Encoder and Decoder
--
GitLab