uds-jca-adapter

Description

A JCA 1.7 compliant Resource Adapter RAR to accept Unix Domain Socket (UDS) connections with full modern Java EE facilities in a fast memory safe language.

Motivation / Use Case

Do you want to accept Unix Domain Socket connections in Java, but have full access to CDI, JAX-RS, JPA, SQL, JTA, etc?

Simply implement the UDSMessageListener interface:

import javax.ejb.MessageDriven;
import javax.ejb.ActivationConfigProperty;

import com.github.exabrial.jca.uds.UDSMessageListener;

@MessageDriven(activationConfig = {
		@ActivationConfigProperty(propertyName = "socketLocation", propertyValue = "/tmp/myapp.sock") })
public class UDSDumper implements UDSMessageListener {
	@Inject
	private Logger log;

	@Override
	public byte[] onPacket(final byte[] payload) {
		log.info("onPacket() payload length:{}", payload.length);
		return null;
	}
}

Transport Modes

The adapter supports two transport modes:

• Packet Mode (default): The client writes the payload then calls shutdownOutput() to signal EOF. The server reads until EOF, processes the message, writes the reply, and closes the connection. One request-reply per connection.
• Newline Mode (newlineMode=true): Messages are newline-delimited (\n). The connection stays open for multiple request-reply exchanges.

Maven Coordinates

The API jar contains the interface you need to implement.

		<dependency>
			<groupId>com.github.exabrial</groupId>
			<artifactId>uds-jca-adapter-api</artifactId>
			<version>1.0.0</version>
			<scope>compile</scope>
		</dependency>

Installation

RAR installation by app server differs greatly by server. Most of the time you install a JCA adapter at the EAR or server level.

Easiest deployment: Apache TomEE 8.0.4+ embedded war deployment

To deploy at the Application level, add the following to your app's pom.xml, then copy the ra.xml into your WEB-INF directory.

		<dependency>
			<groupId>com.github.exabrial</groupId>
			<artifactId>uds-jca-adapter</artifactId>
			<version>1.0.0</version>
			<scope>runtime</scope>
		</dependency>

Configuration

Resource Adapter Properties (global defaults)

These are global fallback values. Activation spec properties override these when set.

config option	type	default
appendNewline	Boolean
maxPacketSize	Integer	32768
newlineEscapeChar	String	\n
socketPermissions	String	770

Activation Spec Properties (per MDB)

config option	type	required	default
socketLocation	String	yes
appendNewline	Boolean	no	falls back to RA property, then true in newline mode, false in packet mode
maxPacketSize	Integer	no	falls back to RA property, then 32768
newlineEscapeChar	String	no	falls back to RA property, then \n in newline mode, null in packet mode
newlineMode	Boolean	no	false
socketPermissions	String	no	falls back to RA property, then 770

appendNewline

When true, the adapter appends a \n byte after each reply. In newline mode this is required for the client to detect message boundaries, so it defaults to true. In packet mode the connection close signals EOF, so it defaults to false.

maxPacketSize

Maximum number of bytes the adapter will read for a single message. In packet mode, payloads exceeding this size are discarded. In newline mode, this is the read buffer size.

newlineEscapeChar

When set, all literal \n characters within reply payloads are replaced with this string before writing the reply. This prevents embedded newlines from breaking newline-delimited framing. Defaults to \n (the literal two-character string) in newline mode and null (disabled) in packet mode.

newlineMode

When true, the adapter uses newline-delimited framing on a persistent connection. When false (default), the adapter uses EOF-based packet mode with one connection per request.

socketPermissions

POSIX file permissions applied to the socket file, specified as a 3-digit octal string (e.g. 770).

License and other boring legal notes

• All files in this project are copyrighted
• All files in this project are licensed under EUPL-1.2
  • This license allows you to safely use this code in closed-source commercial projects, without ever having to reveal your company's proprietary application code
  • However: note that if you modify/extend uds-jca-adapter, and offer online access to apps through a modified/extended uds-jca-adapter, it is required by law that the source code for your uds-jca-adapter changeset be made available first, before offering said access to your app
  • Again, this does not include your proprietary application source code, just the changeset to uds-jca-adapter
• Java, Apache, TomEE, and other names are trademarks; this project is not endorsed by nor affiliated with them