{"id":13807968,"url":"https://github.com/imrafaelmerino/vertx-values","last_synced_at":"2025-10-30T08:13:37.629Z","repository":{"id":256627444,"uuid":"848707551","full_name":"imrafaelmerino/vertx-values","owner":"imrafaelmerino","description":"vertx-values enhances JSON handling in Vert.x by providing codecs for the immutable JSON objects from the json-values library. It eliminates the need for copying JSON data during transmission over the Event Bus, reducing garbage collection overhead and boosting performance.","archived":false,"fork":false,"pushed_at":"2024-11-23T21:25:20.000Z","size":19969,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-06T17:51:40.936Z","etag":null,"topics":["immutability","java","json","json-values","persistent-data-structure","vertx"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/imrafaelmerino.png","metadata":{"files":{"readme":"docs/README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-28T08:59:38.000Z","updated_at":"2024-12-06T10:15:10.000Z","dependencies_parsed_at":"2024-09-12T05:14:51.672Z","dependency_job_id":"9fd9da9e-ec4c-46e5-9d2e-867f90332f01","html_url":"https://github.com/imrafaelmerino/vertx-values","commit_stats":null,"previous_names":["imrafaelmerino/vertx-values"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/imrafaelmerino/vertx-values","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imrafaelmerino%2Fvertx-values","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imrafaelmerino%2Fvertx-values/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imrafaelmerino%2Fvertx-values/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imrafaelmerino%2Fvertx-values/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/imrafaelmerino","download_url":"https://codeload.github.com/imrafaelmerino/vertx-values/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imrafaelmerino%2Fvertx-values/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263290726,"owners_count":23443651,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["immutability","java","json","json-values","persistent-data-structure","vertx"],"created_at":"2024-08-04T01:01:32.962Z","updated_at":"2025-10-30T08:13:32.606Z","avatar_url":"https://github.com/imrafaelmerino.png","language":"Java","funding_links":["https://www.buymeacoffee.com/imrafaelmerino"],"categories":["Miscellaneous"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./logo/package_twitter_swe2n4mg/color1/text/profilepicture/color1_textlogo_light_background.png\" alt=\"Logo\" width=\"300\" height=\"300\" /\u003e\n\u003c/p\u003e\n\n\"_Immutability Changes Everything._\"\n**Pat Helland**\n\n[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-%E2%98%95%20Support-yellow)](https://www.buymeacoffee.com/imrafaelmerino)\n\n[![Maven](https://img.shields.io/maven-central/v/com.github.imrafaelmerino/vertx-json-values/2.0.0)](https://search.maven.org/artifact/com.github.imrafaelmerino/vertx-json-values/2.0.0/jar)\n\n- [Goal](#goal)\n- [Explanation](#exp)\n- [How-to](#howto)\n- [Performance](#perf)\n- [Requirements](#requirements)\n- [Installation](#inst)\n\n## \u003ca name=\"goal\"\u003e\u003ca/\u003e Goal\n\nThe goal of this section is to address a common practice in Vertx, which involves sending messages in JSON format due to\nits simplicity and widespread compatibility across various programming languages supported by Vertx. However, a\nsignificant challenge arises when sending messages as JsonObject or JsonArray types, as Vertx is required to create a\ncopy of the message each time it's sent over the Event Bus. This process becomes increasingly detrimental to\nperformance, especially with larger JSON payloads, and places a considerable burden on the Garbage Collector.\n\nTo mitigate these issues, vertx-values steps in to provide support for transmitting immutable JSON objects from\njson-values. This library offers a genuinely immutable JSON representation achieved through the use of persistent data\nstructures and adheres to functional programming principles. Not only does json-values enable the creation, validation,\ngeneration, and manipulation of JSON data, but it also offers a straightforward and functional API for these tasks. The\nultimate goal is to enhance the efficiency and performance of JSON message transmission within Vertx applications.\n\n## \u003ca name=\"exp\"\u003e\u003ca/\u003e Explanation\n\nEvery type (`Integer`, `String`, `JsonObject`, `JsonArray`, `Buffer`, etc.) that can be sent\nacross the Event Bus has an\nassociated [MessageCodec](https://vertx.io/docs/apidocs/io/vertx/core/eventbus/MessageCodec.html).\nA `MessageCodec` is where it's defined how to serialize\nand deserialize a message. A third method called `transform` is also\nimplemented in this class. When a verticle sends a message locally to the EB, Vertx intercepts\nthat message and calls its codecs `transform` method.\n\nGo to the source\npackage [io.vertx.core.eventbus.impl.codecs](https://vertx.io/docs/apidocs/io/vertx/core/eventbus/impl/codecs/package-frame.html)\nto check out what types Vertx supports. The good thing is that you can define your codecs\nto send messages of new types to the EB.\n\nThe default JSONs implemented in Vertx with **Jackson**, [JsonObject](https://vertx.io/docs/apidocs/io/vertx/core/json/JsonObject.html) and\n[JsonArray](https://vertx.io/docs/apidocs/io/vertx/core/json/JsonArray.html), have the\ncodecs [JsonObjectMessageCodec](https://vertx.io/docs/apidocs/io/vertx/core/eventbus/impl/codecs/JsonObjectMessageCodec.html)\nand [JsonArrayMessageCodec](https://vertx.io/docs/apidocs/io/vertx/core/eventbus/impl/codecs/JsonArrayMessageCodec.html).\nLet's\ntake a look at their `transform` method implementation:\n\n```code\n\n// Vertx impl \npublic JsonObject transform(JsonObject message) {\n    return message.copy();\n}\n\n```\n\nSince **Jackson** is not immutable at all, the `transform` method\nhas to make a copy of the message before sending it to the EB. Otherwise, we would have\na shared reference to an object among independent Verticles, which would be\na nightmare and violates some of the most basic principles of message-passing\narchitectures.\n\nAs I pointed out before, making a copy every time a message is sent is inefficient and put more pressure on\nthe Garbage Collector, especially if you have a large number of Verticles communicating one to\neach other.\n\nvertx-values provides codecs to send [json-values](https://github.com/imrafaelmerino/json-values) across the EB.\nTake a look at the `transform` method of its codecs:\n\n```code\n\n// vertx-values impl\npublic JsObj transform(final JsObj message) {\n   return message;\n}\n\n```\n\n**As you can see, it returns the same message without making any copy**.\nAnd if that was not enough, immutable data structures have a lot of benefits,\nespecially in concurrent programs and architectures based on the actor model like Vertx.\n\n## \u003ca name=\"howto\"\u003e\u003ca/\u003e How to\n\nRegistering the codecs from vertx-values is a straightforward process that involves deploying a Verticle. Here's how you\ncan achieve this in Vertx:\n\n```code  \nimport vertx.values.codecs.RegisterJsValuesCodecs;\n\nvertx.deployVerticle(new RegisterJsValuesCodecs(), \n                     r -\u003e System.out.println(\"Registered codecs!\")\n                    );\n                    \n```\n\nWhen you deploy the codecs Verticle, it registers the necessary codecs for vertx-values. If you attempt to register the\ncodecs more than once, Vertx will detect this and prevent duplicate registrations, ensuring that you don't inadvertently\noverwrite or interfere with previously registered codecs.\n\nThis simple process allows you to enable the use of vertx-values' immutable JSON representations in your Vertx\napplication, improving message transmission efficiency and reducing the load on the Garbage Collector.\n\n## \u003ca name=\"perf\"\u003e\u003ca/\u003e Performance\n\nLet's illustrate the efficiency gains of using vertx-values with a practical example. We'll create a Verticle named \"\nbounce\" that echoes back the messages it receives:\n\n``` code\n\n vertx.eventBus()\n      .consumer(\"bounce\", \n                message -\u003e message.reply(message.body())\n               )\n\n```\n\nNow, we'll send two types of messages to the \"bounce\" Verticle for comparison:\n\n- A JSON object: obj\n- A JSON array containing four identical objects: [obj, obj, obj, obj]\n\nWe will measure the performance of these message transmissions using both the JSON representation from Vertx and the\nJSON from json-values. To ensure accurate benchmarking, we'll employ jmh, a reliable Java benchmarking tool.\n\nI ran this benchmark test eight times on my computer (MacBook Pro with Apple M1 chip, 8 cores, 16GB LPDDR4 RAM) and\nrecorded the results, which I subsequently uploaded to JMH Visualizer. Here's the chart summarizing the outcomes:\n\n\n\u003cimg src=\"./sending_one_message_results.png\" alt=\"sending messages to the event bus\"/\u003e\n\n\nThe chart reveals a clear performance advantage when using vertx-values. Whether sending a single JSON object or a JSON\narray four times larger, the results remain consistently efficient. This efficiency is attributed to the absence of\nmessage copying before transmission, a feature inherent to vertx-values.\n\nConversely, when transmitting JSON objects from Vertx, performance declines by approximately 40%, and sending JSON\narrays causes a severe performance degradation. This degradation is primarily due to the time-consuming process of\ncopying larger objects. These findings underscore the benefits of adopting vertx-values for improved efficiency in your\nVertx applications, particularly when handling substantial JSON payloads.\n\n## \u003ca name=\"requirements\"\u003e\u003ca/\u003e Requirements\n\n- For versions prior to 0.7, json-values requires Java 8 or later. Please note that only fixes are accepted for these\n  versions.\n- For versions starting from 0.8 and beyond, json-values mandates Java 17 or later.\n\n## \u003ca name=\"inst\"\u003e\u003ca/\u003e Installation\n\nTo include json-values in your project, add the corresponding dependency to your build tool based on your Java version:\n\nFor Java 8 or higher:\n\n```xml\n\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.github.imrafaelmerino\u003c/groupId\u003e\n    \u003cartifactId\u003evertx-json-values\u003c/artifactId\u003e\n    \u003cversion\u003e0.7\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nFor Java 17 or higher:\n\n```xml\n\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.github.imrafaelmerino\u003c/groupId\u003e\n    \u003cartifactId\u003evertx-json-values\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nFor Java 21 or higher:\n\n```xml\n\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.github.imrafaelmerino\u003c/groupId\u003e\n    \u003cartifactId\u003evertx-json-values\u003c/artifactId\u003e\n    \u003cversion\u003e2.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n\nChoose the appropriate version according to your Java runtime.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimrafaelmerino%2Fvertx-values","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimrafaelmerino%2Fvertx-values","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimrafaelmerino%2Fvertx-values/lists"}