0
# Network Utilities
1

2
Network utilities for address resolution, port management, and service discovery integration with comprehensive tools for distributed service coordination.
3

4
## Capabilities
5

6
### Network Utilities
7

8
Core network utilities for address resolution, port management, and service discovery integration.
9

10
```java { .api }
11
/**
12
 * Network utility functions for CDAP services
13
 */
14
public final class Networks {
15
    /**
16
     * Resolve hostname to InetAddress with fallback
17
     * @param hostname The hostname to resolve
18
     * @param onErrorAddress Fallback address if resolution fails
19
     * @return Resolved InetAddress or fallback address
20
     */
21
    public static InetAddress resolve(String hostname, InetAddress onErrorAddress);
22
    
23
    /**
24
     * Find a random free port
25
     * @return Available port number
26
     */
27
    public static int getRandomPort();
28
    
29
    /**
30
     * Extract IP address from socket address
31
     * @param address The socket address
32
     * @return IP address as string
33
     */
34
    public static String getIP(SocketAddress address);
35
    
36
    /**
37
     * Add discoverable service to configuration
38
     * @param cConf Configuration object
39
     * @param key Configuration key
40
     * @param discoverable Service to add
41
     */
42
    public static void addDiscoverable(CConfiguration cConf, String key, Discoverable discoverable);
43
    
44
    /**
45
     * Remove discoverable service from configuration
46
     * @param cConf Configuration object
47
     * @param key Configuration key
48
     * @param discoverable Service to remove
49
     */
50
    public static void removeDiscoverable(CConfiguration cConf, String key, Discoverable discoverable);
51
    
52
    /**
53
     * Get discoverable services from configuration
54
     * @param cConf Configuration object  
55
     * @param key Configuration key
56
     * @return Set of discoverable services
57
     */
58
    public static Set<Discoverable> getDiscoverables(CConfiguration cConf, String key);
59
    
60
    /**
61
     * Set network address in configuration
62
     * @param cConf Configuration object
63
     * @param key Configuration key
64
     * @param addr Socket address to set
65
     */
66
    public static void setAddress(CConfiguration cConf, String key, InetSocketAddress addr);
67
    
68
    /**
69
     * Get network address from configuration
70
     * @param cConf Configuration object
71
     * @param key Configuration key
72
     * @return Socket address from configuration
73
     */
74
    public static InetSocketAddress getAddress(CConfiguration cConf, String key);
75
}
76
```
77

78
**Usage Examples:**
79

80
```java
81
import io.cdap.cdap.common.utils.Networks;
82
import io.cdap.cdap.common.conf.CConfiguration;
83
import org.apache.twill.discovery.Discoverable;
84

85
// Resolve hostnames with fallback
86
InetAddress localhost = InetAddress.getLoopbackAddress();
87
InetAddress resolved = Networks.resolve("my-server.com", localhost);
88
System.out.println("Resolved address: " + resolved.getHostAddress());
89

90
// Find available ports
91
int port1 = Networks.getRandomPort();
92
int port2 = Networks.getRandomPort();
93
System.out.println("Available ports: " + port1 + ", " + port2);
94

95
// Extract IP from socket address
96
SocketAddress socketAddr = new InetSocketAddress("192.168.1.100", 8080);
97
String ip = Networks.getIP(socketAddr);
98
System.out.println("IP: " + ip); // "192.168.1.100"
99

100
// Service discovery integration
101
CConfiguration cConf = CConfiguration.create();
102

103
// Add discoverable service
104
Discoverable webService = new Discoverable() {
105
    @Override
106
    public String getName() { return "web-service"; }
107
    
108
    @Override
109
    public InetSocketAddress getSocketAddress() {
110
        return new InetSocketAddress("localhost", 8080);
111
    }
112
    
113
    @Override
114
    public byte[] getPayload() { return new byte[0]; }
115
};
116

117
Networks.addDiscoverable(cConf, "services.web", webService);
118

119
// Remove discoverable service
120
Networks.removeDiscoverable(cConf, "services.web", webService);
121

122
// Retrieve discoverable services
123
Set<Discoverable> services = Networks.getDiscoverables(cConf, "services.web");
124
for (Discoverable service : services) {
125
    System.out.println("Service: " + service.getName() + 
126
                      " at " + service.getSocketAddress());
127
}
128

129
// Address configuration management
130
InetSocketAddress bindAddr = new InetSocketAddress("0.0.0.0", 9090);
131
Networks.setAddress(cConf, "my.service.bind.address", bindAddr);
132

133
InetSocketAddress configuredAddr = Networks.getAddress(cConf, "my.service.bind.address");
134
System.out.println("Configured to bind on: " + configuredAddr);
135
```
136

137
### Service Discovery Components
138

139
Components for service discovery and endpoint selection strategies.
140

141
```java { .api }
142
/**
143
 * Strategy for selecting endpoints from discovered services
144
 */
145
public interface EndpointStrategy {
146
    /**
147
     * Pick an endpoint from available discoverables
148
     * @param discoverables Available service endpoints
149
     * @return Selected endpoint or null if none available
150
     */
151
    Discoverable pick(Iterable<Discoverable> discoverables);
152
}
153

154
/**
155
 * Base implementation of endpoint strategy
156
 */
157
public abstract class AbstractEndpointStrategy implements EndpointStrategy {
158
    protected AbstractEndpointStrategy();
159
    
160
    /**
161
     * Pick an endpoint, with null handling
162
     */
163
    @Override
164
    public final Discoverable pick(Iterable<Discoverable> discoverables);
165
    
166
    /**
167
     * Subclasses implement the actual picking logic
168
     */
169
    protected abstract Discoverable doPick(Iterable<Discoverable> discoverables);
170
}
171

172
/**
173
 * Random endpoint selection strategy
174
 */
175
public class RandomEndpointStrategy extends AbstractEndpointStrategy {
176
    public RandomEndpointStrategy();
177
    
178
    @Override
179
    protected Discoverable doPick(Iterable<Discoverable> discoverables);
180
}
181

182
/**
183
 * Sticky endpoint selection strategy that prefers the same endpoint
184
 */
185
public class StickyEndpointStrategy extends AbstractEndpointStrategy {
186
    public StickyEndpointStrategy();
187
    
188
    @Override  
189
    protected Discoverable doPick(Iterable<Discoverable> discoverables);
190
}
191
```
192

193
### URI and Address Utilities
194

195
Utilities for URI handling and address resolution.
196

197
```java { .api }
198
/**
199
 * URI scheme constants
200
 */
201
public enum URIScheme {
202
    HTTP("http"),
203
    HTTPS("https"),
204
    FILE("file");
205
    
206
    private final String scheme;
207
    
208
    URIScheme(String scheme);
209
    
210
    public String getScheme();
211
    
212
    /**
213
     * Create URI with this scheme
214
     */
215
    public URI createURI(String host, int port, String path);
216
}
217

218
/**
219
 * Discoverable with address resolution capabilities
220
 */
221
public class ResolvingDiscoverable implements Discoverable {
222
    public ResolvingDiscoverable(Discoverable discoverable);
223
    
224
    @Override
225
    public String getName();
226
    
227
    @Override
228
    public InetSocketAddress getSocketAddress();
229
    
230
    @Override
231
    public byte[] getPayload();
232
    
233
    /**
234
     * Get resolved socket address (resolves hostname to IP)
235
     */
236
    public InetSocketAddress getResolvedSocketAddress();
237
}
238
```
239

240
**Advanced Usage Examples:**
241

242
```java
243
import io.cdap.cdap.common.discovery.*;
244
import org.apache.twill.discovery.DiscoveryServiceClient;
245

246
// Endpoint selection strategies
247
public class LoadBalancedClient {
248
    private final DiscoveryServiceClient discoveryClient;
249
    private final EndpointStrategy strategy;
250
    
251
    public LoadBalancedClient(DiscoveryServiceClient discoveryClient) {
252
        this.discoveryClient = discoveryClient;
253
        // Use random strategy for load balancing
254
        this.strategy = new RandomEndpointStrategy();
255
    }
256
    
257
    public String makeRequest(String serviceName, String path) throws IOException {
258
        Iterable<Discoverable> endpoints = discoveryClient.discover(serviceName);
259
        Discoverable endpoint = strategy.pick(endpoints);
260
        
261
        if (endpoint == null) {
262
            throw new IOException("No available endpoints for service: " + serviceName);
263
        }
264
        
265
        InetSocketAddress addr = endpoint.getSocketAddress();
266
        // Make HTTP request to selected endpoint
267
        return httpClient.get("http://" + addr.getHostString() + ":" + 
268
                             addr.getPort() + path);
269
    }
270
}
271

272
// Sticky client that prefers the same endpoint
273
public class StickyClient {
274
    private final EndpointStrategy stickyStrategy = new StickyEndpointStrategy();
275
    
276
    public void processWorkflow(String serviceName, List<String> requests) {
277
        Iterable<Discoverable> endpoints = discoveryClient.discover(serviceName);
278
        
279
        // All requests in this workflow will prefer the same endpoint
280
        for (String request : requests) {
281
            Discoverable endpoint = stickyStrategy.pick(endpoints);
282
            if (endpoint != null) {
283
                processRequest(endpoint, request);
284
            }
285
        }
286
    }
287
}
288

289
// URI building utilities
290
public class ServiceUrlBuilder {
291
    public static URI buildServiceUrl(URIScheme scheme, Discoverable service, String path) {
292
        InetSocketAddress addr = service.getSocketAddress();
293
        return scheme.createURI(addr.getHostString(), addr.getPort(), path);
294
    }
295
    
296
    public static List<URI> buildServiceUrls(String serviceName, String path, 
297
                                           DiscoveryServiceClient discoveryClient) {
298
        List<URI> urls = new ArrayList<>();
299
        
300
        for (Discoverable service : discoveryClient.discover(serviceName)) {
301
            URI httpUrl = URIScheme.HTTP.createURI(
302
                service.getSocketAddress().getHostString(),
303
                service.getSocketAddress().getPort(),
304
                path
305
            );
306
            urls.add(httpUrl);
307
        }
308
        
309
        return urls;
310
    }
311
}
312

313
// Address resolution with fallback
314
public class NetworkConfig {
315
    public static InetSocketAddress getBindAddress(CConfiguration cConf, 
316
                                                  String hostKey, String portKey, 
317
                                                  String defaultHost, int defaultPort) {
318
        String host = cConf.get(hostKey, defaultHost);
319
        int port = cConf.getInt(portKey, defaultPort);
320
        
321
        // Resolve hostname with localhost fallback
322
        InetAddress addr = Networks.resolve(host, InetAddress.getLoopbackAddress());
323
        return new InetSocketAddress(addr, port);
324
    }
325
    
326
    public static void configureService(CConfiguration cConf, String serviceName, 
327
                                       InetSocketAddress bindAddress) {
328
        // Store the actual bind address after service starts
329
        Networks.setAddress(cConf, serviceName + ".bind.address", bindAddress);
330
        
331
        // Make it discoverable
332
        Discoverable discoverable = new SimpleDiscoverable(serviceName, bindAddress);
333
        Networks.addDiscoverable(cConf, serviceName + ".discoverable", discoverable);
334
    }
335
}
336
```