![[Main Page]](/themes/Go4ITv2/images/logo.gif){kind=logo}
Introduction
- This document focuses on the Codec Generator (or CD-gen) in Figure 1, whose purpose is to generate the CoDec from the TTCN-3 ATS sources and C++ Codets.
Use Cases
- This section contains a set of use cases that describe the external behavior of this TM module. A use case is a description of a specific interaction that a user (or another module) may have with this module. Use cases are deceptively simple tools for describing the functionality of the software.
- A use case is a simple, straightforward tool that can be used to completely describe all the behavior of a piece of software. It contains a textual description of all the ways that the intended users could work with the software through its interface. Use cases do not describe any internal workings of the software, nor do they explain how that software will be implemented. They simply show the steps that the user follows to use the software to do the work. All the ways the users interact with the software can be described in this manner.
- This section will contain multiple use cases, enough to define all of the interactions the users will have with the module.
- In the following figure a general overview of defined use cases and relationships between the different actors (i.e., users) which have been defined in this section is shown.
UC-1: Generating the CoDec
Summary
- The CoDec Generator provides a command line executable for generating the codec.
Rationale
- In order to generate the CoDec the user executes the CoDec Generator an gives as parameters:
- the list of TTCN-3 files the ATS
- the list of C++ files containing the Codets
- the name of the C++ generated files
Actors
- User
Preconditions
- The ATS and the Codets are ready.
Basic Course of Events
- Step1: The user executes the command line.
- Step2: The generator parses the TTCN-3 files and extracts the type definitions.
- Step3: The generator parses the C++ files and extracts the codet definitions.
- Step4: The generator generates the codecs and merge them with the codets to produce the CoDec.
Alternative Paths
- Alternative1: the TTCN-3 files are incorrect. The generator outputs error message, CoDEc is not generated.
- Alternative2: C++ files for codets are incorrect. The generator outputs error message, CoDec is not generated.
Postconditions
- The CoDec is ready to be compiled by a C++ compiler.
UC-2: Calling codets while encoding (General Case)
Summary
- The CoDec Generator provides several entry points for executing custom code while encoding a value.
Rationale
- When encoding a value, the generated CoDec calls the following customisable member functions:
- PreEncode() called before encoding a value
- PostEncode() called after encoding a value
Actors
- Codet, CoDec
Preconditions
- The C++ object mapping the value to be encoded is instanciated.
- A binary buffer for receiving then encoded result is instanciated, and a marker points at the current position in the buffer.
Basic Course of Events
- Step1: the CoDec is requested to encode a value
- Step2: the CoDec calls the codet PreEncode if defined.
- Step3: the CoDec encodes the value
- Step4: the CoDec calls the codet PostEncode if defined.
Alternative Paths
- In case of error in step 3, an exception is thrown (see also UC-5: Catching Exceptions).
Postconditions
- The encoded value is written to the buffer and the marker points at the first bit after the encoded value.
UC-2bis: Calling codets while decoding (General Case)
Summary
- The CoDec Generator provides several entry points for executing custom code while decoding a value.
Rationale
- When decoding a value, the generated CoDec calls the following customisable member functions:
- PreDecode() called before decoding a value
- PostDecode() called after decoding a value
Actors
- Codet, CoDec
Preconditions
- A binary buffer is instanciated and a marker points at the first bit of the value to be decoded.
- The C++ object that will contain the decoded value is instanciated.
Basic Course of Events
- Step1: the CoDec is requested to decode a value
- Step2: the CoDec calls the codet PreDecode if defined.
- Step3: the CoDec decodes the value
- Step4: the CoDec calls the codet PostDecode if defined.
Alternative Paths
- In case of error in step 3, an exception is thrown (see also UC-5: Catching Exceptions).
Postconditions
- The C++ object is filled with the decoded value and the marker points at the first bit after the decoded value.
UC-3: Calling codets while encoding (Structured Types)
Summary
- The CoDec Generator provides several entry points for executing custom code while encoding a value.
Rationale
- In order to implement the right encoding mechanisms for a given codec referring to a structured TTCN-3 type, the generated CoDec calls the following customisable member functions:
- PreEncode() called before encoding a value
- PreEncodeField() called before encoding a field in a structured type
- PostEncodeField() called after encoding a field in a structured type
- PostEncode() called after encoding a value
Actors
- Codet, CoDec
Preconditions
- The C++ object mapping the value to be encoded is instanciated.
- A binary buffer for receiving then encoded result is instanciated, and a marker points at the current position in the buffer.
Basic Course of Events
- Step1: the CoDec is requested to encode a structured value
- Step2: the CoDec calls the codet PreEncode if defined.
- Step3: for each field
- the CoDec calls the codet PreEncodeField if defined
- the CoDec calls the codet PreEncodeField if defined
- the CoDec calls the codet PostEncodeField if defined
- Step4: the CoDec calls the codet PostEncode if defined.
Alternative Paths
- In case of error in step 3, an exception is thrown (see also UC-5: Catching Exceptions).
Postconditions
- The encoded value is written to the buffer and the marker points at the first bit after the encoded value.
UC-3bis: Calling codets while decoding (Structured Types)
Summary
- The CoDec Generator provides several entry points for executing custom code while decoding a value.
Rationale
- In order to implement the right decoding mechanisms for a given codec referring to a structured TTCN-3 type, the generated CoDec calls the following customisable member functions:
- PreDecode() called before Decoding a value
- PreDecodeField() called before decoding a field in a structured type
- PostDecodeField() called after decoding a field in a structured type
- PostDecode() called after decoding a value
Actors
- Codet, CoDec
Preconditions
- A binary buffer is instanciated and a marker points at the first bit of the value to be decoded.
- The C++ object that will contain the decoded value is instanciated.
Basic Course of Events
- Step1: the CoDec is requested to decode a structured value
- Step2: the CoDec calls the codet PreDecode if defined.
- Step3: for each field
- the CoDec calls the codet PreDecodeField if defined
- the CoDec calls the codet PreDecodeField if defined
- the CoDec calls the codet PostDecodeField if defined
- Step4: the CoDec calls the codet PostDecode if defined.
Alternative Paths
- In case of error in step 3, an exception is thrown (see also UC-5: Catching Exceptions).
Postconditions
- The C++ object is filled with the decoded value and the marker points at the first bit after the decoded value.
UC-4: Executing a codet
Summary
- A common design used for calling and defining codets.
Rationale
- Every codet should have the same calling prototype. The only difference
between two codets is its position in the in the sequence of operations. Actors
- Codet, CoDec
Preconditions
- The C++ object mapping the value being encoded/decoded is instanciated.
- A binary buffer containing then encoded value is instanciated, and a marker points at the current position in the buffer.
Basic Course of Events
- Step1: the CoDec calls the codet (member function) for the C++ object mapping the value being decoded/encoded with the following parameters
- a reference to the binary buffer with its current marker
- the index of the current field (only for PreEncodeField, PostEncodeField, PreDecodeField and PostDecodeField)
- Step2: the body of the codet is executed, possible actions include:
- modifying the buffer, moving its marker
- making hypothesis for the decoder (UC-6, UC-7, UC-8, UC-9 & UC-10)
- access and possibly modify the content of the current object, its children and parent objects.
- Step3: return
Alternative Paths
- In case of error in step 3 the codet throws an exception (see also UC-5: Catching Exceptions).
Postconditions
- None
UC-5: Catching exceptions
Summary
- Special codets can be defined for handling exceptions.
Rationale
- To handle encoding and decoding errors the user needs to catch exceptions.
This can be in a special variant of PostEncode and PostDecode codets. Two variants of these codets can be defined by the user:
- PostEncode(buffer) called after encoding the value successfully
- PostEncode(buffer, exception) called if an exception was caught while encoding
and respectively
- PostDecode(buffer) called after decoding the value successfully
- PostDecode(buffer, exception) called if an exception was caught while decoding
Actors
- Codet, CoDec
Preconditions
- The C++ object mapping the value being encoded/decoded is instanciated.
- A binary buffer containing then encoded value is instanciated, and a marker points at the current position in the buffer.
Basic Course of Events
- Step1: the CoDec is requested to encode (resp. decode) a value
- Step2: the CoDec calls PreEncode if defined (resp. PreDecode)
- Step3: the CoDec enters a try block
- Step4: the CoDec encodes (resp. decodes) the value
- Step5: the CoDec leaves the try block
- Step6: the CoDec calls PostEncode(buffer) if defined (resp. PostDecode(buffer))
Alternative Paths
- If an exception is caught in Step5, the CoDec calls PostEncode(buffer,exception)
(resp. PostDecode(buffer,exception)) and returns immediately without executing Step6 Postconditions
- None
UC-6: Making decoding hypothesis (length of an encoded value)
Summary
- The user can make decoding decisions at runtime.
Rationale
- The size of an encoded variable may not be known in advance, but only during
the process of decoding the message. However the CoDec need to know how to delimit encoded fields so as to decode them separately. When the encoded size of a value can be guessed from another part of the message (e.g. the value of a length field), it can be transmitted to the CoDec by calling SetHypLength() on this value. Actors
- Codet, CoDec
Preconditions
- None
Basic Course of Events
- Step1: while decoding a message, the length of a not-yet decoded field is determined inside a codet
- Step2: the codet calls SetHypLength
- Step3: when the decoder reaches the value it applies the hypothesis given in step 2 and decodes the value
- Step4: if the value cannot be decoded, an exception is thrown
Alternative Paths
- None
Postconditions
- None
UC-7: Making decoding hypothesis (length of an encoded field)
Summary
- The user can make decoding decisions at runtime.
Rationale
- The size of field inside an encoded structure may not be known in advance, but
only during the process of decoding the message. However the CoDec need to know how to delimit encoded fields so as to decode them separately. When the encoded size of a field can be guessed from another part of the message (e.g. the value of a length field), it can be transmitted to the CoDec by calling SetHypFieldLength() on this value and giving the index of the target field. Actors
- Codet, CoDec
Preconditions
- None
Basic Course of Events
- Step1: while decoding a message, the length of a not-yet decoded field is determined inside a codet
- Step2: the codet calls SetHypFieldLength
- Step3: when the decoder reaches the field it applies the hypothesis given in step 2 and decodes the field
- Step4: if the field cannot be decoded, an exception is thrown
Alternative Paths
- None
Postconditions
- None
UC-8: Making decoding hypothesis (presence of an optional field)
Summary
- The user can make decoding decisions at runtime.
Rationale
- The presence of an optional field inside an encoded record or set may not be
known in advance, but only during the process of decoding the message. However the CoDec need to decide whether to decode the field or not. When the presence size of a field can be guessed from another part of the message (e.g. the value of a flag), it can be transmitted to the CoDec by calling SetHypFieldIsPresent() on this record and giving the index of the target field. Actors
- Codet, CoDec
Preconditions
- None
Basic Course of Events
- Step1: while decoding a message, the presence of a not-yet decoded field is determined inside a codet
- Step2: the codet calls SetHypFieldIsPresent
- Step3: when the decoder reaches the field it applies the hypothesis given in step 2 and decodes or skip the field
Alternative Paths
- None
Postconditions
- None
UC-9: Making decoding hypothesis (variant of a union)
Summary
- The user can make decoding decisions at runtime.
Rationale
- The chosen variant of a union may not be known in advance, but only during the
process of decoding the message. However the CoDec need to decide which field to decode. When the variant can be guessed from another part of the message (e.g. a type field), it can be transmitted to the CoDec by calling SetHypChosenId() on this union and giving the index of the chosen field. Actors
- Codet, CoDec
Preconditions
- None
Basic Course of Events
- Step1: while decoding a message, the variant of a not-yet decoded union is determined inside a codet
- Step2: the codet calls SetHypChosenId
- Step3: when the decoder reaches the union it applies the hypothesis given in step 2 and decodes the chosen field
Alternative Paths
- None
Postconditions
- None
UC-10: Making decoding hypothesis (number of fields in a record of/set of)
Summary
- The user can make decoding decisions at runtime.
Rationale
- The number of elements in a "record of" or a "set of" may not be known in
advance, but only during the process of decoding the message. However the CoDec need to know the size of the encoded "record of" so as to decode the next fields properly. When the number of elements can be guessed from another part of the message (e.g. the value of a length field), it can be transmitted to the CoDec by calling SetHypSize() on this value. Actors
- Codet, CoDec
Preconditions
- None
Basic Course of Events
- Step1: while decoding a message, the number of elements of a not-yet decoded
"record of"/"set of" is determined inside a codet
- Step2: the codet calls SetHypSize
- Step3: when the decoder reaches the value it applies the hypothesis given in step 2 and decodes the right number of elements
- Step4: if all the elements cannot be decoded, an exception is thrown
Alternative Paths
- None
Postconditions
- None
Functional Requirements
FR-1: Naming Convention
Summary
- Mapping between TTCN-3 subtypes and C++ classes.
Rationale
- The mapping between between TTCN-3 subtypes defined in the ATS and C++ classes produced by the CoDec generator and completed with the codets must be clear.
Requirements
- Each TTCN-3 subtype defined by the user maps to a C++ class wearing the same name.
- In order to avoid name clashes,
- generated C++ classes must be defined in a namespace wearing the name of their defining TTCN-3 module
- "module" namespaces are defined in a common parent namespace that contains all the code generated from the ATS
References
FR-2: Common value framework
Summary
- Representation of TTCN-3 values with an Object Oriented framework.
Rationale
- To ease value manipulation and provide abstraction, classes representing
TTCN-3 types should share a common object oriented framework. Requirements
- The framework should have 4 layers
- 1st layer: a root class that can represent any TTCN-3 value
- 2nd layer: separation between primitive types (integer, bitstring, ...) and structured types (record, union, ...)
- 3rd layer: classes representing TTCN-3 types
- 4th layer: classes representing TTCN-3 subtypes (generated from the TTCN-3 sources)
References
FR-3: Default codecs
Summary
- Default codecs are provided for primitive types.
Rationale
- To ease value manipulation and provide abstraction, classes representing
TTCN-3 types should share a common object oriented framework. Requirements
- The default behaviour is to encode and decode the primitive types as follows:
- integer: as signed or unsigned big endian
- bitstring: binary representation of the string
- octetstring: binary representation of the string
- hexstring: binary representation of the string
- charstring: binary representation of the string
- boolean: '1' for true and '0' for false
CD-gen should provide a way of redefining the encoding of primitive types. References
FR-4: Exceptions handling
Summary
- Mechanisms for reporting errors.
Rationale
- Due to the fragmented nature of the final CoDec errors are reported using
exceptions, which can be processed by the user in special codets. Requirements
- Errors must be reported with exceptions.
- Exceptions must provide a detailed human readable report of the error.
- Exceptions can be processed by the user
References
FR-5: CD design compliance
Summary
- The generated CoDec must meet the general requirements for a CoDec.
Rationale
- The generated CoDec is a part of a Test System made of several modules (Test
Executable, System Adapter, Platform Adapter,...). Every module must operate in accordance with the rest of the system. Requirements
- The generated CoDec must be compliant with the section
Technical Documentation: General Design of the CD of the present document. References
Nonfunctional Requirements
NF-1: Documentation
Summary
- Detailed description of developed software
Rationale
- Documentation is a communicable material needed to describe the structure and components implemented. It also includes the programmer manual.
- Correct, up to date, and complete documentation should help in reaching a good quality for:
- Maintainability (CD-gen can be modified at the lowest possible cost)
- Reliability (ability of the CD-gen to perform and maintain its functionality in routine and also in different unexpected circumstances)
Requirements
- The documentation will consist of:
- Software architecture of CD-gen following the developer's guide.
- Dependency with other parties (using a relationship or flow diagrams).
- Flow diagrams for each TCI routine implemented (or functions using TCI routines)
- The documentation will be divided into component parts and for each one the following documentation will be provided:
- Component description.
- Reference to the specification (this document).
- Component peculiarities.
- Component documentation.
- API documented in detail: parameters return value and behavioral description.
- Configuration and installation guidelines.
- Component distribution.
- Source code must be documented according to the rules established to edit Java code (i.e., javadocs). See also developer's guide [7].
References
NF-2: Platform Compatibility
Summary
- Platform requirements to execute CD-gen.
Rationale
- CD-gen subsystem is part of test system that it will be complied and linked jointly in order to get the executable entity. All of them must be according to the same platform requirement.
Requirements
- Operating System; linux 2.6.
- Compiler: gcc 3.4.
- Additional compiler features: POSIX library.
- T3RTS (TTCN-3 Runtime System) will be implemented in C/C++ language. However, T3RTS on Java are currently put on the market and therefore it will be needed to develop an initial study to migrate a CD-gen implemented in C/C++ to Java implementation (e.g. using JNI, Java Native Interface).
References