0
# junixsocket-core
1

2
junixsocket-core is a comprehensive Java library that enables the use of Unix Domain Sockets (AF_UNIX) and other address/protocol families (AF_TIPC, AF_VSOCK, AF_SYSTEM) from Java applications. It provides both traditional Java Socket API and NIO channel support with complete inter-process communication capabilities.
3

4
## Package Information
5

6
- **Package Name**: com.kohlschutter.junixsocket:junixsocket-core  
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: See [Maven Dependency](#maven-dependency) section
10

11
## Maven Dependency
12

13
Since version 2.4.0, junixsocket-core is POM-only, so you must specify `<type>pom</type>`:
14

15
```xml
16
<dependency>
17
  <groupId>com.kohlschutter.junixsocket</groupId>
18
  <artifactId>junixsocket-core</artifactId>
19
  <version>2.10.1</version>
20
  <type>pom</type>
21
</dependency>
22
```
23

24
This meta-dependency includes:
25
- `junixsocket-common`: Main API implementation
26
- `junixsocket-native-common`: Native library support
27

28
## Core Imports
29

30
```java
31
import org.newsclub.net.unix.AFUNIXSocket;
32
import org.newsclub.net.unix.AFUNIXServerSocket;
33
import org.newsclub.net.unix.AFUNIXDatagramSocket;
34
import org.newsclub.net.unix.AFUNIXSocketAddress;
35
```
36

37
For NIO support:
38

39
```java
40
import org.newsclub.net.unix.AFUNIXSocketChannel;
41
import org.newsclub.net.unix.AFUNIXServerSocketChannel;
42
import org.newsclub.net.unix.AFUNIXDatagramChannel;
43
import org.newsclub.net.unix.AFUNIXSelectorProvider;
44
import org.newsclub.net.unix.AFUNIXProtocolFamily;
45
```
46

47
For advanced features:
48

49
```java
50
import org.newsclub.net.unix.AFUNIXSocketCredentials;
51
import org.newsclub.net.unix.AFUNIXSocketPair;
52
import org.newsclub.net.unix.AFPipe;
53
import org.newsclub.net.unix.AFSocketCapability;
54
```
55

56
## Basic Usage
57

58
### Simple Client-Server Communication
59

60
```java
61
import java.io.*;
62
import java.nio.charset.StandardCharsets;
63
import org.newsclub.net.unix.*;
64

65
// Server
66
File socketFile = new File("/tmp/junixsocket-example.sock");
67
try (AFUNIXServerSocket server = AFUNIXServerSocket.newInstance()) {
68
    server.bind(AFUNIXSocketAddress.of(socketFile));
69
    
70
    try (AFUNIXSocket clientSocket = server.accept();
71
         InputStream is = clientSocket.getInputStream();
72
         OutputStream os = clientSocket.getOutputStream()) {
73
        
74
        // Send greeting
75
        os.write("Hello, Client!".getBytes(StandardCharsets.UTF_8));
76
        os.flush();
77
        
78
        // Read response
79
        byte[] buffer = new byte[128];
80
        int bytesRead = is.read(buffer);
81
        String response = new String(buffer, 0, bytesRead, StandardCharsets.UTF_8);
82
        System.out.println("Client says: " + response);
83
    }
84
}
85

86
// Client
87
try (AFUNIXSocket socket = AFUNIXSocket.connectTo(AFUNIXSocketAddress.of(socketFile));
88
     InputStream is = socket.getInputStream();
89
     OutputStream os = socket.getOutputStream()) {
90
    
91
    // Read greeting
92
    byte[] buffer = new byte[128];
93
    int bytesRead = is.read(buffer);
94
    String greeting = new String(buffer, 0, bytesRead, StandardCharsets.UTF_8);
95
    System.out.println("Server says: " + greeting);
96
    
97
    // Send response
98
    os.write("Hello, Server!".getBytes(StandardCharsets.UTF_8));
99
    os.flush();
100
}
101
```
102

103
## Architecture
104

105
junixsocket-core is built around several key components:
106

107
- **Core Socket Implementation**: Traditional Java Socket API (`AFUNIXSocket`, `AFUNIXServerSocket`) for familiar stream-based communication
108
- **Address Management**: Flexible addressing system (`AFUNIXSocketAddress`) supporting file paths and abstract namespace
109
- **NIO Integration**: Complete NIO support (`AFUNIXSocketChannel`, `AFUNIXServerSocketChannel`) for high-performance, non-blocking I/O
110
- **Multi-Protocol Support**: Extensions for TIPC, VSOCK, and AF_SYSTEM protocols beyond Unix Domain Sockets
111
- **Native Integration**: Seamless JNI bridge providing cross-platform native socket implementations
112
- **RMI Support**: Remote Method Invocation over Unix sockets for efficient inter-process communication
113

114
## Capabilities
115

116
### Unix Domain Sockets
117

118
Traditional and NIO-based Unix Domain Socket implementations for high-performance inter-process communication using file system paths.
119

120
```java { .api }
121
// Core socket classes
122
public final class AFUNIXSocket extends AFSocket implements AFUNIXSocketExtensions;
123
public final class AFUNIXServerSocket extends AFServerSocket;
124
public final class AFUNIXDatagramSocket extends AFDatagramSocket;
125

126
// Factory methods
127
public static AFUNIXSocket connectTo(AFUNIXSocketAddress addr) throws IOException;
128
public static AFUNIXSocket newInstance() throws IOException;
129
public static AFUNIXSocket newStrictInstance() throws IOException;
130
public static AFUNIXServerSocket newInstance() throws IOException;
131
public static AFUNIXServerSocket bindOn(AFUNIXSocketAddress addr) throws IOException;
132
public static AFUNIXDatagramSocket newInstance() throws IOException;
133
```
134

135
[Unix Domain Sockets](./unix-sockets.md)
136

137
### Socket Addressing
138

139
Comprehensive addressing system supporting file paths, abstract namespace, and other socket families with flexible address creation and management.
140

141
```java { .api }
142
public abstract class AFSocketAddress extends SocketAddress;
143
public final class AFUNIXSocketAddress extends AFSocketAddress;
144

145
// Address creation
146
public static AFUNIXSocketAddress of(File socketFile) throws AFException;
147
public static AFUNIXSocketAddress of(Path socketPath) throws AFException;
148
public static AFUNIXSocketAddress ofNewTempFile() throws IOException;
149
```
150

151
[Socket Addressing](./addressing.md)
152

153
### NIO Channel Support
154

155
High-performance, non-blocking I/O implementation with full Java NIO integration for scalable socket operations and event-driven programming.
156

157
```java { .api }
158
public final class AFUNIXSocketChannel extends AFSocketChannel implements AFUNIXSocketExtensions;
159
public final class AFUNIXServerSocketChannel extends AFServerSocketChannel;
160
public final class AFUNIXDatagramChannel extends AFDatagramChannel;
161
public final class AFUNIXSelectorProvider extends AFSelectorProvider;
162

163
// Channel creation
164
public static AFUNIXSocketChannel open() throws IOException;
165
public static AFUNIXSocketChannel open(AFUNIXSocketAddress remote) throws IOException;
166
public static AFUNIXServerSocketChannel open() throws IOException;
167
public static AFUNIXDatagramChannel open() throws IOException;
168
```
169

170
[NIO Channels](./nio-channels.md)
171

172
### RMI Integration
173

174
Remote Method Invocation support over Unix Domain Sockets enabling efficient distributed computing within the same system.
175

176
```java { .api }
177
public class AFUNIXRMISocketFactory extends AFRMISocketFactory;
178
public interface AFRMIService;
179

180
// RMI setup
181
public static AFUNIXRMISocketFactory getInstance() throws IOException;
182
```
183

184
[RMI Integration](./rmi.md)
185

186
### Exception Handling
187

188
Comprehensive exception hierarchy providing detailed error information for robust socket error handling and debugging.
189

190
```java { .api }
191
public class AFException extends IOException;
192
public class SocketClosedException extends SocketException;
193
public class AddressUnavailableSocketException extends SocketException;
194
public class BrokenPipeSocketException extends SocketException;
195
```
196

197
[Exception Handling](./exceptions.md)
198

199
### Socket Capabilities
200

201
Runtime capability detection and platform support validation for socket features and protocol availability.
202

203
```java { .api }
204
public enum AFSocketCapability;
205
public enum AFUNIXSocketCapability;
206
public class AFSocketCapabilityRequirement;
207

208
// Capability testing
209
public boolean isSupported();
210
public static AFSocketCapabilityRequirement require(AFSocketCapability capability);
211
```
212

213
[Socket Capabilities](./capabilities.md)
214

215
### Datagram Sockets
216

217
DatagramSocket implementation for connectionless Unix Domain Socket communication with packet-based messaging.
218

219
```java { .api }
220
public final class AFUNIXDatagramSocket extends AFDatagramSocket;
221
public final class AFUNIXDatagramChannel extends AFDatagramChannel;
222

223
// Factory methods
224
public static AFUNIXDatagramSocket newInstance() throws IOException;
225
public static AFUNIXDatagramChannel open() throws IOException;
226
```
227

228
[Datagram Sockets](./datagram-sockets.md)
229

230
### Socket Pairs and Pipes
231

232
Interconnected socket pairs and pipe implementations for efficient bidirectional communication between processes.
233

234
```java { .api }
235
public final class AFUNIXSocketPair extends AFSocketPair;
236
public final class AFPipe extends Pipe;
237

238
// Pair creation
239
public static AFUNIXSocketPair open() throws IOException;
240
public static AFPipe open() throws IOException;
241
```
242

243
[Socket Pairs and Pipes](./socket-pairs.md)
244

245
### File Descriptor Operations
246

247
Advanced Unix Domain Socket features including file descriptor passing, peer credentials, and ancillary message handling.
248

249
```java { .api }
250
interface AFUNIXSocketExtensions {
251
    FileDescriptor[] getReceivedFileDescriptors() throws IOException;
252
    void setOutboundFileDescriptors(FileDescriptor... fds) throws IOException;
253
    AFUNIXSocketCredentials getPeerCredentials() throws IOException;
254
}
255

256
public final class AFUNIXSocketCredentials {
257
    public long getPid();
258
    public long getUid();
259
    public long getGid();
260
    public long[] getGids();
261
}
262
```
263

264
[File Descriptor Operations](./file-descriptors.md)
265

266
### Utility Classes
267

268
File descriptor access, peer credentials, socket factories, and native library management for advanced socket operations.
269

270
```java { .api }
271
public class FileDescriptorAccess;
272
public class PeerCredentials;
273
public class AFUNIXSocketFactory extends AFSocketFactory;
274
public class NativeLibraryLoader;
275
public class NativeUnixSocket;
276

277
// Key utilities
278
public static FileDescriptor getFileDescriptor(AFSocket socket) throws IOException;
279
public static PeerCredentials fromSocket(AFUNIXSocket socket) throws IOException;
280
public static boolean isNativeLibraryLoaded();
281
```
282

283
[Utility Classes](./utilities.md)
284

285
## Other Socket Types
286

287
## Other Socket Types
288

289
### TIPC Sockets
290

291
TIPC (Transparent Inter-Process Communication) socket support for cluster communication on Linux systems.
292

293
```java { .api }
294
public final class AFTIPCSocket extends AFSocket;
295
public final class AFTIPCSocketAddress extends AFSocketAddress;
296
public final class AFTIPCSocketChannel extends AFSocketChannel;
297
public final class AFTIPCDatagramSocket extends AFDatagramSocket;
298
```
299

300
### VSOCK Sockets
301

302
VSOCK (Virtual Socket) support for communication between virtual machines and their hosts.
303

304
```java { .api }
305
public final class AFVSOCKSocket extends AFSocket;  
306
public final class AFVSOCKSocketAddress extends AFSocketAddress;
307
public final class AFVSOCKSocketChannel extends AFSocketChannel;
308
public final class AFVSOCKDatagramSocket extends AFDatagramSocket;
309
```
310

311
### AF_SYSTEM Sockets
312

313
AF_SYSTEM socket support for macOS system-level communication.
314

315
```java { .api }
316
public final class AFSYSTEMSocket extends AFSocket;
317
public final class AFSYSTEMSocketAddress extends AFSocketAddress;
318
public final class AFSYSTEMSocketChannel extends AFSocketChannel;
319
```
320

321
## Protocol Support Enums
322

323
```java { .api }
324
public enum AFUNIXProtocolFamily implements ProtocolFamily {
325
    UNIX;
326
    
327
    public SocketChannel openSocketChannel() throws IOException;
328
    public ServerSocketChannel openServerSocketChannel() throws IOException;
329
    public DatagramChannel openDatagramChannel() throws IOException;
330
}
331

332
public enum AFSocketType {
333
    SOCK_STREAM, SOCK_DGRAM, SOCK_RAW, SOCK_RDM, SOCK_SEQPACKET
334
}
335

336
public enum AFSocketProtocol {
337
    DEFAULT
338
}
339
```
340

341