{"id":32191567,"url":"https://github.com/onyx-platform/onyx-java","last_synced_at":"2025-10-22T01:43:21.544Z","repository":{"id":62433996,"uuid":"46595778","full_name":"onyx-platform/onyx-java","owner":"onyx-platform","description":"The Java API for Onyx","archived":false,"fork":false,"pushed_at":"2017-06-01T03:15:46.000Z","size":919,"stargazers_count":5,"open_issues_count":1,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-10-22T01:43:21.154Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/onyx-platform.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-11-21T01:17:52.000Z","updated_at":"2018-06-14T05:39:28.000Z","dependencies_parsed_at":"2022-11-01T21:16:11.126Z","dependency_job_id":null,"html_url":"https://github.com/onyx-platform/onyx-java","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/onyx-platform/onyx-java","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onyx-platform%2Fonyx-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onyx-platform%2Fonyx-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onyx-platform%2Fonyx-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onyx-platform%2Fonyx-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onyx-platform","download_url":"https://codeload.github.com/onyx-platform/onyx-java/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onyx-platform%2Fonyx-java/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280365580,"owners_count":26318385,"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","status":"online","status_checked_at":"2025-10-21T02:00:06.614Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-10-22T01:43:16.878Z","updated_at":"2025-10-22T01:43:21.536Z","avatar_url":"https://github.com/onyx-platform.png","language":"Java","funding_links":[],"categories":["Memory and concurrency"],"sub_categories":[],"readme":"# Onyx-Java\n\nOnyx-Java is designed to allow users who write Java code to use the Onyx Platform.\n\u003cbr\u003e\nThe package provides the following features:\n\u003cul\u003e\n\u003cli\u003eA simple Java interface for the Onyx Platform core API\u003c/li\u003e\n\u003cli\u003eUtilities for manipulating Clojure maps directly in Java\u003c/li\u003e\n\u003cli\u003eTools to simplify use of core.async plugins\u003c/li\u003e\n\u003cli\u003eAffordances for inclusion of pure Java classes in a workflow\u003c/li\u003e\n\u003c/ul\u003e\n\u003cbr\u003e\n\n## Installation\n\n```\n[org.onyxplatform/onyx-java \"0.1.0\"]\n```\n\n## Build Status\n\nCircleCI Tests:  [![CircleCI](https://circleci.com/gh/RBerkheimer/onyx-java.svg?style=svg)](https://circleci.com/gh/RBerkheimer/onyx-java)\n\n## API Docs\n\nAutomatically generated documentation for the Java API can be found [here](https://rberkheimer.github.io/onyx-java/).\n\n## Overview\nOnyx-Java mirrors the Onyx Platform core API by providing a Java equivalent for each component of an Onyx workflow. This means the parts of Onyx such as Catalogs, Lifecycles, Jobs, Tasks, and so on, each have a new equivalent Java class.\n\u003cbr\u003e\u003cbr\u003e\nThese classes provide methods for adding entries to components, such as adding tasks to catalogs, edges to workflows, catalogs to jobs, etc.\n\u003cbr\u003e\u003cbr\u003e\n\u003cstrong\u003e\nPlease note:\n\u003c/strong\u003e\n\u003cbr\u003e\nOnyx-Java does not validate semantic correctness of entries - parameter and type checking enforcement is left to Onyx Platform itself, which takes place at runtime.\n\u003cbr\u003e\nThis means that it is up to the user to refer to the Onyx Platform information model documentation to ensure that they are passing the expected parameters of types expected by the Onyx Platform.\n\u003cbr\u003e\u003cbr\u003e\n\n### Utilities\n\nOnyx-Java provides the following utilities for high-level package consumption:\n\n#### Onyx Environment\n\nThe Onyx Platform is powerful, but using it can be complex - the platform allows for multiple configuration options, needs to make several calls during spin up and shutdown, and requires that persistent peer and environment metadata is available to core API calls, such as job execution.\n\u003cbr\u003e\nOnyx-Java provides a utility class called *OnyxEnv* to simplify management of the environment and provide proxying methods to encapsulate this complexity. It provides convenience functions for setting up, controlling, and using the Onyx environment and the jobs that the environment contains.\n\n#### Maps\n\nThe native language of the Onyx Platform is Clojure, and the ubiquitous data structure that it uses for all communication is an implementation of the IPersistentMap. While Java can manipulate these maps directly, it is often easier or preferable to use tools that mirror the natural way Onyx is used to using for argument manipulation.\n\u003cbr\u003e\nOnyx-Java provides this ability in the utility class *MapFns*, which offers pure Java versions of useful Clojure map manipulation functions, such as get, getIn, assoc, dissoc, and others, making it easier to directly manipulate the arguments used by Onyx.\n\u003cbr\u003e\nMapFns also provides support for loading edn files that contain map specifications, allowing the environment, peer configuration, and task specifications to be configured rather than coded. This promotes highly patterned design, allows high reuse, and guarantees efficiency.\n\u003cbr\u003e\u003cbr\u003e\n\n#### Core Async\n\nThe Onyx Platform provides excellent support for asynchronous task execution via a core-async plugin.\n\u003cbr\u003e\nCore-async jobs in Onyx are common and stereotyped, and setting them up generally includes rewriting boilerplate code.\n\u003cbr\u003e\u003cbr\u003e\nOnyx-Java provides the ability to set up these common core-async jobs up automatically, via the utility classes *AsyncCatalog* and *AsyncLifecycles*. These two classes encapsulate generating the correct catalog and lifecycle entries for setting up, using, and collecting the resulting output from async channels. This utility provides a way for users to avoid writing boilerplate code in this common scenario.\n\u003cbr\u003e\u003cbr\u003e\n\n#### Java Objects\n\nOnyx-Java allows pure Java objects to be added to workflows and jobs as tasks by providing a simple abstract base class for user classes to extend and a utility class to add objects created by those user classes to a catalog.\n\u003cbr\u003e\u003cbr\u003e\nThe abstract base class *OnyxFn* takes a Clojure map as the single argument and provides an abstract method that consumes the map. This abstract method is overridden by the user class.\n\u003cbr\u003e\nObject based on the user class can then be added to the job catalog using the *BindUtils*, which will create a new instance of the class at runtime. BindUtils also provides methods for releasing the instances once they are no longer needed.\n\u003cbr\u003e\u003cbr\u003e\n\n## Package Use\n\nOnyx-Java is designed to be used in a way that mirrors as closely as possible the traditional use of Onyx Platform while being implemented in a way that reflects Java convention. This makes it easy for Java users to quickly feel comfortable using the package without obfuscating the power of the Onyx Platform itself.\n\u003cbr\u003e\nJust as in Onyx Platform, users have the responsibility to set up jobs and job components, initialize environment and peer configurations, and control job execution;\nhowever, unlike Onyx Platform, Onyx-Java users can do this using an API written entirely in Java that can be implemented in a conventional Java way.\n\u003cbr\u003e\u003cbr\u003e\n\n### Basic\n\nThis section outlines out a general approach for using Onyx-Java by providing a working bare-bones implementation.\n\u003cbr\u003e\nMore detailed examples can be found in the test documentation [here](docs/readme/expanded_use_example.md).\n\u003cbr\u003e\u003cbr\u003e\n\n```java\nimport clojure.lang.IPersistentMap;\nimport clojure.lang.PersistentVector;\n\nimport org.onyxplatform.api.java.OnyxEnv;\nimport org.onyxplatform.api.java.OnyxMap;\nimport org.onyxplatform.api.java.OnyxVector;\nimport org.onyxplatform.api.java.Job;\nimport org.onyxplatform.api.java.Catalog;\nimport org.onyxplatform.api.java.Lifecycles;\n\nimport org.onyxplatform.api.java.utils.AsyncCatalog;\nimport org.onyxplatform.api.java.utils.AsyncLifecycles;\n\nimport org.onyxplatform.api.java.instance.BindUtils;\n\n\n// Configure and start the Onyx Platform runtime.\n//\nOnyxEnv onyxEnv = new OnyxEnv(\"onyx-env.edn\", true);\n\n// Constuct a simple single-function job that uses\n// a pure Java object for segment processing backed\n// by core.async.\n//\n\nJob job = new Job(onyxEnv.taskScheduler());\n\njob.addWorkflowEdge(\"in\", \"pass\");\njob.addWorkflowEdge(\"pass\", \"out\");\n\nCatalog c = job.getCatalog();\nint batchSize = 5;\nint batchTimeout = 50;\n\n// Add core.async plugin catalog entries\nAsyncCatalog.addInput(c, \"in\", batchSize, batchTimeout);\nAsyncCatalog.addOutput(c, \"out\", batchSize, batchTimeout);\n\n// Use the fully-qualified onyxplatform.test.PassFn class\n//\nBindUtils.addFn(c, \"pass\", batchSize, batchTimeout,\n                   \"onyxplatform.test.PassFn\", MapFns.emptyMap());\n\n// Add accompanying core.async plugin lifecycles\nLifecycles lc = job.getLifecycles();\nAsyncLifecycles.addInput(lc, \"in\");\nAsyncLifecycles.addOutput(lc, \"out\");\n\nOnyxMap m = new OnyxMap().addKeywordParameter(\"test-input\", \"TEST\");\nOnyxVector inputs = new OnyxVector().addElement(m);\n\nIPersistentMap job-meta = onyxEnv.submitAsyncJob(job, inputs);\nPersistentVector output = AsyncLifecycles.collectOutputs(job, \"out\");\n\n// Release the cached instance\nBindUtils.releaseInstances(job);\n```\n\n\n### Java Objects\n\nInclusion of Java task objects in a workflow requires that you provide a concrete subclass of *OnyxFn*:\n\u003cbr\u003e\u003cbr\u003e\n\n```java\npackage onyxplatform.test;\n\nimport clojure.lang.IPersistentMap;\n\nimport org.onyxplatform.api.java.instance.OnyxFn;\n\npublic class PassFn extends OnyxFn {\n\n        public PassFn(IPersistentMap m) {\n                super(m);\n        }\n\n        public Object consumeSegment(IPersistentMap m) {\n                return m;\n        }\n}\n```\n\n\u003cbr\u003e\nThen, using the fully qualified name of your class and any constructor parameters, you use *BindUtils* to generate a matching catalog entry:\n\u003cbr\u003e\u003cbr\u003e\n\n```java\nimport org.onyxplatform.api.java.instance.BindUtils;\n\nCatalog catalog = new Catalog();\n\nString taskName = \"pass\";\nString fullyQualifiedName = \"onyxplatform.test.PassFn\";\nIPersistentMap ctrArgs = MapFns.emptyMap();\n\nint batchSize = 5;\nint batchTimeout = 50;\n\nBindUtils.addFn(catalog, batchSize, batchTimeout, fullyQualifiedName, ctrArgs);\n```\n\n\u003cbr\u003e\nThis will add the appropriate entry to bind task processing to a specific instance of your class that is loaded and called at job runtime.\n\u003cbr\u003e\u003cbr\u003e\nYou are responsible for instance management as your instances are cached in memory. This is accomplished via the release static methods provided by *BindUtils*:\n\u003cbr\u003e\u003cbr\u003e\n\n```java\nBindUtils.releaseInstances(job);\n```\n\n#### **NOTE**\n\nThere are parallel clojure namespaces and functions that provide affordances for clojure-based workflows;\n\u003cbr\u003e\ni.e., Onyx-Java does not prohibit users from writing the system in Java while running tasks that are written in Clojure.\n\u003cbr\u003e\u003cbr\u003e\n\n\n## License\n\nCopyright © 2016 Distributed Masonry\n\nDistributed under the Eclipse Public License either version 1.0 or (at\nyour option) any later version.\u003cbr\u003e\n\u003cbr\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonyx-platform%2Fonyx-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonyx-platform%2Fonyx-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonyx-platform%2Fonyx-java/lists"}