0
# Utilities
1

2
Practical utility annotations for common programming tasks including null checking, exception handling, and synchronization.
3

4
## Capabilities
5

6
### @NonNull
7

8
```java { .api }
9
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.LOCAL_VARIABLE})
10
@Retention(RetentionPolicy.SOURCE)
11
public @interface NonNull {
12
}
13
```
14

15
### @SneakyThrows
16

17
```java { .api }
18
@Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
19
@Retention(RetentionPolicy.SOURCE)
20
public @interface SneakyThrows {
21
    Class<? extends Throwable>[] value() default java.lang.Throwable.class;
22
}
23
```
24

25
### @Synchronized
26

27
```java { .api }
28
@Target(ElementType.METHOD)
29
@Retention(RetentionPolicy.SOURCE)
30
public @interface Synchronized {
31
    String value() default "";
32
}
33
```
34

35
### @Cleanup
36

37
```java { .api }
38
@Target(ElementType.LOCAL_VARIABLE)
39
@Retention(RetentionPolicy.SOURCE)
40
public @interface Cleanup {
41
    String value() default "close";
42
}
43
```
44

45
### @Locked
46

47
Guards all statements in a method with a java.util.concurrent.locks.Lock for thread safety.
48

49
```java { .api }
50
/**
51
 * Guards all statements in an annotation method with a Lock.
52
 * 
53
 * For non-static methods, a field named $lock is used, and for static methods,
54
 * $LOCK is used. These will be generated if needed and if they aren't already present.
55
 */
56
@Target(ElementType.METHOD)
57
@Retention(RetentionPolicy.SOURCE)
58
public @interface Locked {
59
    /**
60
     * Optional: specify the name of a different field to lock on. It is a compile time error if this field
61
     * doesn't already exist (the fields are automatically generated only if you don't specify a specific name).
62
     *
63
     * @return Name of the field to lock on (blank = generate one).
64
     */
65
    String value() default "";
66
    
67
    /**
68
     * Locks using a ReadWriteLock#readLock().
69
     */
70
    @Target(ElementType.METHOD)
71
    @Retention(RetentionPolicy.SOURCE)
72
    public @interface Read {
73
        String value() default "";
74
    }
75
    
76
    /**
77
     * Locks using a ReadWriteLock#writeLock().
78
     */
79
    @Target(ElementType.METHOD)
80
    @Retention(RetentionPolicy.SOURCE)
81
    public @interface Write {
82
        String value() default "";
83
    }
84
}
85
```
86

87
**Usage Examples:**
88

89
```java
90
import lombok.*;
91
import java.nio.file.*;
92
import java.io.*;
93

94
public class FileProcessor {
95
    @SneakyThrows
96
    public String readFile(String filename) {
97
        return Files.readString(Paths.get(filename));
98
    }
99

100
    @Synchronized
101
    public void processData(@NonNull String data) {
102
        // Thread-safe processing using synchronized block
103
    }
104
    
105
    @Locked
106
    public void updateCounter() {
107
        // Thread-safe using java.util.concurrent.locks.Lock
108
        counter++;
109
    }
110
    
111
    @Locked.Read
112
    public int readCounter() {
113
        // Thread-safe read using ReadWriteLock.readLock()
114
        return counter;
115
    }
116
    
117
    @Locked.Write  
118
    public void resetCounter() {
119
        // Thread-safe write using ReadWriteLock.writeLock()
120
        counter = 0;
121
    }
122

123
    @SneakyThrows
124
    public void processFile(String filename) {
125
        @Cleanup FileInputStream fis = new FileInputStream(filename);
126
        // File will be automatically closed
127
        // Process file content...
128
    }
129
}
130
```