0
# Apache Flink Runtime Web
1

2
Apache Flink Runtime Web is a Java library that provides comprehensive web-based interfaces for Apache Flink runtime operations. It enables JAR file management, job execution through REST APIs, and includes a standalone history server for viewing completed jobs. Built on Netty with a modern Angular frontend, it serves as the essential web dashboard component for monitoring and managing Apache Flink streaming applications.
3

4
## Package Information
5

6
- **Package Name**: flink-runtime-web_2.12
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **License**: Apache-2.0
10
- **Installation**: Add to Maven pom.xml:
11
  ```xml
12
  <dependency>
13
    <groupId>org.apache.flink</groupId>
14
    <artifactId>flink-runtime-web_2.12</artifactId>
15
    <version>1.14.6</version>
16
  </dependency>
17
  ```
18

19
## Core Imports
20

21
```java
22
import org.apache.flink.runtime.webmonitor.utils.WebFrontendBootstrap;
23
import org.apache.flink.runtime.webmonitor.history.HistoryServer;
24
import org.apache.flink.runtime.webmonitor.WebSubmissionExtension;
25
import org.apache.flink.runtime.rest.handler.router.Router;
26
import org.apache.flink.configuration.Configuration;
27
import org.slf4j.Logger;
28
import java.io.File;
29
```
30

31
For JAR management handlers:
32

33
```java
34
import org.apache.flink.runtime.webmonitor.handlers.*;
35
```
36

37
## Basic Usage
38

39
```java
40
import org.apache.flink.runtime.webmonitor.utils.WebFrontendBootstrap;
41
import org.apache.flink.configuration.Configuration;
42
import org.apache.flink.shaded.netty4.io.netty.handler.ssl.util.SelfSignedCertificate;
43
import java.io.File;
44

45
// Create web frontend bootstrap
46
Configuration config = new Configuration();
47
File uploadDir = new File("/tmp/flink-web-upload");
48
WebFrontendBootstrap bootstrap = new WebFrontendBootstrap(
49
    router,
50
    logger,
51
    uploadDir,
52
    null, // SSL handler factory
53
    "localhost",
54
    8081,
55
    config
56
);
57

58
// Get server details
59
int port = bootstrap.getServerPort();
60
String address = bootstrap.getRestAddress();
61

62
// Shutdown when done
63
bootstrap.shutdown();
64
```
65

66
For standalone history server:
67

68
```java
69
import org.apache.flink.runtime.webmonitor.history.HistoryServer;
70
import org.apache.flink.configuration.Configuration;
71

72
// Start history server
73
Configuration config = new Configuration();
74
HistoryServer historyServer = new HistoryServer(config);
75
historyServer.run();
76
```
77

78
## Architecture
79

80
The Flink Runtime Web component is built around several key architectural patterns:
81

82
- **Netty-based Server**: High-performance HTTP server using Netty with custom routing
83
- **REST API Handlers**: Modular request handlers extending AbstractRestHandler for specific operations
84
- **Data Transfer Objects**: Type-safe request/response bodies for API communication
85
- **Parameter System**: Type-safe query and path parameter definitions
86
- **Extension Pattern**: WebSubmissionExtension provides modular JAR submission capabilities
87
- **History Server**: Standalone server for archived job information and static file serving
88

89
This design enables both embedded use (via WebFrontendBootstrap) and standalone deployment (via HistoryServer), with a clean separation between server infrastructure, REST API handlers, and data models.
90

91
## Capabilities
92

93
### Web Server Bootstrap
94

95
Core infrastructure for setting up and managing the Netty-based web server. Provides the foundation for embedding Flink's web interface in applications.
96

97
```java { .api }
98
public class WebFrontendBootstrap {
99
    public WebFrontendBootstrap(
100
        Router router,
101
        Logger logger,
102
        File uploadDir,
103
        SSLHandlerFactory sslHandlerFactory,
104
        String address,
105
        int port,
106
        Configuration configuration
107
    );
108
    
109
    public ServerBootstrap getBootstrap();
110
    public int getServerPort();
111
    public String getRestAddress();
112
    public void shutdown();
113
}
114
```
115

116
[Web Server Bootstrap](./web-server-bootstrap.md)
117

118
### JAR Management
119

120
Complete JAR file lifecycle management including upload, listing, execution, and deletion. Core functionality for submitting and managing Flink jobs through the web interface.
121

122
```java { .api }
123
public class JarUploadHandler extends AbstractRestHandler<RestfulGateway, EmptyRequestBody, JarUploadResponseBody, EmptyMessageParameters> {
124
    public JarUploadHandler(
125
        GatewayRetriever<? extends RestfulGateway> leaderRetriever,
126
        Time timeout,
127
        Map<String, String> responseHeaders,
128
        MessageHeaders<EmptyRequestBody, JarUploadResponseBody, EmptyMessageParameters> messageHeaders,
129
        Path jarDir,
130
        Executor executor
131
    );
132
}
133

134
public class JarRunHandler extends AbstractRestHandler<RestfulGateway, JarRunRequestBody, JarRunResponseBody, JarRunMessageParameters> {
135
    // POST /jars/:jarId/run
136
}
137

138
public class JarListHandler extends AbstractRestHandler<RestfulGateway, EmptyRequestBody, JarListInfo, EmptyMessageParameters> {
139
    // GET /jars
140
}
141
```
142

143
[JAR Management](./jar-management.md)
144

145
### History Server
146

147
Standalone server functionality for viewing archived job information and serving static files. Ideal for long-term job monitoring and analysis.
148

149
```java { .api }
150
public class HistoryServer {
151
    public HistoryServer(Configuration configuration);
152
    public HistoryServer(Configuration configuration, Consumer<ArchiveEvent> eventListener);
153
    
154
    public static void main(String[] args);
155
    public void run();
156
}
157

158
public class HistoryServerArchiveFetcher {
159
    // Archive management functionality
160
}
161
```
162

163
[History Server](./history-server.md)
164

165
### REST API Specifications
166

167
Type-safe REST API definitions including headers, parameters, and message specifications. Provides compile-time safety for API contracts.
168

169
```java { .api }
170
public class JarUploadHeaders implements MessageHeaders<EmptyRequestBody, JarUploadResponseBody, EmptyMessageParameters> {
171
    // POST /jars/upload specification
172
}
173

174
public class JarRunHeaders implements MessageHeaders<JarRunRequestBody, JarRunResponseBody, JarRunMessageParameters> {
175
    // POST /jars/:jarId/run specification
176
}
177

178
public class JarIdPathParameter extends MessagePathParameter<String> {
179
    // Path parameter for JAR ID
180
}
181
```
182

183
[REST API Specifications](./rest-api-specifications.md)
184

185
### Data Transfer Objects
186

187
Comprehensive request and response body classes for all API operations. Provides type-safe data exchange between client and server.
188

189
```java { .api }
190
public abstract class JarRequestBody implements RequestBody {
191
    public String getEntryClassName();
192
    public List<String> getProgramArguments();
193
    public Integer getParallelism();
194
    public JobID getJobId();
195
}
196

197
public class JarRunRequestBody extends JarRequestBody {
198
    public Boolean getAllowNonRestoredState();
199
    public String getSavepointPath();
200
}
201

202
public class JarUploadResponseBody implements ResponseBody {
203
    public JarUploadResponseBody(String filename);
204
    public String getStatus();
205
    public String getFilename();
206
}
207
```
208

209
[Data Transfer Objects](./data-transfer-objects.md)
210

211
### Utilities and Extensions
212

213
Helper utilities and extension points for JAR processing and web submission functionality. Provides reusable components for custom implementations.
214

215
```java { .api }
216
public class JarHandlerUtils {
217
    public static List<String> tokenizeArguments(String args);
218
    
219
    public static class JarHandlerContext {
220
        public static JarHandlerContext fromRequest(HandlerRequest<JarRequestBody, ?> request, Path jarDir);
221
        public void applyToConfiguration(Configuration configuration);
222
        public JobGraph toJobGraph(ClassLoader classLoader);
223
        public PackagedProgram toPackagedProgram(ClassLoader classLoader);
224
    }
225
}
226

227
public class WebSubmissionExtension implements WebMonitorExtension {
228
    public Collection<Tuple2<RestHandlerSpecification, ChannelInboundHandler>> getHandlers();
229
    public CompletableFuture<Void> closeAsync();
230
}
231
```
232

233
[Utilities and Extensions](./utilities-extensions.md)
234

235
## REST Endpoints Summary
236

237
The package provides the following REST endpoints for JAR management:
238

239
- **POST /jars/upload** - Upload JAR files to the server
240
- **GET /jars** - List all uploaded JAR files with entry point information
241
- **POST /jars/:jarId/run** - Execute an uploaded JAR as a Flink job
242
- **DELETE /jars/:jarId** - Delete an uploaded JAR file
243
- **GET /jars/:jarId/plan** - Show execution plan for JAR without running
244
- **POST /jars/:jarId/plan** - Show execution plan with custom parameters
245

246
## Error Handling
247

248
The package includes comprehensive error handling through:
249

250
- **PipelineErrorHandler**: Final error handler in the Netty pipeline
251
- **Validation**: Parameter validation in all request handlers  
252
- **HTTP Status Codes**: Proper REST API status code responses
253
- **Exception Translation**: Conversion of internal exceptions to HTTP responses