0
# Socket Addressing
1

2
Comprehensive addressing system for Unix Domain Sockets and other socket families, supporting file paths, abstract namespace, and flexible address creation and management.
3

4
## Core Imports
5

6
```java
7
import java.io.*;
8
import java.net.*;
9
import java.nio.file.*;
10
import org.newsclub.net.unix.AFUNIXSocketAddress;
11
import org.newsclub.net.unix.AFSocketAddress;
12
import org.newsclub.net.unix.AFException;
13
```
14

15
## Capabilities
16

17
### AFUNIXSocketAddress
18

19
Primary addressing class for Unix Domain Socket connections, supporting both file system paths and abstract namespace addressing.
20

21
```java { .api }
22
/**
23
 * Unix Domain Socket addressing implementation
24
 */
25
public final class AFUNIXSocketAddress extends AFSocketAddress {
26
    
27
    /**
28
     * Creates an AFUNIXSocketAddress for the given file
29
     * @param socketFile The socket file path
30
     * @return AFUNIXSocketAddress instance
31
     * @throws AFException if address creation fails
32
     */
33
    public static AFUNIXSocketAddress of(File socketFile) throws AFException;
34
    
35
    /**
36
     * Creates an AFUNIXSocketAddress for the given path
37
     * @param socketPath The socket path
38
     * @return AFUNIXSocketAddress instance  
39
     * @throws AFException if address creation fails
40
     */
41
    public static AFUNIXSocketAddress of(Path socketPath) throws AFException;
42
    
43
    /**
44
     * Creates an AFUNIXSocketAddress for the given path string
45
     * @param pathname The socket path as string
46
     * @return AFUNIXSocketAddress instance
47
     * @throws AFException if address creation fails
48
     */
49
    public static AFUNIXSocketAddress of(String pathname) throws AFException;
50
    
51
    /**
52
     * Creates an AFUNIXSocketAddress for a new temporary file
53
     * @return AFUNIXSocketAddress instance for temporary socket
54
     * @throws IOException if temporary file creation fails
55
     */
56
    public static AFUNIXSocketAddress ofNewTempFile() throws IOException;
57
    
58
    /**
59
     * Creates an AFUNIXSocketAddress from a byte array
60
     * @param bytes The address as byte array
61
     * @return AFUNIXSocketAddress instance
62
     * @throws AFException if address creation fails
63
     */
64
    public static AFUNIXSocketAddress of(byte[] bytes) throws AFException;
65
    
66
    /**
67
     * Creates an AFUNIXSocketAddress from a URI
68
     * @param uri The socket URI
69
     * @return AFUNIXSocketAddress instance
70
     * @throws AFException if address creation fails
71
     */
72
    public static AFUNIXSocketAddress of(URI uri) throws AFException;
73
    
74
    /**
75
     * Creates an AFUNIXSocketAddress for the given file with port
76
     * @param socketFile The socket file path
77
     * @param port The port number
78
     * @return AFUNIXSocketAddress instance
79
     * @throws AFException if address creation fails
80
     */
81
    public static AFUNIXSocketAddress of(File socketFile, int port) throws AFException;
82
    
83
    /**
84
     * Creates an AFUNIXSocketAddress in the abstract namespace (Linux only)
85
     * @param name The abstract socket name
86
     * @return AFUNIXSocketAddress instance for abstract socket
87
     * @throws AFException if address creation fails
88
     */
89
    public static AFUNIXSocketAddress inAbstractNamespace(String name) throws AFException;
90
    
91
    // Address properties
92
    public File getFile() throws FileNotFoundException;
93
    public Path getPath() throws FileNotFoundException;
94
    public String getPathname();
95
    public boolean isInAbstractNamespace();
96
    
97
    // Address validation
98
    public boolean hasFilename();
99
    public boolean exists();
100
    
101
    // Address properties
102
    public int getPort();
103
    public byte[] toBytes();
104
    public URI toURI() throws IOException;
105
    
106
    // Compatibility methods
107
    public String toString();
108
    public boolean equals(Object obj);
109
    public int hashCode();
110
}
111
```
112

113
**Usage Examples:**
114

115
```java
116
import java.io.File;
117
import java.nio.file.Path;
118
import java.nio.file.Paths;
119
import org.newsclub.net.unix.*;
120

121
// File-based socket addressing
122
File socketFile = new File("/tmp/my-app.sock");
123
AFUNIXSocketAddress addr1 = AFUNIXSocketAddress.of(socketFile);
124

125
// Path-based socket addressing  
126
Path socketPath = Paths.get("/var/run/service.sock");
127
AFUNIXSocketAddress addr2 = AFUNIXSocketAddress.of(socketPath);
128

129
// String-based socket addressing
130
AFUNIXSocketAddress addr3 = AFUNIXSocketAddress.of("/tmp/string-socket.sock");
131

132
// Temporary socket file
133
AFUNIXSocketAddress tempAddr = AFUNIXSocketAddress.ofNewTempFile();
134
System.out.println("Temporary socket: " + tempAddr.getFile());
135

136
// Abstract namespace (Linux only)
137
AFUNIXSocketAddress abstractAddr = AFUNIXSocketAddress.inAbstractNamespace("my-abstract-socket");
138
System.out.println("Abstract socket: " + abstractAddr.getPathname());
139
System.out.println("Is abstract: " + abstractAddr.isInAbstractNamespace());
140

141
// Address validation
142
if (addr1.exists()) {
143
    System.out.println("Socket file exists");
144
}
145
if (addr1.hasFilename()) {
146
    System.out.println("Address has filename: " + addr1.getFile().getName());
147
}
148
```
149

150
### Address Creation Patterns
151

152
Common patterns for creating socket addresses in different scenarios:
153

154
```java
155
// Server socket binding
156
public AFUNIXSocketAddress createServerAddress() throws IOException {
157
    // Use temporary file for ephemeral server
158
    return AFUNIXSocketAddress.ofNewTempFile();
159
}
160

161
// Client connection address
162
public AFUNIXSocketAddress createClientAddress(String serviceName) throws AFException {
163
    // Connect to well-known service socket
164
    File serviceSocket = new File("/var/run/" + serviceName + ".sock");
165
    return AFUNIXSocketAddress.of(serviceSocket);
166
}
167

168
// Application-specific socket
169
public AFUNIXSocketAddress createAppSocket(String appName) throws AFException {
170
    String userHome = System.getProperty("user.home");
171
    File socketFile = new File(userHome + "/.config/" + appName + "/socket");
172
    return AFUNIXSocketAddress.of(socketFile);
173
}
174

175
// Process-specific socket
176
public AFUNIXSocketAddress createProcessSocket() throws AFException {
177
    long pid = ProcessHandle.current().pid();
178
    String socketPath = "/tmp/app-" + pid + ".sock";
179
    return AFUNIXSocketAddress.of(socketPath);
180
}
181
```
182

183
### AFSocketAddress (Base Class)
184

185
Abstract base class for all AF socket address implementations.
186

187
```java { .api }
188
/**
189
 * Base class for all AF socket addresses
190
 */
191
public abstract class AFSocketAddress extends SocketAddress {
192
    
193
    // Address comparison
194
    public abstract boolean equals(Object obj);
195
    public abstract int hashCode();
196
    public abstract String toString();
197
    
198
    // Address properties
199
    public abstract byte[] getBytes();
200
    public abstract int getAddressFamily();
201
    
202
    // Utility methods
203
    public abstract boolean hasFilename();
204
    public abstract String getHostname();
205
}
206
```
207

208
### Other Socket Address Types
209

210
Address implementations for other socket families supported by junixsocket:
211

212
```java { .api }
213
/**
214
 * TIPC socket addressing for cluster communication
215
 */
216
public final class AFTIPCSocketAddress extends AFSocketAddress {
217
    public static AFTIPCSocketAddress of(int type, int instance);
218
    public static AFTIPCSocketAddress of(int type, int instance, int scope);
219
    
220
    public int getType();
221
    public int getInstance();  
222
    public int getScope();
223
}
224

225
/**
226
 * VSOCK socket addressing for VM communication
227
 */
228
public final class AFVSOCKSocketAddress extends AFSocketAddress {
229
    public static AFVSOCKSocketAddress of(int cid, int port);
230
    
231
    public int getCID();
232
    public int getPort();
233
}
234

235
/**
236
 * AF_SYSTEM socket addressing for macOS system communication
237
 */
238
public final class AFSYSTEMSocketAddress extends AFSocketAddress {
239
    public static AFSYSTEMSocketAddress of(int id);
240
    
241
    public int getSystemID();
242
}
243
```
244

245
**Usage Examples for Other Address Types:**
246

247
```java
248
// TIPC addressing (Linux cluster communication)
249
AFTIPCSocketAddress tipcAddr = AFTIPCSocketAddress.of(1000, 1, 2);
250
System.out.println("TIPC - Type: " + tipcAddr.getType() + 
251
                   ", Instance: " + tipcAddr.getInstance() +
252
                   ", Scope: " + tipcAddr.getScope());
253

254
// VSOCK addressing (VM communication)  
255
AFVSOCKSocketAddress vsockAddr = AFVSOCKSocketAddress.of(2, 1234);
256
System.out.println("VSOCK - CID: " + vsockAddr.getCID() + 
257
                   ", Port: " + vsockAddr.getPort());
258

259
// AF_SYSTEM addressing (macOS system communication)
260
AFSYSTEMSocketAddress systemAddr = AFSYSTEMSocketAddress.of(1);
261
System.out.println("System ID: " + systemAddr.getSystemID());
262
```
263

264
## Address Management
265

266
### Address Pooling
267

268
Efficient address object reuse using the built-in pooling system:
269

270
```java { .api }
271
/**
272
 * Object pool for socket addresses
273
 */
274
public class SocketAddressPool extends ObjectPool<AFSocketAddress> {
275
    public static SocketAddressPool getInstance();
276
    
277
    public AFSocketAddress acquire();
278
    public void release(AFSocketAddress address);
279
}
280

281
/**
282
 * Mutable socket address for efficient reuse
283
 */
284
public class MutableSocketAddress {
285
    public void set(AFSocketAddress address);
286
    public AFSocketAddress get();
287
    public void clear();
288
}
289
```
290

291
**Usage Examples:**
292

293
```java
294
// Using address pool for high-frequency operations
295
SocketAddressPool pool = SocketAddressPool.getInstance();
296

297
// Acquire address from pool
298
AFSocketAddress pooledAddr = pool.acquire();
299
try {
300
    // Use address for socket operations
301
    AFUNIXSocket socket = AFUNIXSocket.connectTo((AFUNIXSocketAddress) pooledAddr);
302
    // ... socket operations
303
} finally {
304
    // Return to pool for reuse
305
    pool.release(pooledAddr);
306
}
307

308
// Mutable address for dynamic addressing
309
MutableSocketAddress mutableAddr = new MutableSocketAddress();
310
for (int i = 0; i < 10; i++) {
311
    AFUNIXSocketAddress addr = AFUNIXSocketAddress.of("/tmp/socket-" + i + ".sock");
312
    mutableAddr.set(addr);
313
    
314
    // Use mutable address
315
    AFSocketAddress current = mutableAddr.get();
316
    // ... address operations
317
    
318
    mutableAddr.clear();
319
}
320
```
321

322
## Advanced Addressing Features
323

324
### Address Validation and Properties
325

326
```java { .api }
327
// File system integration
328
public boolean exists();
329
public File getFile() throws FileNotFoundException;
330
public Path getPath() throws FileNotFoundException;
331

332
// Address properties
333
public boolean hasFilename();
334
public boolean isInAbstractNamespace();
335
public String getPathname();
336
public String getHostname();
337

338
// Binary representation
339
public byte[] getBytes();
340
public int getAddressFamily();
341
```
342

343
**Validation Examples:**
344

345
```java
346
AFUNIXSocketAddress addr = AFUNIXSocketAddress.of("/tmp/service.sock");
347

348
// Check if socket file exists
349
if (addr.exists()) {
350
    System.out.println("Socket file exists at: " + addr.getFile());
351
} else {
352
    System.out.println("Socket file does not exist, server may not be running");
353
}
354

355
// Address properties
356
System.out.println("Has filename: " + addr.hasFilename());
357
System.out.println("Pathname: " + addr.getPathname());
358
System.out.println("Is abstract: " + addr.isInAbstractNamespace());
359

360
// Binary representation for low-level operations
361
byte[] addressBytes = addr.getBytes();
362
int family = addr.getAddressFamily();
363
System.out.println("Address family: " + family);
364
System.out.println("Address bytes length: " + addressBytes.length);
365
```
366

367
### Abstract Namespace (Linux)
368

369
Linux-specific abstract namespace support for sockets not bound to filesystem:
370

371
```java
372
// Create abstract socket (Linux only)
373
AFUNIXSocketAddress abstractAddr = AFUNIXSocketAddress.inAbstractNamespace("my-service");
374

375
// Check if in abstract namespace
376
if (abstractAddr.isInAbstractNamespace()) {
377
    System.out.println("Using abstract namespace: " + abstractAddr.getPathname());
378
    // Note: pathname will start with null byte for abstract sockets
379
}
380

381
// Abstract sockets don't have files
382
try {
383
    File file = abstractAddr.getFile();
384
} catch (FileNotFoundException e) {
385
    System.out.println("Abstract sockets don't have filesystem entries");
386
}
387
```
388

389
## Error Handling
390

391
Common addressing-related exceptions:
392

393
```java { .api }
394
// Address creation failures
395
public class AFException extends IOException;
396

397
// File system related errors
398
public class FileNotFoundException extends IOException;
399
public class AddressUnavailableSocketException extends SocketException;
400
```
401

402
**Error Handling Examples:**
403

404
```java
405
try {
406
    AFUNIXSocketAddress addr = AFUNIXSocketAddress.of("/invalid/path/socket.sock");
407
    File socketFile = addr.getFile();
408
} catch (AFException e) {
409
    System.err.println("Failed to create socket address: " + e.getMessage());
410
} catch (FileNotFoundException e) {
411
    System.err.println("Socket file not found: " + e.getMessage());
412
}
413

414
// Validate directory exists before creating socket address
415
File socketDir = new File("/var/run/myapp");
416
if (!socketDir.exists()) {
417
    if (!socketDir.mkdirs()) {
418
        throw new IOException("Cannot create socket directory: " + socketDir);
419
    }
420
}
421

422
File socketFile = new File(socketDir, "service.sock");
423
AFUNIXSocketAddress addr = AFUNIXSocketAddress.of(socketFile);
424
```