mcfunley / juds

A Unix domain socket library for Java

JUDS

ABSTRACT

Java Unix Domain Sockets (JUDS) provide classes to address the need in Java for accessing Unix domain sockets. The source is provided for a shared library containing the compiled native C code, which is called into by the Java UnixDomainSocket classes via JNI (Java Native Interface) to open, close, unlink (delete), read, and write to Unix domain sockets.

DESCRIPTION

JUDS is similar with and inspired by J-BUDS. However, JUDS has been written to have more performance than J-BUDS while supplying all features Unix domain sockets have. JUDS consists of an abstract class UnixDomainSocket and two derived classes, UnixDomainSocketClient and UnixDomainSocketServer. It can simply be used by instantiating one of the two classes. Through the getInputStream and getOutputStream methods, the resulting instance can be used to get an InputStream and/or OutputStream object.

From version 0.93 on, UnixDomainSocketServer can be used with accept() to obtain undifferentiated UnixDomainSocket, this allowing to handle multiple clients from the same Server. New API is then used in that case (the previous one remains supported).

Limitations:

Datagram sockets are unidirectional, i.e. trying to get an OutputStream for an UnixDomainSocketServer object results in an UnsupportedOperationException being thrown. Accordingly trying to get an InputStream for an UnixDomainSocketClient also results in such an exception being thrown. With the API before version 0.92, stream sockets can only handle connections between two end points. Trying to connect to an UnixDomainSocketServer which has already accepted a connection with another client will result in an error. With New API (version 0.93 or higher) UnixDomainServerSocket.accept() returns an independent socket for each new incoming connection.

VERSION

Version 0.95 - 2016-02-04

VERSION HISTORY

Version 0.95 - 2016-02-04 - Socket timeout. - Possibility to specify a folder for unpacked native library. - Minor bug fixes.

Version 0.94 - 2010-04-30 - Now builds on OSX. - Build system switched to autoconf. - Native libraries are now embedded in the jar. - Support for universal jars. - Mainline repository moved to: http://github.com/mcfunley/juds. - Refactored native library. - Fixed errant bzero of random memory location. - Minor bug fixes.

Version 0.93 - 2010-01-08 - Extend API with accept(): allow server socket to handle multiple clients. - Simplified API still supported but incompatible with accept(). - Test class for new API (can be use as a sample). - Fix for stream closure detection.

Version 0.92 - 2009-11-05 - Removed the umask() call in UnixDomainSocket.c. As some nice people have told me, changing the umask is evil ;-)

Version 0.9 - 2008-02-07 - Fixed a bug in the nativeCreate() function in UnixDomainSocket.c which was the reason for UnixDomainSocketServer to not work correctly.

Version 0.8 - 2008-12-06 - Fixed UnixDomainSocket.UnixDomainSocketInputStream.read() method in order to return correct results (Thanks to Roman Kosenko!). - Rearranged test, made it more comprehensible. Now the test can be launched by running the make target 'test'. There isn't any additional operation from the user required anymore (Thanks to Roman Kosenko!). - Introduced package structure (com.google.code.juds), improved Makefile. - Added unlink(socketFile) calls in UnixDomainSocket.c for the case of failing listen() or accept() calls to remove the unused socket file (Thanks Alan Harder!).

Version 0.7 - 2008-07-16 - Made changes to the makefile. This fixes some issues for building under non-Linux platforms. - Added a note how to fix an issue under cygwin to the documentation. - Restructured the documentation.

Version 0.6 - 2008-06-03 - Made some minor refactoring and orthographical corrections. No difference in functionality to version 0.5.

Version 0.5 - 2008-03-05 - Initial version

INSTALLATION

The java UnixDomainSocket classes use native methods in order to access AF_UNIX sockets for interprocess communication. JUDS can be installed by using the included makefile. IMPORTANT NOTE: In order for the compilation process to work, it is likely that you need to change one or more of the top four variables in the makefile. By example please select you right jdk by edeting Makefile JAVA_HOME .

You should also make sure you have the 'autoconf' and 'libc6-dev-i386' packages installed. A installation process could look like this:

sudo apt-get install libc6-dev-i386 autoconf
./autoconf.sh
./configure
make
sudo make install

make install does nothing more than copying the shared library libunixdomainsocket.so to the /usr/lib directory. Alternatively you can also set the variable LD_LIBRARY_PATH to include the directory where libunixdomainsocket.so is located.

TESTING

To test the installation, simply run the make target 'test': make test

TROUBLESHOOTING

There might be issues with gcc under cygwin because the type __int64 used in jni.h is not defined. Here are some proposals how that can be fixed: http://maba.wordpress.com/2004/07/28/generating-dll-files-for-jni-under-windowscygwingcc/ (see also the comments)

Please send bug reports and comments to [email protected].

LICENSE

This library is free software; you can redistribute it and/or modify it under the terms of version 2.1 of the GNU Lesser General Public License as published by the Free Software Foundation.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details:

http://www.opensource.org/licenses/lgpl-license.html http://www.gnu.org/copyleft/lesser.html

To obtain a written copy of the GNU Lesser General Public License, please write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

CONTRIBUTORS

Klaus Trainer - original author.

Philippe Lhardy

Mathias Herberts

Richard Moats

Dan McKinley - current maintainer.

ACKNOWLEDGMENTS

JUDS has been inspired by Robert Morgan's J-BUDS (Java Based Unix Domain Sockets) which is licensed under the GNU Lesser General Public License version 2.1 as well.

juds's Issues

configure bails under jdk7

configure: error: The java compiler /usr/lib/jvm/java-7-openjdk-amd64/bin/javac does not seem to be version 1.6 (try setting JAVA_HOME)?

The JUDS.jarUrl url might contain jar://

The jarUrl may contain jar:// scheme if detected from source code which later fails on new File(JUDS.jarFile.toURI()).

It reads no more than 8192 bytes

For small amount of data, everything is fine. For more than 8192 bytes it reads only first 8192 bytes. DSo 'BYTES READED' is never more than 8192. Desn't matter what is bufferSize value:

`

public String exec(String channelId, String requestJson) throws RpcException {
	try {
		Require.notNull(channelId, "channelId");
		Require.notNull(requestJson, "requestJson");
		
		String respStr = null;

		UnixDomainSocketClient socket = channels.get(channelId);
		if (socket == null) {
			socket = new UnixDomainSocketClient(socketFilePath, JUDS.SOCK_STREAM);
			channels.put(channelId, socket);
		}

		InputStream in = socket.getInputStream();
		OutputStream out = socket.getOutputStream();
		
		try {
			PrintWriter w = new PrintWriter(out);
			w.print(requestJson);
			w.flush();
		} catch (Throwable ex) {
			throw new Exception("Cannot send request \"" + requestJson + "\" to c-lightning RPC socket", ex);
		}

		try {
			InputStreamReader r = new InputStreamReader(in);

			CharBuffer respChBuf = CharBuffer.allocate(bufferSize);
			
			StringBuilder resp = new StringBuilder();
			int bytesRead;
			do {
				bytesRead = r.read(respChBuf);
				LOGGER.debug("Readed bytes: " + bytesRead);
				if(bytesRead > 0) {
					respChBuf.flip();
					resp.append(respChBuf.toString());
				}
			} while(bytesRead == bufferSize);
			respStr = resp.toString();
			LOGGER.info("BYTES READED: " + resp.length());
		} catch (Throwable ex) {
			throw new Exception("Cannot get response from c-lightning RPC socket", ex);
		}
		return Require.notNull(respStr, "respStr");
	} catch (Throwable ex) {
		throw new RpcException("Cannot execute request '" + requestJson + "'", ex);
	}
}`

parameters in file Makefiles.in

I am kind of new to Ubuntu and this unix domain socket things
what are the meaning of the following parameters that I need to specify in Makefiles.in?

NAIVELIB
M32
M64
LIBEXT

I get stuck here for a long time T-T
thank you so much if can help !

Socket timeout

There seems to be two socket timeouts. One hardcoded in C for 10 s. The other one configurable in Java code for read using the Thread. Both seems to be wrong as the first one is hardcoded while the second introduces the thread leak.

Allow SOCK_SEQPACKET and other socket types.

Thank you for the great library. Could I suggest a small improvement, which would allow any native OS sock types to be passed in from java? Something like the following could work:

In UnixDomainSocket.c, could I suggest changing:
s = socket(PF_UNIX, SOCK_TYPE(jSocketType), 0);
to:
s = socket(PF_UNIX, jSocketType, 0);
This would allow SOCK_SEQPACKET to be specified.

This would allow any sock type to be passed to the os.

To maintain compatibility with existing impls and OS's, you could detect and populate the type constants at compile and classload times:
jint Java_com_etsy_net_UnixDomainSocket_nativeSockTypeVal(jstring val){
#ifdef SOCK_STREAM
if(0==strcmp(val,"SOCK_STREAM")) return SOCK_STREAM;
#endif
#ifdef SOCK_DGRAM
if(0==strcmp(val,"SOCK_DGRAM")) return SOCK_DGRAM;
#endif
#ifdef SOCK_SEQPACKET
if(0==strcmp(val,"SOCK_SEQPACKET")) return SOCK_SEQPACKET;
#endif
// etc.... for different known enums
return -1;
}

//Add a quick static wrapper in UnixDomainSocket.java
//then in JUDS.java
static{
SOCK_STREAM = UnixDomainSocket.SockTypeVal("SOCK_STREAM");
SOCK_DGRAM = UnixDomainSocket.SockTypeVal("SOCK_DGRAM");
SOCK_SEQPACKET = UnixDomainSocket.SockTypeVal("SOCK_SEQPACKET");
//etc...
};

Thanks!

UnixDomainSocketInputStream.read throws IOException

when calling read() and read(byte[], int, int) a lot of IOExceptions are thrown.
When looking at the code I found this:

 count = nativeRead(nativeSocketFileHandle, b, 0, 1);
                if (count == -1)
                    throw new IOException();

Should that throws statement really be there?
After removing it and rebuilt, it seams to work better.

socket fds are left open if connect fails

Hi,

nativeOpen() creates a socket file description and tries to connect to server. If the connect fails
an error is rightfully returned but the socket is never closed. The misbehaving code:

s = socket(PF_UNIX, SOCK_TYPE(jSocketType), 0);
ASSERTNOERR(s == -1, "nativeOpen: socket");
ASSERTNOERR(connect(s, (struct sockaddr *)&sa, salen) == -1,
        "nativeOpen: connect");

I fixed it by adding a close statement to the assert but the solution might not open to the casual
reader very easily. A better solution would be appreciated.

/* close returns either -1 or 0 */
ASSERTNOERR(connect(s, (struct sockaddr *)&sa, salen) == -1 && close(s) < 1,
        "nativeOpen: connect");

Support ARM processors such as the Raspberry Pi

I have it working on my Raspberry Pi (using my fork here: https://github.com/joeferner/juds) but it requires removing the x86 and x64 targets since Raspberry Pi doesn't support cross compiling.

PR #8 breaks compilation (JUDSDIR not defined)

PR #8 references JUDSDIR that is not defined anywhere

Allow asynchronous close of the socket

If there is blocking read operation in progress (without any data provided by the socket) and another thread closes the socket the reading thread is still blocked. It seems to be resolved by shutting down the connections before closing the socket.

Maven

Please setup a maven directory for this. :)

Allow user to specify path for extracted native library

This should be achieved by system property.

Support for Linux abstract namespace.

First off, thanks for JUDS, it's really helpful.

I've slightly modified the code to support the Linux abstract namespace. In UnixDomainSocket.c, in the method sockaddr_init, I've added the following:

// Linux abstract namespace
if (socketFile[0]=='@')
sa->sun_path[0] = 0;

The following code connects to a domain socket in the abstract namespace:

UnixDomainSocketClient socket = new UnixDomainSocketClient("@some_socket" JUDS.SOCK_STREAM);
socket.getOutputStream().write("Ohai!".getBytes());
socket.close();

It might be nice to either merge this two-line fix, or perhaps support the abstract namespace in another way.

Allow setting the file mode of the socket before listening on it

I need my socket to have mode 0600 but I can't find any way to do this.