You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+80Lines changed: 80 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -105,6 +105,86 @@ class Spaceship{
105
105
106
106
When mixing annotation and programmatic API, take-a-hint will opt for configuration by programmatic API.
107
107
108
+
### Provide easy hints for final users
109
+
110
+
It's much better when the final user can get hints on how to fix errors at failure time. take-a-hint offers custom Exception classes to help you communicate hints easily.
111
+
112
+
If you have already a code block that throws an exception, you can wrap it inside `HintException` or `HintRuntimeException`. This will let you personalize final error messages depending on your needs. Here are some examples:
113
+
114
+
```java
115
+
classSpaceship {
116
+
privatevoidgoToMars() {
117
+
throwHintRuntimeException.of(
118
+
newIllegalStateException("Oxygen leak !!!"), // this is your regular exception
119
+
"Check your equipments !"// you can set a custom hint message to be shown to final user
120
+
);
121
+
}
122
+
}
123
+
```
124
+
125
+
When the error gets thrown, the final user will get the following message (depending on configuration):
You can work with checked exceptions while using take-a-hint via the custom exception class `HintException` :
134
+
135
+
```java
136
+
classSpaceship {
137
+
privatevoidgoToMars() throwsHintException {
138
+
throwHintException.of(newIllegalStateException("Oxygen leak !!!"), "Check your equipments !");
139
+
}
140
+
}
141
+
// ...
142
+
try {
143
+
newSpaceship().goToMars();
144
+
} catch (HintException ex) { // HintException is a checked exception, should be thrown
145
+
System.out.println("Custom error : "+ ex.getHintsMsg()); // use exception instance as you want
146
+
}
147
+
148
+
```
149
+
150
+
Another cool thing you can do with take-a-hint is set a global hint message for method or class. Let's say you have a method that may throw an exception in multiple occasions, and you want to provide a single hint message for the whole method. Then, you can use the annotation `@HintMessage` to do that.
151
+
152
+
```java
153
+
@Hint
154
+
classSpaceship {
155
+
@HintMessage("Check your equipments")
156
+
privatevoidgoToMars(intx) {
157
+
if(x==-1){
158
+
thrownewIllegalStateException("Crash !");
159
+
}elseif(x==0){
160
+
thrownewIllegalStateException("Boom !");
161
+
}else{
162
+
// go
163
+
}
164
+
}
165
+
}
166
+
```
167
+
168
+
For each exception thrown within the method `goToMars`, take-a-hint will display (depending on the configuration) the custom hint message provided by the annotation `@HintMessage`.
169
+
170
+
You can use the same annotation with the parent class. In that case, the provided message in the class will be shown whenever an exception gets thrown within a method of that class. Each method with its own annotation will override the class custom message.
171
+
172
+
```java
173
+
@Hint
174
+
@HintMessage("Check your equipments !")
175
+
classSpaceship {
176
+
@HintMessage("What about heat ?") // this message will override the one in parent class
177
+
privatevoidgoToTheSun(intx) {
178
+
thrownewIllegalStateException("Burned !");
179
+
}
180
+
181
+
// will use parent message
182
+
privatevoidgoToMars() {
183
+
thrownewIllegalStateException("Boom !");
184
+
}
185
+
}
186
+
```
187
+
108
188
### Use with Picocli
109
189
110
190
[Picocli](https://picocli.info/) is a one-file framework for creating Java command line applications with almost zero code.
0 commit comments