0
# Elasticsearch Core
1

2
Elasticsearch Core is a foundational Java library providing essential utilities and infrastructure components for the Elasticsearch ecosystem. It offers core building blocks for resource management, I/O operations, time handling, functional programming with checked exceptions, and common data structures. The library is designed to be lightweight and dependency-free, serving as the foundation that other Elasticsearch modules build upon.
3

4
## Package Information
5

6
- **Package Name**: org.elasticsearch:elasticsearch-core
7
- **Package Type**: Maven/Gradle
8
- **Language**: Java
9
- **Installation**: `implementation 'org.elasticsearch:elasticsearch-core:9.0.3'`
10

11
## Core Imports
12

13
```java
14
import org.elasticsearch.core.*;
15
```
16

17
Individual imports:
18

19
```java
20
import org.elasticsearch.core.RefCounted;
21
import org.elasticsearch.core.Releasable;
22
import org.elasticsearch.core.TimeValue;
23
import org.elasticsearch.core.IOUtils;
24
import org.elasticsearch.core.CheckedFunction;
25
import org.elasticsearch.core.Tuple;
26
```
27

28
## Basic Usage
29

30
```java
31
import org.elasticsearch.core.*;
32
import java.util.concurrent.TimeUnit;
33

34
public class Example {
35
    public void resourceManagement() {
36
        // Resource management with RefCounted
37
        RefCounted resource = AbstractRefCounted.of(() -> {
38
            System.out.println("Resource closed");
39
        });
40
        
41
        resource.incRef(); // Increment reference count
42
        resource.decRef(); // Decrement reference count (closes when reaches 0)
43
    }
44
    
45
    public void timeOperations() {
46
        // Time value handling
47
        TimeValue duration = TimeValue.timeValueSeconds(30);
48
        TimeValue timeout = new TimeValue(5, TimeUnit.MINUTES);
49
        
50
        System.out.println("Duration: " + duration.toString());
51
        System.out.println("Timeout: " + timeout.toHumanReadableString(2));
52
    }
53
    
54
    public void functionalOperations() throws Exception {
55
        // Checked functional interfaces
56
        CheckedFunction<String, Integer, NumberFormatException> parser = 
57
            Integer::parseInt;
58
        
59
        Integer result = parser.apply("42");
60
        
61
        CheckedConsumer<String, Exception> printer = System.out::println;
62
        printer.accept("Hello World");
63
    }
64
}
65
```
66

67
## Architecture
68

69
Elasticsearch Core is organized around several key design patterns:
70

71
- **Resource Management**: Consistent lifecycle management through RefCounted and Releasable interfaces
72
- **Functional Programming**: Checked exception variants of standard functional interfaces for safer error handling
73
- **Utility Pattern**: Static utility classes providing common operations without instantiation
74
- **Type Safety**: Strong typing with generic support for compile-time validation
75
- **Annotation-Driven**: Metadata annotations for code analysis and IDE integration
76

77
## Capabilities
78

79
### Resource Management
80

81
Provides lifecycle management patterns for resources that need explicit cleanup, including reference counting and releasable interfaces.
82

83
```java { .api }
84
public interface RefCounted {
85
    void incRef();
86
    boolean tryIncRef();
87
    boolean decRef();
88
    boolean hasReferences();
89
    default void mustIncRef();
90
}
91

92
public interface Releasable extends Closeable {
93
    void close();
94
}
95

96
public abstract class AbstractRefCounted implements RefCounted {
97
    protected AbstractRefCounted();
98
    protected abstract void closeInternal();
99
    public static AbstractRefCounted of(Runnable onClose);
100
}
101
```
102

103
[Resource Management](./resource-management.md)
104

105
### Functional Interfaces
106

107
Checked exception variants of standard Java functional interfaces, enabling functional programming patterns with proper exception handling.
108

109
```java { .api }
110
@FunctionalInterface
111
public interface CheckedFunction<T, R, E extends Exception> {
112
    R apply(T t) throws E;
113
}
114

115
@FunctionalInterface
116
public interface CheckedConsumer<T, E extends Exception> {
117
    void accept(T t) throws E;
118
    default CheckedConsumer<T, E> andThen(CheckedConsumer<? super T, E> after);
119
}
120

121
@FunctionalInterface
122
public interface CheckedSupplier<T, E extends Exception> {
123
    T get() throws E;
124
}
125

126
@FunctionalInterface
127
public interface CheckedRunnable<E extends Exception> {
128
    void run() throws E;
129
}
130
```
131

132
[Functional Interfaces](./functional-interfaces.md)
133

134
### Utility Classes
135

136
Core utility classes for common operations including I/O, time handling, string processing, and data manipulation.
137

138
```java { .api }
139
public final class IOUtils {
140
    public static void close(Closeable... objects);
141
    public static void close(@Nullable Closeable closeable);
142
    public static void closeWhileHandlingException(Closeable... objects);
143
    public static void fsync(Path fileToSync, boolean isDir);
144
}
145

146
public class TimeValue implements Comparable<TimeValue> {
147
    public TimeValue(long millis);
148
    public TimeValue(long duration, TimeUnit timeUnit);
149
    public static TimeValue timeValueSeconds(long seconds);
150
    public static TimeValue parseTimeValue(String sValue, String settingName);
151
}
152

153
public record Tuple<V1, V2>(V1 v1, V2 v2) {
154
    public static <V1, V2> Tuple<V1, V2> tuple(V1 v1, V2 v2);
155
}
156
```
157

158
[Utility Classes](./utility-classes.md)
159

160
### Type System
161

162
Annotations, enums, and type utilities that provide metadata and type manipulation capabilities for the Elasticsearch ecosystem.
163

164
```java { .api }
165
@Retention(RetentionPolicy.CLASS)
166
@Target({ElementType.PARAMETER, ElementType.FIELD, ElementType.METHOD})
167
public @interface Nullable {
168
}
169

170
@Retention(RetentionPolicy.CLASS) 
171
@Target({ElementType.CONSTRUCTOR, ElementType.FIELD, ElementType.METHOD, ElementType.TYPE})
172
public @interface SuppressForbidden {
173
    String reason();
174
}
175

176
public enum RestApiVersion {
177
    V_9(9), V_8(8);
178
    
179
    public static RestApiVersion current();
180
    public static RestApiVersion forMajor(int major);
181
    public boolean matches(Predicate<RestApiVersion> predicate);
182
}
183
```
184

185
[Type System](./type-system.md)