or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

addressing.mdcapabilities.mddatagram-sockets.mdexceptions.mdfile-descriptors.mdindex.mdnio-channels.mdrmi.mdsocket-pairs.mdunix-sockets.mdutilities.md
tile.json

tessl/maven-com-kohlschutter-junixsocket--junixsocket-core

Java Unix Domain Socket implementation providing AF_UNIX, AF_TIPC, AF_VSOCK, and AF_SYSTEM socket support with traditional and NIO APIs

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.kohlschutter.junixsocket/junixsocket-core@2.10.x

To install, run

npx @tessl/cli install tessl/maven-com-kohlschutter-junixsocket--junixsocket-core@2.10.0

index.mddocs/

junixsocket-core

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.

Package Information

  • Package Name: com.kohlschutter.junixsocket:junixsocket-core
  • Package Type: Maven
  • Language: Java
  • Installation: See Maven Dependency section

Maven Dependency

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

<dependency>
  <groupId>com.kohlschutter.junixsocket</groupId>
  <artifactId>junixsocket-core</artifactId>
  <version>2.10.1</version>
  <type>pom</type>
</dependency>

This meta-dependency includes:

  • junixsocket-common: Main API implementation
  • junixsocket-native-common: Native library support

Core Imports

import org.newsclub.net.unix.AFUNIXSocket;
import org.newsclub.net.unix.AFUNIXServerSocket;
import org.newsclub.net.unix.AFUNIXDatagramSocket;
import org.newsclub.net.unix.AFUNIXSocketAddress;

For NIO support:

import org.newsclub.net.unix.AFUNIXSocketChannel;
import org.newsclub.net.unix.AFUNIXServerSocketChannel;
import org.newsclub.net.unix.AFUNIXDatagramChannel;
import org.newsclub.net.unix.AFUNIXSelectorProvider;
import org.newsclub.net.unix.AFUNIXProtocolFamily;

For advanced features:

import org.newsclub.net.unix.AFUNIXSocketCredentials;
import org.newsclub.net.unix.AFUNIXSocketPair;
import org.newsclub.net.unix.AFPipe;
import org.newsclub.net.unix.AFSocketCapability;

Basic Usage

Simple Client-Server Communication

import java.io.*;
import java.nio.charset.StandardCharsets;
import org.newsclub.net.unix.*;

// Server
File socketFile = new File("/tmp/junixsocket-example.sock");
try (AFUNIXServerSocket server = AFUNIXServerSocket.newInstance()) {
    server.bind(AFUNIXSocketAddress.of(socketFile));
    
    try (AFUNIXSocket clientSocket = server.accept();
         InputStream is = clientSocket.getInputStream();
         OutputStream os = clientSocket.getOutputStream()) {
        
        // Send greeting
        os.write("Hello, Client!".getBytes(StandardCharsets.UTF_8));
        os.flush();
        
        // Read response
        byte[] buffer = new byte[128];
        int bytesRead = is.read(buffer);
        String response = new String(buffer, 0, bytesRead, StandardCharsets.UTF_8);
        System.out.println("Client says: " + response);
    }
}

// Client
try (AFUNIXSocket socket = AFUNIXSocket.connectTo(AFUNIXSocketAddress.of(socketFile));
     InputStream is = socket.getInputStream();
     OutputStream os = socket.getOutputStream()) {
    
    // Read greeting
    byte[] buffer = new byte[128];
    int bytesRead = is.read(buffer);
    String greeting = new String(buffer, 0, bytesRead, StandardCharsets.UTF_8);
    System.out.println("Server says: " + greeting);
    
    // Send response
    os.write("Hello, Server!".getBytes(StandardCharsets.UTF_8));
    os.flush();
}

Architecture

junixsocket-core is built around several key components:

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

Capabilities

Unix Domain Sockets

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

// Core socket classes
public final class AFUNIXSocket extends AFSocket implements AFUNIXSocketExtensions;
public final class AFUNIXServerSocket extends AFServerSocket;
public final class AFUNIXDatagramSocket extends AFDatagramSocket;

// Factory methods
public static AFUNIXSocket connectTo(AFUNIXSocketAddress addr) throws IOException;
public static AFUNIXSocket newInstance() throws IOException;
public static AFUNIXSocket newStrictInstance() throws IOException;
public static AFUNIXServerSocket newInstance() throws IOException;
public static AFUNIXServerSocket bindOn(AFUNIXSocketAddress addr) throws IOException;
public static AFUNIXDatagramSocket newInstance() throws IOException;

Unix Domain Sockets

Socket Addressing

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

public abstract class AFSocketAddress extends SocketAddress;
public final class AFUNIXSocketAddress extends AFSocketAddress;

// Address creation
public static AFUNIXSocketAddress of(File socketFile) throws AFException;
public static AFUNIXSocketAddress of(Path socketPath) throws AFException;
public static AFUNIXSocketAddress ofNewTempFile() throws IOException;

Socket Addressing

NIO Channel Support

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

public final class AFUNIXSocketChannel extends AFSocketChannel implements AFUNIXSocketExtensions;
public final class AFUNIXServerSocketChannel extends AFServerSocketChannel;
public final class AFUNIXDatagramChannel extends AFDatagramChannel;
public final class AFUNIXSelectorProvider extends AFSelectorProvider;

// Channel creation
public static AFUNIXSocketChannel open() throws IOException;
public static AFUNIXSocketChannel open(AFUNIXSocketAddress remote) throws IOException;
public static AFUNIXServerSocketChannel open() throws IOException;
public static AFUNIXDatagramChannel open() throws IOException;

NIO Channels

RMI Integration

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

public class AFUNIXRMISocketFactory extends AFRMISocketFactory;
public interface AFRMIService;

// RMI setup
public static AFUNIXRMISocketFactory getInstance() throws IOException;

RMI Integration

Exception Handling

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

public class AFException extends IOException;
public class SocketClosedException extends SocketException;
public class AddressUnavailableSocketException extends SocketException;
public class BrokenPipeSocketException extends SocketException;

Exception Handling

Socket Capabilities

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

public enum AFSocketCapability;
public enum AFUNIXSocketCapability;
public class AFSocketCapabilityRequirement;

// Capability testing
public boolean isSupported();
public static AFSocketCapabilityRequirement require(AFSocketCapability capability);

Socket Capabilities

Datagram Sockets

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

public final class AFUNIXDatagramSocket extends AFDatagramSocket;
public final class AFUNIXDatagramChannel extends AFDatagramChannel;

// Factory methods
public static AFUNIXDatagramSocket newInstance() throws IOException;
public static AFUNIXDatagramChannel open() throws IOException;

Datagram Sockets

Socket Pairs and Pipes

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

public final class AFUNIXSocketPair extends AFSocketPair;
public final class AFPipe extends Pipe;

// Pair creation
public static AFUNIXSocketPair open() throws IOException;
public static AFPipe open() throws IOException;

Socket Pairs and Pipes

File Descriptor Operations

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

interface AFUNIXSocketExtensions {
    FileDescriptor[] getReceivedFileDescriptors() throws IOException;
    void setOutboundFileDescriptors(FileDescriptor... fds) throws IOException;
    AFUNIXSocketCredentials getPeerCredentials() throws IOException;
}

public final class AFUNIXSocketCredentials {
    public long getPid();
    public long getUid();
    public long getGid();
    public long[] getGids();
}

File Descriptor Operations

Utility Classes

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

public class FileDescriptorAccess;
public class PeerCredentials;
public class AFUNIXSocketFactory extends AFSocketFactory;
public class NativeLibraryLoader;
public class NativeUnixSocket;

// Key utilities
public static FileDescriptor getFileDescriptor(AFSocket socket) throws IOException;
public static PeerCredentials fromSocket(AFUNIXSocket socket) throws IOException;
public static boolean isNativeLibraryLoaded();

Utility Classes

Other Socket Types

Other Socket Types

TIPC Sockets

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

public final class AFTIPCSocket extends AFSocket;
public final class AFTIPCSocketAddress extends AFSocketAddress;
public final class AFTIPCSocketChannel extends AFSocketChannel;
public final class AFTIPCDatagramSocket extends AFDatagramSocket;

VSOCK Sockets

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

public final class AFVSOCKSocket extends AFSocket;  
public final class AFVSOCKSocketAddress extends AFSocketAddress;
public final class AFVSOCKSocketChannel extends AFSocketChannel;
public final class AFVSOCKDatagramSocket extends AFDatagramSocket;

AF_SYSTEM Sockets

AF_SYSTEM socket support for macOS system-level communication.

public final class AFSYSTEMSocket extends AFSocket;
public final class AFSYSTEMSocketAddress extends AFSocketAddress;
public final class AFSYSTEMSocketChannel extends AFSocketChannel;

Protocol Support Enums

public enum AFUNIXProtocolFamily implements ProtocolFamily {
    UNIX;
    
    public SocketChannel openSocketChannel() throws IOException;
    public ServerSocketChannel openServerSocketChannel() throws IOException;
    public DatagramChannel openDatagramChannel() throws IOException;
}

public enum AFSocketType {
    SOCK_STREAM, SOCK_DGRAM, SOCK_RAW, SOCK_RDM, SOCK_SEQPACKET
}

public enum AFSocketProtocol {
    DEFAULT
}