# Overview

This library provides a low-power layout engine.

The version of the sync protocol implemented by the library is specified by a constant in the `MessageHandler` class.

# Usage

Add the following line to your `module.ivy`:

    @MMM_DEPENDENCY_DECLARATION@

# Requirements

This library requires the following Foundation Libraries:

    @FOUNDATION_LIBRARIES_LIST@

To work on Simulator, this library requires Architecture version 7.20.5 (or higher 7.x) or 8.1.0 (or higher 8.x).

This library also requires the UTF-8 character encoding to be embedded, otherwise a `java.io.UnsupportedEncodingException` exception will be thrown during watchface sync or watchface loading.
Applications using this library must set the option `cldc.encoding.utf8.included` to `true`.

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

N/A.

# Restrictions

None.

# Sync Maintenance

## Messages Specification

Any modification should be reflected in the specification documents:

- New message types
- Modification to the format of existing messages
- New error codes
- Data flow and error handling

## Unit Testing

Each class of the sync package is tested in a separate class, named after the class: for example, `TestMessageHandler`
for `MessageHandler`.

### Code Coverage

The unit tests should cover most of the code, aiming at 100% code coverage.
The testsuite is configured so that the code coverage report is generated.

### Use case: adding a new message type

1. Add a new test class for the new `Message` class (e.g., `TestSomeMessage` for a `SomeMessage` class).
2. Test each method of the class, with a special attention to testing the message deserialization/serialization methods:
    - The `TestUtilities` class provides a `testDeserialize()` method to test the deserialization of a collection of
      payloads. It is handy for testing all the possible deserialization issues.
    - Add a method in the class `DataProvider` for getting the payloads to test (e.g., `getSomePayloads()`). The
      returned array contains a CBOR hexadecimal string representing a payload and the expected error code.
    - For generating the CBOR payload, you may use third party tools like https://cbor.me/ than can convert a JSON into
      a CBOR hexadecimal string.
    - Try to generate a payload for each possible error.
3. Add new tests in the class `TestMessageHandler` to test how this new message is handled in the
   class `MessageHandler`:
    - The goal is to check that the message is handled as expected whatever the payload submitted (correct or
      incorrect): response sent, errors, data integrity, listener events, etc.
4. Update the `TestMessage` class to ensure that the new message type is taken into account:
    - Add the new message type in the method `DataProvider.getMessageTypes()`.
    - Update the test method `TestMessage.testOfUnknownType()` to reflect the message type range.

---
_Markdown_  
_Copyright 2023-2024 MicroEJ Corp. All rights reserved._  
_MicroEJ Corp. PROPRIETARY/CONFIDENTIAL. Use is subject to license terms._