{"id":17047123,"url":"https://github.com/jhalterman/sarge","last_synced_at":"2025-10-17T16:01:42.297Z","repository":{"id":3376454,"uuid":"4424037","full_name":"jhalterman/sarge","owner":"jhalterman","description":"Erlang style object supervision for the JVM","archived":false,"fork":false,"pushed_at":"2023-04-12T01:45:45.000Z","size":290,"stargazers_count":125,"open_issues_count":8,"forks_count":14,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-26T09:51:12.207Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"eBayClassifiedsGroup/PanteraS","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jhalterman.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2012-05-23T18:55:05.000Z","updated_at":"2024-09-12T13:01:24.000Z","dependencies_parsed_at":"2022-08-24T13:39:36.266Z","dependency_job_id":null,"html_url":"https://github.com/jhalterman/sarge","commit_stats":{"total_commits":100,"total_committers":5,"mean_commits":20.0,"dds":0.08999999999999997,"last_synced_commit":"5b607d23bc37e110d368bd867033b377e20e020d"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhalterman%2Fsarge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhalterman%2Fsarge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhalterman%2Fsarge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhalterman%2Fsarge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jhalterman","download_url":"https://codeload.github.com/jhalterman/sarge/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248586217,"owners_count":21128998,"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":[],"created_at":"2024-10-14T09:48:31.477Z","updated_at":"2025-10-17T16:01:42.223Z","avatar_url":"https://github.com/jhalterman.png","language":"Java","funding_links":[],"categories":["容错组件"],"sub_categories":[],"readme":"# Sarge\n\n[![Build Status](https://github.com/jhalterman/sarge/workflows/build/badge.svg)](https://github.com/jhalterman/sarge/actions)\n[![Maven Central](https://img.shields.io/maven-central/v/net.jodah/sarge.svg?maxAge=60\u0026colorB=53C92E)][maven] \n[![License](http://img.shields.io/:license-apache-brightgreen.svg)](http://www.apache.org/licenses/LICENSE-2.0.html)\n[![JavaDoc](https://img.shields.io/maven-central/v/net.jodah/sarge.svg?maxAge=60\u0026label=javadoc\u0026color=blue)](https://jodah.net/sarge/javadoc)\r\n\r\n*Simple object supervision (for when stuff goes wrong)*\n\nSarge creates *supervised* objects which *automatically* handle failures when they occur by performing retries, state resets, and failure escalation, allowing for easy and robust fault tolerance with little effort.\n\n## Usage\r\n\nSarge handles failures according to a `Plan` which takes an exception and directs Sarge to do something with it. Creating a `Plan` is straightforward:\n\n```java\nPlan plan = Plans\n  .retryOn(TimeoutException.class, 5, Duration.mins(1))\n  .escalateOn(ConnectionClosedException.class)\n  .rethrowOn(IllegalArgumentException.class, IllegalStateException.class)\n  .make();\n```      \n      \nThis Plan retries any method invocations that fail with a TimeoutException, escalates any ConnectionClosedExceptions, and rethrows any IllegalArgumentExceptions and IllegalStateExceptions.      \n\n#### Supervision\n\nWith our `Plan` in hand, we can create a *supervised* object:\n\n```java\nSarge sarge = new Sarge();\nMailService service = sarge.supervised(MailService.class, plan);\n```    \n\nSupervision is automatically applied according to the plan when any exception occurs while invoking a method against the object:\n    \n```java\n// Failures are handled according to the plan\nservice.sendMail();\n```\n    \n#### Hierarchical supervision\n\nSarge can create a parent/child supervision hierarchy where the `Supervisor`'s plan is applied to any failures that occur in the child:\r\n\n```java\nclass Parent implements Supervisor {\n  @Override\n  public Plan plan(){\n    return Plans\n      .retryOn(TimeoutException.class, 5, Duration.mins(1))\n      .escalateOn(ConnectionClosedException.class)\n      .make();\n  }\n}\n \nParent parent = new Parent(); \nSarge sarge = new Sarge();\n \n// Create a new Child that is supervised by the parent\nChild child = sarge.supervised(Child.class, parent);\n```    \n    \nWe can link additional supervisable objects into a parent-child supervision hierarchy, which will handle any failures that are escalated:\n\n```java\nParent parent = sarge.supervisable(Parent.class);\nsarge.supervise(parent, uberParent);\n```\n\t\n#### More on plans\n\nAside from the `Plans` class, Plans can also be constructed directly by implementing the `Plan` interface and returning the desired `Directive` for handling each failure:\n\n```java\nPlan plan = new Plan() {\n  public Directive apply(Throwable cause) {\n    if (cause instanceof TimeoutException)\n      return Directive.Retry(5, Duration.min(1));\n    if (cause instanceof ConnectionClosedException)\n      return Directive.Escalate;\n  }\n};\n```\n    \n#### Lifecycle hooks\n\nLifecycle hooks allow supervised objects to be notified prior to a supervision directive being carried out, allowing an object to reset its internal state if necessary:\n\n```java\nclass SupervisedService implements PreRetry {\n  @Override\n  public void preRetry(Throwable reason) {\n    if (reason instanceof ConnectionClosedException)\n      connect();\n  }\n}\n```\n\n#### 3rd Party Integration\n\nBy default, supervised objects must be instantiated by Sarge since they require instrumentation. As an alternative, we can delegate instantiation of supervised objects to other libraries such as [Spring](https://github.com/jhalterman/sarge/tree/master/src/test/java/net/jodah/sarge/integration/SpringIntegrationTest.java) or [Guice](https://github.com/jhalterman/sarge/tree/master/src/test/java/net/jodah/sarge/integration/GuiceIntegrationTest.java) by hooking into Sarge's [SupervisedInterceptor](https://jhalterman.github.com/sarge/javadoc/net/jodah/sarge/SupervisedInterceptor.html). Have a look at the [tests](https://github.com/jhalterman/sarge/tree/master/src/test/java/net/jodah/sarge/integration) for examples on how to integrate 3rd party libraries.\n\n#### Logging\n\nLogging is provided via the [slf4j](http://www.slf4j.org/) [API](http://www.slf4j.org/apidocs/index.html). Invocation exceptions are logged at the ERROR level and include only the exception message. Full exception logging can be enabled by setting the DEBUG log level for the `net.jodah.sarge` category.\n\n## Docs\n\nJavaDocs are available [here](https://jodah.net/sarge/javadoc).\n\n## Limitations\n\nSince Sarge relies on runtime bytecode generation to create supervised objects by subclassing them, it cannot supervise classes that are _final_, _protected_ or _private_, or methods that are _final_ or _private_.\n\n## Thanks\n\nSarge was inpsired by [Erlang OTP's](http://www.erlang.org/doc/design_principles/des_princ.html) supervision trees and [Akka's supervision](http://akka.io) implementation. Thanks to the their contributors for the great work.\r\n\r\n## License\r\n\r\nCopyright 2012-2013 Jonathan Halterman - Released under the [Apache 2.0 license](http://www.apache.org/licenses/LICENSE-2.0.html).\n\n[maven]: https://maven-badges.herokuapp.com/maven-central/net.jodah/sarge","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjhalterman%2Fsarge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjhalterman%2Fsarge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjhalterman%2Fsarge/lists"}