initial import

git-svn-id: http://juds.googlecode.com/svn/trunk@10 c8679d40-244a-0410-9193-c76e7b7dbb69

COPYRIGHT

@@ -0,0 +1,25 @@
+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
+
+
+AUTHOR
+Klaus Trainer
+
+
+ACKNOWLEDGMENT
+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.

README

@@ -0,0 +1,128 @@
+===
+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.
+
+
+VERSION
+=======
+
+Version 0.5 - 2008-03-05
+
+
+HISTORY
+=======
+
+Version History:
+	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.
+
+A installation process could look like this:
+
+	make
+	make install
+
+make install does only copy the shared library libunixdomainsocket.so to the
+/usr/lib directory. Alternatively you can also set the variable LD_LIBRARY_PATH
+so that includes the directory where libunixdomainsocket.so is included.
+
+
+TESTING
+=======
+
+To test the installation, the file TestUnixDomainSocket.java has to be
+compiled. This can be done by simply entering:
+
+	make test
+
+Now a test can be performed through first executing the included python program
+Test_UnixDomainSocket.py with a socket filename as command line argument.
+For example, this could look like this:
+
+	python Test_UnixDomainSocket.py socketfile
+
+Then the Java class file TestUnixDomainSocket.class has to be executed, also
+with the same socket filename as above as command line argument, e.g.:
+
+	java TestUnixDomainSocket socketfile
+
+
+DESCRIPTION
+===========
+
+JUDS is similar with and inspired of 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 the two classes. Through the getInputStream and
+getOutputStream methods, the resulting instance can be used to get an
+InputStream and/or OutputStream object.
+
+Limitations:
+
+Datagram sockets are unidirectional, i.e. trying to get an OutputStream for an
+UnixDomainSocketServer object results in an UnsupportedOperationException being
+thrown. Accordinly trying to get an InputStream for an UnixDomainSocketClient
+also results in such an exception being thrown.
+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.
+
+
+TROUBLESHOOTING
+===============
+
+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
+
+
+AUTHOR
+======
+
+Klaus Trainer
+
+
+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.

TestUnixDomainSocket.java

@@ -0,0 +1,79 @@
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+
+public class TestUnixDomainSocket {
+
+	public static void main(String[] args) throws IOException {
+		if (args.length != 1) {
+			System.out
+					.println("usage: java TestUnixDomainSocket socketfilename");
+			System.exit(1);
+		}
+		String socketFile = args[0];
+
+		byte[] b = new byte[128];
+		UnixDomainSocketClient socket = new UnixDomainSocketClient(socketFile,
+				UnixDomainSocket.SOCK_STREAM);
+		InputStream in = socket.getInputStream();
+		OutputStream out = socket.getOutputStream();
+		System.out.println("Test #1: Test UnixDomainSocketClient\nTestcase "
+				+ "1.1: Test UnixDomainSocketClient with a stream socket...");
+		in.read(b);
+		System.out.println("Text received: \"" + new String(b) + "\"");
+		String text = "Hello! I'm the client!";
+		out.write(text.getBytes());
+		System.out.println("Text sent: " + "\"" + text + "\"");
+		socket.close();
+
+		System.out.println("Testcase 1.2: Test UnixDomainSocketClient with "
+				+ "a datagram socket...");
+		socket = new UnixDomainSocketClient(socketFile,
+				UnixDomainSocket.SOCK_DGRAM);
+		System.out.println("Provoke and catch an "
+				+ "UnsupportedOperationException:");
+		try {
+			in = socket.getInputStream();
+		} catch (UnsupportedOperationException e) {
+			System.out.println("UnsupportedOperationException has been "
+					+ "thrown as expected.");
+		}
+		out = socket.getOutputStream();
+		text = "Hello! I'm the client!";
+		out.write(text.getBytes());
+		System.out.println("Text sent: \"" + text + "\"");
+		socket.close();
+
+		UnixDomainSocketServer ssocket = new UnixDomainSocketServer(socketFile,
+				UnixDomainSocket.SOCK_STREAM);
+		in = ssocket.getInputStream();
+		out = ssocket.getOutputStream();
+		System.out.println("\nTest #2: Test UnixDomainSocketServer\nTestcase "
+				+ "2.1: Test UnixDomainSocketServer with a stream socket...");
+		in.read(b);
+		System.out.println("Text received: \"" + new String(b) + "\"");
+		text = "Hello! I'm the server!";
+		out.write(text.getBytes());
+		System.out.println("Text sent: " + "\"" + text + "\"");
+		ssocket.close();
+		ssocket.unlink();
+
+		System.out.println("Testcase 2.2: Test UnixDomainSocketServer with "
+				+ "a datagram socket...");
+		ssocket = new UnixDomainSocketServer(socketFile,
+				UnixDomainSocket.SOCK_DGRAM);
+		System.out.println("Provoke and catch an "
+				+ "UnsupportedOperationException:");
+		in = ssocket.getInputStream();
+		try {
+			out = ssocket.getOutputStream();
+		} catch (UnsupportedOperationException e) {
+			System.out.println("UnsupportedOperationException has been "
+					+ "thrown as expected.");
+		}
+		in.read(b);
+		System.out.println("Text received: \"" + new String(b) + "\"");
+		ssocket.close();
+		ssocket.unlink();
+	}
+}

Test_UnixDomainSocket.py

@@ -0,0 +1,58 @@
+#!/usr/bin/python
+
+import sys, os, socket, time
+
+BUFSIZE = 128
+
+def main():
+    if len(sys.argv) != 2:
+        print "usage: %s socketfilename" % sys.argv[0]
+        sys.exit(1)
+    socket_file = sys.argv[1]
+
+    print ("Test #1: Test UnixDomainSocketClient\n"
+        "Testcase 1.1: Test UnixDomainSocketClient with a stream socket...")
+    s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    s.bind(socket_file)
+    s.listen(0)
+    client, client_address = s.accept()
+    text = "Hello I'm the server..."
+    client.send(text)
+    print "Text sent: \"Hello I'm the server...\""
+    text = client.recv(BUFSIZE)
+    print "Text received: \"%s\"" % text
+    s.close()
+    os.unlink(socket_file)
+
+    print "Testcase 1.2: Test UnixDomainSocketClient with a datagram socket..."
+    s = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)
+    s.bind(socket_file)
+    text = s.recv(BUFSIZE)
+    print "Text received: \"%s\"" % text
+    s.close()
+    os.unlink(socket_file)
+
+    print ("\nTest #2: Test UnixDomainSocketServer\n"
+        "Testcase 2.1: Test UnixDomainSocketServer with a stream socket...")
+    s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    time.sleep(2)   # wait for the server
+    s.connect(socket_file)
+    text = "Hello I'm the client..."
+    s.send(text)
+    print "Text sent: \"Hello I'm the client...\""
+    text = s.recv(BUFSIZE)
+    print "Text received: \"%s\"" % text
+    s.close()
+
+    print "Testcase 2.2: Test UnixDomainSocketServer with a datagram socket..."
+    s = socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM)
+    time.sleep(2)   # wait for the server
+    s.connect(socket_file)
+    text = "Hello I'm the client..."
+    s.send(text)
+    print "Text sent: \"%s\"" % text
+    s.close()
+
+
+if __name__ == "__main__":
+    main()