Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/wavesoftware/java-eid-exceptions
EID Runtime Exceptions and Utilities
https://github.com/wavesoftware/java-eid-exceptions
Last synced: about 13 hours ago
JSON representation
EID Runtime Exceptions and Utilities
- Host: GitHub
- URL: https://github.com/wavesoftware/java-eid-exceptions
- Owner: wavesoftware
- License: apache-2.0
- Created: 2015-07-18T21:53:04.000Z (over 9 years ago)
- Default Branch: develop
- Last Pushed: 2018-12-29T21:53:26.000Z (almost 6 years ago)
- Last Synced: 2024-10-19T03:18:29.378Z (about 1 month ago)
- Language: Java
- Homepage: http://wavesoftware.github.io/java-eid-exceptions
- Size: 232 KB
- Stars: 11
- Watchers: 2
- Forks: 7
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# EID Runtime Exceptions and Utilities
[](https://travis-ci.org/wavesoftware/java-eid-exceptions) [](https://coveralls.io/github/wavesoftware/java-eid-exceptions?branch=master) [](https://sonar.wavesoftware.pl/dashboard?id=pl.wavesoftware%3Aeid-exceptions) [](https://search.maven.org/search?q=g:pl.wavesoftware%20AND%20a:eid-exceptions)
This 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.
## The Idea
The 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.
This 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.
This 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.
This approach is best to use with tools and IDE plugins like:
* [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)
* [EidGenerator for Netbeans IDE](http://plugins.netbeans.org/plugin/53137/exception-id-eid-generator)
Error page can say something like:
> We are deeply sorry. A fatal error occurred.
> The reference number is: 20150721:100554
>
> Wait a couple of minutes, and try again. If the same error number persists, call IT support.
That error page is easy to implement, because all those exceptions implement `EidContainer` interface.
Example:
```java
throw new EidIllegalStateException("20150721:100554", cause);
```
Example log:
```
pl.wavesoftware.eid.exceptions.EidIllegalStateException: [20150721:100554] => Zipfile in invalid format
at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:57)
Caused by: java.util.zip.DataFormatException: Zipfile in invalid format
at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:57)
... 62 more
```
## Caution
This 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.
## Maven
```xml
pl.wavesoftware
eid-exceptions
2.0.0
```
### `EidPreconditions` class
#### General use
`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.
Each 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.
Each example uses static import:
```java
import static pl.wavesoftware.eid.utils.EidPreconditions.*;
```
#### `checkArgument` method
`checkArgument` method should be used to check argument of the method, and validate it in technical terms (not business terms).
Example:
```java
// [..]
public static double sqrt(double value);
checkArgument(value >= 0.0, "20150718:012333");
// if ok, calculate the square root
}
```
In this example, `checkArgument` throws an `EidIllegalArgumentException` to indicate that developer made an error in its call to `sqrt`.
#### `checkState` method
`checkState` method should be used to check state of the class in given moment, and validate it in technical terms (not business terms).
Example:
```java
checkState(a >= 3.14 && b < 0., "20150721:115016");
```
#### `checkNotNull` method
`checkNotNull` method should be used to check if given non null argument is actually `null`
Example:
```java
String nonNullUserName = checkNotNull(userName, "20150721:115515");
```
#### `checkElementIndex` method
`checkElementIndex` method can be used to test parameters of an array, before being used
```java
checkElementIndex(index, list.size(), "20150721:115749");
```
#### Formatted message support
From release `1.2.0` methods have been added to support additional formatted messages for `checkArgument`,
`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.
From release `2.0.0` message formatting is done using `MessageFormat#format(String, Object[])` method.
For example:
```java
checkState(
transation.isValid(), "20151119:120238",
"Invalid transaction: {0}", transaction
);
```
Will produce output similar to;
```
pl.wavesoftware.eid.exceptions.EidIllegalStateException:
↵ [20151119:120238] => Invalid transaction:
↵
```
#### Functional try to execute blocks
You 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.
There are two versions. One with `UnsafeSupplier` and one with `UnsafeProcedure`. The difference is that unsafe procedure do not return anything.
Example:
```java
import static pl.wavesoftware.eid.utils.EidExecutions.tryToExecute;
// [..]
InputStream is = tryToExecute(
() -> openResource("project.properties"),
"20150718:121521"
);
```
or with JDK < 8
```java
InputStream is = EidExecutions.tryToExecute(new UnsafeSupplier() {
@Override @Nonnull
public InputStream get() throws IOException {
return this.getClass().getClassLoader()
.getResourceAsStream("project.properties");
}
}, "20150718:121521");
```
#### Logging
Eid object can also be useful in logging. That is `message` method provided to do that. Message formatting is done using
`MessageFormat.format(String, Object[])` method.
For example:
```java
log.debug(DefaultEid
.eid("20151119:121814")
.message("REST request received: {0}", request).toString()
);
```
will unfold to something similar to:
```
2017-01-08T16:45:34,334 DEBUG [a.b.c.RestBroker]
↵ [20151119:121814] REST request received:
↵ flow=ShowLastTransactions step=Confirm>
```
#### Configuration
From release `2.0.0` configuration interfaces have been added. There are 2 ways to configure Eid library.
##### Configuration using Java's ServiceLoader mechanism
Java `ServiceLoader` mechanism is standard for extending libraries. To do that, create on your classpath, a file:
`META-INF/services/pl.wavesoftware.eid.api.Configurator`
In 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.
##### Programmatic configuration
You can also configure Eid library programmatically. To do just that, use `EidModule.getBinding().getConfigurationSystem().configure()` method.
```java
// configure
Configurator original = EidModul.getBinding()
.getConfigurationSystem()
.configure(configuration ->
configuration.uniqueIdGenerator(() -> constUniq)
);
// restore original configuration with:
EidModule.getBinding()
.getConfigurationSystem()
.configure(original);
```
Note, that method returns a configurator that can be used to restore configuration to the state before you invoke this configuration method.
#### Validation
On `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.
### Contributing
Contributions are welcome!
To contribute, follow the standard [git flow](http://danielkummer.github.io/git-flow-cheatsheet/) of:
1. Fork it
1. Create your feature branch (`git checkout -b feature/my-new-feature`)
1. Commit your changes (`git commit -am 'Add some feature'`)
1. Push to the branch (`git push origin feature/my-new-feature`)
1. Create new Pull Request
Even 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).
## Requirements
* JDK 6 - 11
### Releases
- 2.0.0
- Complete overhaul of library structure
- Support for Java 9 and 11
- More obvious exceptions constructors
- Better configuration
- Optional validation
- 1.2.0
- Major performance tweaks and tests for `EidPreconditions` methods #4
- Major performance tweaks and tests for `Eid` class #2
- Switched to new OSSRH maven template
- Switched to Git Flow via jgitflow plugin
- 1.1.0
- Adding support for formatted messages in exceptions and also in utility methods of `EidPreconditions`
- 1.0.1
- Fixed handling for throwables as a cause with `message == null`. `cause.toString()` method is used
- 1.0.0
- Support for JDK >= 1.6
- 0.1.0
- initial release
- idea imported from Guava Library and COI code