{"id":20841504,"url":"https://github.com/wavesoftware/java-eid-exceptions","last_synced_at":"2025-07-17T02:03:31.196Z","repository":{"id":35120378,"uuid":"39313959","full_name":"wavesoftware/java-eid-exceptions","owner":"wavesoftware","description":"EID Runtime Exceptions and Utilities","archived":false,"fork":false,"pushed_at":"2018-12-29T21:53:26.000Z","size":238,"stargazers_count":11,"open_issues_count":3,"forks_count":7,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2024-10-19T03:18:29.378Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://wavesoftware.github.io/java-eid-exceptions","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/wavesoftware.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-07-18T21:53:04.000Z","updated_at":"2021-02-02T09:41:15.000Z","dependencies_parsed_at":"2022-09-16T14:11:11.542Z","dependency_job_id":null,"html_url":"https://github.com/wavesoftware/java-eid-exceptions","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wavesoftware%2Fjava-eid-exceptions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wavesoftware%2Fjava-eid-exceptions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wavesoftware%2Fjava-eid-exceptions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wavesoftware%2Fjava-eid-exceptions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wavesoftware","download_url":"https://codeload.github.com/wavesoftware/java-eid-exceptions/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225110833,"owners_count":17422489,"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-11-18T01:20:25.054Z","updated_at":"2024-11-18T01:20:25.808Z","avatar_url":"https://github.com/wavesoftware.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EID Runtime Exceptions and Utilities\n\n[![Build Status](https://travis-ci.org/wavesoftware/java-eid-exceptions.svg?branch=master)](https://travis-ci.org/wavesoftware/java-eid-exceptions) [![Coverage Status](https://coveralls.io/repos/wavesoftware/java-eid-exceptions/badge.svg?branch=master\u0026service=github)](https://coveralls.io/github/wavesoftware/java-eid-exceptions?branch=master) [![SonarQube Tech Debt](https://img.shields.io/sonar/https/sonar.wavesoftware.pl/pl.wavesoftware%3Aeid-exceptions/tech_debt.svg)](https://sonar.wavesoftware.pl/dashboard?id=pl.wavesoftware%3Aeid-exceptions) [![Maven Central](https://img.shields.io/maven-central/v/pl.wavesoftware/eid-exceptions.svg)](https://search.maven.org/search?q=g:pl.wavesoftware%20AND%20a:eid-exceptions)\n\nThis small library holds a set of exceptions and utilities that implements idea of fast, reusable, error codes that can be simply thrown fast in case of unpredictable and unrecoverable application failure. It is meant to be used for application bugs.\n\n## The Idea\n\nThe main idea of this library is to use a set of simple runtime exceptions to speedup development and make it more professional in the same time. Those exceptions should always take the Exception ID (Eid for short) object on construction. The Eid object should be generated by developer while writing code and committed in the constructor of an exception. This eid object will then be reported when that exception is being displayed or logged.\n\nThis approach simplifies the management of exceptions in the application and allows developers to focus on functionality and code quality, rather than coming up with the correct statement for the exception.\n\nThis error number is perfect to be displayed on the error \"500\" page for your application as a bug reference. It's good idea, because it is static, so wil l not change in subsequent invocations, but it also do not disclose the actual reason why bug occurred.\n\nThis approach is best to use with tools and IDE plugins like:\n\n * [Generating Exception Id number in Intellij IDEA with Live Templates](https://github.com/wavesoftware/java-eid-exceptions/wiki/Generating%20Exception%20Id%20number%20in%20Intellij%20IDEA%20with%20Live%20Templates)\n * [EidGenerator for Netbeans IDE](http://plugins.netbeans.org/plugin/53137/exception-id-eid-generator)\n \nError page can say something like:\n\n\u003e We are deeply sorry. A fatal error occurred.\n\u003e The reference number is: 20150721:100554\n\u003e\n\u003e Wait a couple of minutes, and try again. If the same error number persists, call IT support. \n\nThat error page is easy to implement, because all those exceptions implement `EidContainer` interface.\n\nExample:\n\n```java\nthrow new EidIllegalStateException(\"20150721:100554\", cause);\n```\n\nExample log:\n\n```\npl.wavesoftware.eid.exceptions.EidIllegalStateException: [20150721:100554]\u003cg0qrwx\u003e =\u003e Zipfile in invalid format\n\tat sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)\n\tat sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:57)\n\t\nCaused by: java.util.zip.DataFormatException: Zipfile in invalid format\n\tat sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)\n\tat sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:57)\n\t... 62 more\n```\n\n\n## Caution\n\nThis classes shouldn't be used in any public API or library. It is designed to be used for in-house development of end user applications which will report bugs in standardized error pages or post them to issue tracker.\n\n## Maven\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003epl.wavesoftware\u003c/groupId\u003e\n    \u003cartifactId\u003eeid-exceptions\u003c/artifactId\u003e\n    \u003cversion\u003e2.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### `EidPreconditions` class\n\n#### General use\n\n`EidPreconditions` class consists static methods that help to use Eid in a method or constructor. This is solely for convenience purposes. Use them to check whether method or constructor was invoked correctly (whether its preconditions have been met). These methods generally accept a `boolean` expression which is expected to be `true` (or in the case of `checkNotNull`, an object reference which is expected to be non-null). When `false` (or `null`) is passed instead, the `EidPreconditions` method throws an unchecked exception, which helps the calling method communicate to its caller that that caller has made a mistake.\n\nEach method accepts a EID string or Eid object, which is designed to ease of use and provide strict ID for given exception usage. This approach speed up development of large application and helps support teams by giving both static and random ID for each possible bug that could occur.\n\nEach example uses static import:\n\n```java\nimport static pl.wavesoftware.eid.utils.EidPreconditions.*;\n```\n\n#### `checkArgument` method\n\n`checkArgument` method should be used to check argument of the method, and validate it in technical terms (not business terms).\n\nExample:\n\n```java\n// [..]\npublic static double sqrt(double value);\n  checkArgument(value \u003e= 0.0, \"20150718:012333\");\n  // if ok, calculate the square root\n}\n```\n \nIn this example, `checkArgument` throws an `EidIllegalArgumentException` to indicate that developer made an error in its call to `sqrt`. \n\n#### `checkState` method\n\n`checkState` method should be used to check state of the class in given moment, and validate it in technical terms (not business terms).\n\nExample:\n\n```java\ncheckState(a \u003e= 3.14 \u0026\u0026 b \u003c 0., \"20150721:115016\");\n```\n\n#### `checkNotNull` method\n\n`checkNotNull` method should be used to check if given non null argument is actually `null`\n\nExample:\n\n```java\nString nonNullUserName = checkNotNull(userName, \"20150721:115515\");\n```\n\n#### `checkElementIndex` method\n\n`checkElementIndex` method can be used to test parameters of an array, before being used\n\n```java\ncheckElementIndex(index, list.size(), \"20150721:115749\");\n```\n\n#### Formatted message support\n\nFrom release `1.2.0` methods have been added to support additional formatted messages for `checkArgument`, \n`checkState`, `checkNotNull` and `checkElementIndex` method. Those method versions can sometimes be used to pass additional information to exceptions that will be displayed in log files.\n\nFrom release `2.0.0` message formatting is done using `MessageFormat#format(String, Object[])` method.\n\nFor example:\n\n```java\ncheckState(\n  transation.isValid(), \"20151119:120238\", \n  \"Invalid transaction: {0}\", transaction\n);\n```\n\nWill produce output similar to;\n\n```\npl.wavesoftware.eid.exceptions.EidIllegalStateException: \n ↵ [20151119:120238]\u003cxf4j1l\u003e =\u003e Invalid transaction:\n ↵ \u003cTransaction id=null, buyer=null, products=[]\u003e\n```\n \n#### Functional try to execute blocks\n \nYou can use functional blocks to handle operations, that are intended to operate properly. This approach simplify the code and makes it more readable. It's also good way to deal with untested, uncovered `catch` blocks. It's easy and gives developers nice way of dealing with countless operations that suppose to work as intended.\n\nThere are two versions. One with `UnsafeSupplier` and one with `UnsafeProcedure`. The difference is that unsafe procedure do not return anything.\n\nExample:\n\n```java\nimport static pl.wavesoftware.eid.utils.EidExecutions.tryToExecute;\n// [..]\nInputStream is = tryToExecute(\n    () -\u003e openResource(\"project.properties\"),\n    \"20150718:121521\"\n);\n```\n\nor with JDK \u003c 8\n\n```java\nInputStream is = EidExecutions.tryToExecute(new UnsafeSupplier\u003cInputStream\u003e() {\n    @Override @Nonnull\n    public InputStream get() throws IOException {\n        return this.getClass().getClassLoader()\n            .getResourceAsStream(\"project.properties\");\n    }\n}, \"20150718:121521\");\n```\n\n#### Logging\n\nEid object can also be useful in logging. That is `message` method provided to do that. Message formatting is done using \n`MessageFormat.format(String, Object[])` method.\nFor example:\n\n```java\nlog.debug(DefaultEid\n  .eid(\"20151119:121814\")\n  .message(\"REST request received: {0}\", request).toString()\n);\n```\n\nwill unfold to something similar to:\n\n```\n2017-01-08T16:45:34,334 DEBUG [a.b.c.RestBroker]\n ↵ [20151119:121814]\u003cd1afca\u003e REST request received: \n ↵ \u003cRestRequest user=\u003cUser id=345\u003e flow=ShowLastTransactions step=Confirm\u003e\n```\n\n#### Configuration\n\nFrom release `2.0.0` configuration interfaces have been added. There are 2 ways to configure Eid library.\n\n##### Configuration using Java's ServiceLoader mechanism\n\nJava `ServiceLoader` mechanism is standard for extending libraries. To do that, create on your classpath, a file:\n\n`META-INF/services/pl.wavesoftware.eid.api.Configurator`\n\nIn that file, place a fully qualified class name of your class that implements `Configurator` interface. It should be called first time you reference an Eid, or and of the eid exceptions, or utility preconditions class.\n\n##### Programmatic configuration\n\nYou can also configure Eid library programmatically. To do just that, use `EidModule.getBinding().getConfigurationSystem().configure()` method.\n\n```java\n// configure\nConfigurator original = EidModul.getBinding()\n  .getConfigurationSystem()\n  .configure(configuration -\u003e\n    configuration.uniqueIdGenerator(() -\u003e constUniq)\n  );\n\n// restore original configuration with:\nEidModule.getBinding()\n  .getConfigurationSystem()\n  .configure(original);\n```\n \nNote, that method returns a configurator that  can be used to restore configuration to the state before you invoke this configuration method.\n\n#### Validation\n\nOn `2.0.0` release optional validation have been added. If you configure a `Validator` using either of configuration methods, each new Eid will be validated for correctness. Note that this will happen lazily for `EidPreconditions` and `EidExecutions` utility methods.\n\n### Contributing\n\nContributions are welcome!\n\nTo contribute, follow the standard [git flow](http://danielkummer.github.io/git-flow-cheatsheet/) of:\n\n1. Fork it\n1. Create your feature branch (`git checkout -b feature/my-new-feature`)\n1. Commit your changes (`git commit -am 'Add some feature'`)\n1. Push to the branch (`git push origin feature/my-new-feature`)\n1. Create new Pull Request\n\nEven if you can't contribute code, if you have an idea for an improvement please open an [issue](https://github.com/wavesoftware/java-eid-exceptions/issues).\n\n## Requirements\n\n* JDK 6 - 11\n\n### Releases\n\n- 2.0.0\n  - Complete overhaul of library structure\n  - Support for Java 9 and 11\n  - More obvious exceptions constructors\n  - Better configuration\n  - Optional validation\n- 1.2.0\n  - Major performance tweaks and tests for `EidPreconditions` methods #4 \n  - Major performance tweaks and tests for `Eid` class #2 \n  - Switched to new OSSRH maven template\n  - Switched to Git Flow via jgitflow plugin\n- 1.1.0\n  - Adding support for formatted messages in exceptions and also in utility methods of `EidPreconditions`  \n- 1.0.1\n  - Fixed handling for throwables as a cause with `message == null`. `cause.toString()` method is used \n- 1.0.0\n  - Support for JDK \u003e= 1.6\n- 0.1.0\n  - initial release\n  - idea imported from Guava Library and COI code\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwavesoftware%2Fjava-eid-exceptions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwavesoftware%2Fjava-eid-exceptions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwavesoftware%2Fjava-eid-exceptions/lists"}