JarCastingEID Runtime Exceptions and Utilities
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:
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:
throw new EidIllegalStateException("20150721:100554", cause);
Example log:
pl.wavesoftware.eid.exceptions.EidIllegalStateException: [20150721:100554]<g0qrwx> => 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
<dependency>
<groupId>pl.wavesoftware</groupId>
<artifactId>eid-exceptions</artifactId>
<version>2.0.0</version>
</dependency>
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:
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:
// [..]
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:
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:
String nonNullUserName = checkNotNull(userName, "20150721:115515");
checkElementIndex method
checkElementIndex method can be used to test parameters of an array, before being used
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:
checkState(
transation.isValid(), "20151119:120238",
"Invalid transaction: {0}", transaction
);
Will produce output similar to;
pl.wavesoftware.eid.exceptions.EidIllegalStateException:
↵ [20151119:120238]<xf4j1l> => Invalid transaction:
↵ <Transaction id=null, buyer=null, products=[]>
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:
import static pl.wavesoftware.eid.utils.EidExecutions.tryToExecute;
// [..]
InputStream is = tryToExecute(
() -> openResource("project.properties"),
"20150718:121521"
);
or with JDK < 8
InputStream is = EidExecutions.tryToExecute(new UnsafeSupplier<InputStream>() {
@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:
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]<d1afca> REST request received:
↵ <RestRequest user=<User id=345> 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.
// 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 of:
- Fork it
- Create your feature branch (
git checkout -b feature/my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin feature/my-new-feature) - Create new Pull Request
Even if you can't contribute code, if you have an idea for an improvement please open an issue.
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
EidPreconditionsmethods #4 - Major performance tweaks and tests for
Eidclass #2 - Switched to new OSSRH maven template
- Switched to Git Flow via jgitflow plugin
- Major performance tweaks and tests for
- 1.1.0
- Adding support for formatted messages in exceptions and also in utility methods of
EidPreconditions
- Adding support for formatted messages in exceptions and also in utility methods of
- 1.0.1
- Fixed handling for throwables as a cause with
message == null.cause.toString()method is used
- Fixed handling for throwables as a cause with
- 1.0.0
- Support for JDK >= 1.6
- 0.1.0
- initial release
- idea imported from Guava Library and COI code
