eJSON

 eJSON project home page

Notes on the reorganization of the eJSON library

Current problems

Current problems are:

  • Patchy documentation.
  • Vistor pattern not trivial to use.
  • Not obvious how to obtain JSON representation.
  • JSON_OBJECT and JSON_ARRAY are cumbersome to use.
  • Dependencies on GOBO classes UC_STRING, DS_HASH_TABLE and DS_LINKED_LIST.
  • Multiple unit test frameworks. No official unit test decided on.

Principles and requirements

Design principles:

  • Intuitive to use!
  • Simple interface but complete in features!
  • Minimial but adequate documentation!
  • Since the library is still in an experimental state, we will allow breaking changes!
  • Implementation improvements due to performance issues will be done after a clean and simple design has been set.

Requirements:

  • POC_CONVERTERS_FACTORY branch shall be merged with trunk.
  • The library interface shall provide 2 main feature categories; convert from Eiffel to JSON and convert from JSON to Eiffel.
  • The library interface shall be able to be accessed by implementation inheritance from a single class.
  • It shall be possibe to easily create and manipulate arbitrary JSON values.
  • It shall be easy to create and manipulate JSON objects and arrays.
  • There shall be no dependencies on Gobo for basic usage of the library.

Undecided issues:

  • Should EJSON_FACTORY raise an exception or set a status flag on conversion failure? Currently an exception is raised.

  • Which test framework to use? Test framework should ideally not depend on Gobo or EiffelStudio!

Design and implementation notes

  • POC_CONVERTERS_FACTORY shall be merged with trunk.
  • Use of Gobo class UC_STRING shall be replaced by use of STRING_32 (ECMA).
  • A copy of the class SHARED_JSON_FACTORY shall be renamed as SHARED_GOBO_EJSON. This will be the main eJSON class to use via non-conforming (=implementation) inheritance for users who want to map JSON arrays to DS_LINKED_LIST and JSON objects to DS_HASH_TABLEs. The class SHARED_GOBO_EJSON and the 2 converter classes will be put in a new top level cluster "gobo".
  • A copy of the class SHARED_JSON_FACTORY shall be renamed SHARED_EJSON and shall not depend on the Gobo classes JSON_DS_HASH_TABLE_CONVERTER or JSON_DS_LINKED_LIST_CONVERTER. This will be the main eJSON class to use via non-conforming (=implementation) inheritance for users who want to map JSON arrays to LINKED_LIST and JSON objects to HASH_TABLEs. Two new converter classes JSON_HASH_TABLE_CONVERTER and JSON_LINKED_LIST_CONVERTER will be added that rely on the ELKS classes HASH_TABLE and LINKED_LIST.
  • The JSON_VALUE class shall have the following feature, and all its descendants shall implement that feature:
    representation: STRING is
            -- UTF-8 encoded Unicode string representation of Current
        deferred
        end
  • Visitor pattern is moved to new cluster "patterns/visitor".
  • JSON_FILE_READER is moved to new cluster "patterns/file_reader".
  • Add the following features to JSON_OBJECT:
    put_string (value, key: STRING)

    put_number (value: NUMERIC; key: STRING)

    put_boolean (value: BOOLEAN, key: STRING)

    put_null (key: STRING)

    put_list (value: JSON_ARRAY; key: STRING)

    put_object (value: JSON_OBJECT; key: STRING)
  • Add the following features to JSON_ARRAY:
    put_string (value: STRING; i: INTEGER)

    put_number (value: NUMERIC; i: INTEGER)

    put_boolean (value: BOOLEAN, i: INTEGER)

    put_null (i: INTEGER)

    put_list (value: JSON_LIST; i: INTEGER)

    put_object (value: JSON_OBJECT; i: INTEGER)
  • Suggested new cluster layout:
json
  library (New cluster for actual eJSON library classes)
    kernel (New cluster. All classes in this cluster may only depend on ECMA Eiffel and FreeELKS).
      json_array.e
      json_boolean.e
      json_null.e
      json_number.e
      json_object.e
      json_string.e
      json_value.e
      ejson.e (Renamed from POC_CONVERTERS_FACTORY: JSON_FACTORY)
      shared_ejson.e (New)
      scanner
        json_parser.e
        json_reader.e
        json_tokens.e
      converters (Renamed from POC_CONVERTERS_FACTORY: converter)
        json_converter.e (From POC_CONVERTERS_FACTORY)
        json_hash_table_converter.e (New)
        json_linked_list_converter.e (New)
    gobo
      shared_gobo_ejson.e (From POC_CONVERTERS_FACTORY: SHARED_JSON_FACTORY)
      converters
        json_ds_hash_table_converter.e (From POC_CONVERTERS_FACTORY)
        json_ds_linked_list_converter.e (From POC_CONVERTERS_FACTORY)    
    extras
      visitor
        JSON_VISITOR (Moved from top level cluster "visitor").
        JSON_PRINTER (Moved from top level cluster "visitor" and renamed from PRINT_JSON_VISITOR).
      file
        JSON_FILE_READER (From top level cluster)
  build (New cluster/directory. Contains various build scripts)
  test
    geant (geant based unit test).
    autotest (AutoTest based unit test).
  example
    rest
  • Suggestion for documentation layout. This is for the User Guide and shall be based on the existing  User Guide.
1. Preface
  1.1 About project and authors
  1.2 Current version and status of eJSON
2. Introduction
  2.1 What is JSON?
  2.2 Advantages
  2.3 Use in Eiffel applications
  -- Data transfer format in Web applications
  -- Data format for persistance
  -- Data format for configuration files.
  2.4 Prerequisites
  -- Supported Eiffel compilers and library dependencies.
  2.5 Installation
  -- How to install
  2.5 Cluster and directory layout
  -- Inform about the purpose of "kernel", "gobo", "extras" etc.
  2.6 A simple example
  -- Create a JSON object and add a JSON number, a string, a boolean, a null value and a list of strings to it.
4. Complete mapping of JSON values to Eiffel values (with examples)
5. The EJSON and SHARED_EJSON classes and adding custom Eiffel/JSON converters (with examples)
6. The SHARED_GOBO_EJSON class (with examples)
7. The eJSON visitor pattern (with examples)
8. The eJSON file reader (with examples)
9. Compiling and running the unit tests
  • Review and improve class and feature documentation.