{"id":23958217,"url":"https://github.com/katarinamolotova/javacent","last_synced_at":"2025-04-13T05:53:13.508Z","repository":{"id":251476766,"uuid":"837528898","full_name":"katarinamolotova/javacent","owner":"katarinamolotova","description":"Java library to communicate with Centrifugo HTTP API.","archived":false,"fork":false,"pushed_at":"2024-09-02T13:30:37.000Z","size":509,"stargazers_count":4,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-13T05:53:08.493Z","etag":null,"topics":["centrifugo","http-client","java","library"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/katarinamolotova.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-03T08:43:09.000Z","updated_at":"2024-12-09T09:23:19.000Z","dependencies_parsed_at":"2024-08-27T13:17:56.416Z","dependency_job_id":null,"html_url":"https://github.com/katarinamolotova/javacent","commit_stats":null,"previous_names":["katarinamolotova/javacent"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katarinamolotova%2Fjavacent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katarinamolotova%2Fjavacent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katarinamolotova%2Fjavacent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/katarinamolotova%2Fjavacent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/katarinamolotova","download_url":"https://codeload.github.com/katarinamolotova/javacent/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248670503,"owners_count":21142901,"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":["centrifugo","http-client","java","library"],"created_at":"2025-01-06T17:30:17.747Z","updated_at":"2025-04-13T05:53:13.484Z","avatar_url":"https://github.com/katarinamolotova.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# javacent library\n\nJava SDK to communicate with Centrifugo v5 HTTP API. Java \u003e= 8 supported.\n\nTo add to your maven project:\n```\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.opensolutionlab.httpclients\u003c/groupId\u003e\n    \u003cartifactId\u003ejavacent\u003c/artifactId\u003e\n    \u003cversion\u003e2.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Usage\n\nFirst of all, see the description of Centrifugo [server API](https://centrifugal.dev/docs/server/server_api) in the documentation. This library also supports API extensions provided by Centrifugo PRO.\n\nThe library contains `CentrifugoClient` to work with Centrifugo HTTP server API.\n\n## Configuration\n\nTo configure the library, you need to create a configuration class `CentrifugoConfigurations`.\n\nPossible configurations:\n* `apiKey` - Centrifugo HTTP API key for auth (default is empty string)\n* `apiPort` - Centrifugo port (defult is `8000`)\n* `apiUrl` - Centrifugo URL address without port (defult is `http://localhost`)\n* `apiInsecure` - Centrifugo HTTP API is insecure. If it is true, `apiKey` will be an empty string (default is `false`)\n* `apiHandlerPrefix` - Centrifugo HTTP API URL prefix (default is `/api`)\n\nYou can use a builder to create it. The fields that you do not specify will be filled with default values. For example:\n\n```java\nCentrifugoConfigurations configurations = CentrifugoConfigurations\n        .builder()\n        .apiKey(\"centrifugo\")\n        .apiUrl(\"http://localhost\")\n        .apiPort(\"8000\")\n        .build();\n```\n\n## Usage example\n\n```java\nimport org.opensolutionlab.httpclients.clients.CentrifugoClient;\n\npublic class DemoApplication {\n\n    public static void main(String[] args) {\n        CentrifugoConfigurations configurations = CentrifugoConfigurations\n                .builder()\n                .apiKey(\"centrifugo\")\n                .build();\n        CentrifugoClient client = new CentrifugoClient(configurations);\n        client.publish(\"Hello World!\", \"channel\");\n    }\n\n}\n```\n\n## Handling errors\n\nThis library raises exceptions if sth goes wrong. All exceptions are subclasses of CentrifugoException.\n\n* `CentrifugoException` - base class for all exceptions\n* `CentrifugoNetworkException` - raised in case of network related errors (connection refused)\n* `CentrifugoTransportException` - raised in case of transport related errors (HTTP status code is not 2xx)\n* `CentrifugoTimeoutException` - raised in case of timeout\n* `CentrifugoUnauthorizedException` - raised in case of unauthorized access (signal of invalid API key)\n* `CentrifugoDecodeException` - raised in case of server response deserialize error\n* `CentrifugoApiResponseException` - raised in case of API response error (i.e. error returned by Centrifugo itself, you can inspect code and message returned by Centrifugo in this case)\n\nNote, that `BroadcastRequest` and `BatchRequest` are quite special – since they contain multiple commands in one request, \nhandling `CentrifugoApiResponseException` is still required, but not enough – you also need to manually iterate over the results to check for individual errors. \nFor example, one publish command can fail while another one can succeed. For example:\n\n```java\nimport org.opensolutionlab.httpclients.clients.CentrifugoClient;\n\npublic class DemoApplication {\n\n    public static void main(String[] args) {\n        CentrifugoClient client = new CentrifugoClient();\n        \n        client.broadcast(Arrays.asList(\"1\", \"2\"), \"Hello!\");\n        /*\n         *  BroadcastResult(\n         *      responses = {\n         *          PublishResponse(error = null, result = PublishResult(offset = 7, epoch = \"rqKx\")),\n         *          PublishResponse(error = null, result = PublishResult(offset = 7, epoch = \"nUrf\"))\n         *      }\n         *  )\n         */\n\n        client.broadcast(Arrays.asList(\"invalid:1\", \"2\"), \"Hello!\");\n        /*\n         *  BroadcastResult(\n         *      responses = {\n         *          PublishResponse(error = Error(code = 102, message = \"unknown channel\"), result = null),\n         *          PublishResponse(error = null, result = PublishResult(offset = 8, epoch = \"nUrf\"))\n         *      }\n         *  )\n         */\n    }\n}\n```\n\nI.e. `javacent` library does not raise exceptions for individual errors in BroadcastRequest or BatchRequest, \nonly for top-level response error, for example, sending empty list of channels in broadcast:\n\n```\nclient.broadcast(Arrays.emptyList(), \"\");\n\norg.opensolutionlab.httpclients.exceptions.CentrifugoApiResponseException: Server API response error #107: bad request\n    ...\n```\n\nYou can get the error code from all network exceptions for analysis:\n\n```\ntry {\n    ...\n} catch (CentrifugoNetworkException ex) {\n    int code = ex.getResponseCode();\n    ...\n}\n```\n\nSo this all adds some complexity, but that's the trade-off for the performance and efficiency of these two methods. \nYou can always write some convenient wrappers around javacent library to handle errors in a way that suits your application.\n\n## License\n\nThis repository is released under version 2.0 of the\n[Apache License](https://www.apache.org/licenses/LICENSE-2.0).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkatarinamolotova%2Fjavacent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkatarinamolotova%2Fjavacent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkatarinamolotova%2Fjavacent/lists"}