junixsocket 2.1.0

* junisocket 2.1.0 - Support for Java 8, 9, 10 and 11 - Building junixsocket requires Java 9 or later - Jigsaw module support - New Native library loading mechanism - Validate that socket exists before trying to connect - Replaced AFUNIXSocketException with SocketException - Throw InterruptedIOException upon interrupt during write - Properly discard reference to file descriptor upon close - Add system property to override the default directory for RMI sockets - Properly handle timeout during ServerSocket#accept - Additional range checks for array offsets - Script to run the demos from the command-line - Documentation updates - Updated Maven dependencies - Code cleanup and other bug fixes
tarun-synacor · Dec 27, 2018 · a096207 · a096207
1 parent 4fc476b
commit a096207
Show file tree

Hide file tree

Showing 110 changed files with 3,439 additions and 1,204 deletions.
diff --git a/.gitignore b/.gitignore
@@ -2,10 +2,11 @@
 .settings
 .classpath
 target
+target-eclipse
 .DS_Store
 dependency-reduced-pom.xml
 *~
 *~~
 pom.xml.releaseBackup
 /release.properties
-/eclipse
+/coding-style
diff --git a/LICENSE b/LICENSE
@@ -1,10 +1,10 @@
 junixsocket
 
-Copyright (c) 2009,2014 Christian Kohlschütter
+Copyright 2009-2018 Christian Kohlschütter
 
-The author licenses this file to You under the Apache License, Version 2.0
-(the "License"); you may not use this file except in compliance with
-the License.  You may obtain a copy of the License at
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
 
     http://www.apache.org/licenses/LICENSE-2.0
 

diff --git a/NOTICE b/NOTICE
@@ -1,8 +1,5 @@
 junixsocket
-
 Unix Domain Sockets for Java + RMI-over-AF_UNIX. 
 
-Copyright (c) 2009,2014 Dr. Christian Kohlschütter
-
-See http://code.google.com/p/junixsocket/ for further information.
-
+Copyright (c) 2009-2018 Dr. Christian Kohlschütter
+See https://github.com/kohlschutter/junixsocket for more information.
diff --git a/README.md b/README.md
@@ -4,50 +4,38 @@ junixsocket is a Java/JNI library that allows the use of [Unix Domain Sockets](h
 
 ## Why it's cool
 
-* In contrast to other implementations, *junixsocket* extends the Java Sockets API (`java.net.Socket, java.net.SocketAddress`, etc.)
-* Supports *RMI over AF_UNIX*
+* In contrast to other implementations, *junixsocket* extends the Java Sockets API (`java.net.Socket`, `java.net.SocketAddress`, etc.)
+* Supports *RMI over AF_UNIX*.
 * Can connect to local MySQL server via Unix domain sockets (provides a *AFUNIXDatabaseSocketFactory* for Connector/J).
+* Supports Java 8, 9, 10, 11.
+* Comes with pre-built native libraries for macOS and Linux; custom libraries can be built using Maven.
+* Supports Jigsaw modules.
 * Apache 2.0 licensed.
 
 ## Licensing
 
-junixsocket has been written by Christian Kohlschütter. It is released under the Apache 2.0 License.
+junixsocket is released under the Apache 2.0 License.
 
-Commercial support is available through [http://www.kohlschutter.com/ Kohlschütter Search Intelligence].
+Commercial support is available through [Kohlschütter Search Intelligence](http://www.kohlschutter.com/).
 
-## Changelog
+## Quick links
 
-### Noteworthy changes
+ * [Project website](https://kohlschutter.github.io/junixsocket/)
+ * [Changelog](https://kohlschutter.github.io/junixsocket/changelog.html)
+ * [Getting started](https://kohlschutter.github.io/junixsocket/quickstart.html)
+ * [Demo code:](https://kohlschutter.github.io/junixsocket/junixsocket-demo/xref/index.html)
+    - Sockets (`org.newsclub.net.unix.demo`)
+    - RMI over Unix Sockets (`org.newsclub.net.unix.demo.rmi` and `org.newsclub.net.unix.demo.rmi.services`)
+    - MySQL over Unix Sockets  (`org.newsclub.net.mysql.demo`)
+  * API Javadocs
+    - [The core (common) API](https://kohlschutter.github.io/junixsocket/junixsocket-common/apidocs/org.newsclub.net.unix/org/newsclub/net/unix/package-summary.html)
+    - [The RMI-over-Unix-Socket API](https://kohlschutter.github.io/junixsocket/junixsocket-rmi/apidocs/org.newsclub.net.unix.rmi/org/newsclub/net/unix/rmi/package-summary.html)
 
-  * _(2014-09-29)_ *junixsocket 2.0.1*
+## Feature Comparison Matrix
 
-   * **Bugfix:** Added byte array bounds checking to read/write methods.
-   * Fix C compiler warnings
-   * Remove synchronized byte[] array for single-byte reads/writes.
-
-  * _(2014-09-28)_ *junixsocket 2.0.0*
-   * Moved from *Google Code* to *GitHub*.
-   * Now uses Maven as the build system, code is distributed to the *Maven Central* repository.
-   * C code is built using *nar-maven-plugin*
-   * JNI libraries are loaded using *native-lib-loader*
-
-See the commit log for details.
-
-For 1.x releases, please see [https://code.google.com/p/junixsocket](https://code.google.com/p/junixsocket).
-
-## Documentation
-
-For now, please refer to the [Wiki on Google Code](http://code.google.com/p/junixsocket/w/list). 
-
-Quick links:
- * [Getting Started](http://code.google.com/p/junixsocket/wiki/GettingStarted)
- * [Socket Demo](http://code.google.com/p/junixsocket/source/browse/#svn/trunk/junixsocket/src/demo/org/newsclub/net/unix/demo)
- * [RMI Demo](http://code.google.com/p/junixsocket/source/browse/#svn/trunk/junixsocket/src/demo/org/newsclub/net/unix/demo/rmi)
- * [MySQL Socket Demo](http://code.google.com/p/junixsocket/wiki/ConnectingToMySQL)
- * [API Javadocs](http://junixsocket.googlecode.com/svn/trunk/junixsocket/javadoc/index.html)
-
-## Related Work
-
- * [JUDS](http://code.google.com/p/juds/) (LGPL, no RMI, not using Java Sockets API)
- * J-BUDS (LGPL, no RMI, not using Java Sockets API, orphaned)
- * gnu.net.local (GPL with Classpath exception, no RMI, not using Java Sockets API, orphaned) -- [Archive mirror](http://web.archive.org/web/20060702213439/http://www.nfrese.net/software/gnu_net_local/overview.html).
+| Project  | License | Java Sockets API | Supports RMI | Comments |
+| ------------- | --------- | ------------- | ------------- | ------------- |
+| junixsocket | Apache 2.0 | ✅ Yes | ✅ Yes | This project |
+| [JUDS](http://code.google.com/p/juds/)  | LGPL | ❌ No | ❌ No | |
+| J-BUDS  | LGPL | ❌ No | ❌ No | orphaned |
+| [gnu.net.local](http://web.archive.org/web/20060702213439/http://www.nfrese.net/software/gnu_net_local/overview.html) | GPL with Classpath exception | ❌ No | ❌ No | orphaned |
diff --git a/junixsocket-common/.gitignore b/junixsocket-common/.gitignore
@@ -0,0 +1 @@
+/target-eclipse/
diff --git a/junixsocket-common/pom.xml b/junixsocket-common/pom.xml
@@ -1,18 +1,24 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
   <modelVersion>4.0.0</modelVersion>
   <artifactId>junixsocket-common</artifactId>
   <packaging>jar</packaging>
   <parent>
     <groupId>com.kohlschutter.junixsocket</groupId>
     <artifactId>junixsocket-parent</artifactId>
-    <version>2.0.5-SNAPSHOT</version>
+    <version>2.1.0</version>
     <relativePath>../pom.xml</relativePath>
   </parent>
   <name>junixsocket-common</name>
   <properties>
     <kohlschutter.project.base.directory>${project.parent.basedir}</kohlschutter.project.base.directory>
+    <junixsocket.custom.arch></junixsocket.custom.arch>
   </properties>
+
+  <description>The public, core API</description>
+
   <build>
     <plugins>
       <plugin>
@@ -35,5 +41,19 @@
     </plugins>
   </build>
   <dependencies>
+    <dependency>
+      <groupId>com.kohlschutter.junixsocket</groupId>
+      <artifactId>junixsocket-native-common</artifactId>
+      <version>${project.version}</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>com.kohlschutter.junixsocket</groupId>
+      <artifactId>junixsocket-native-custom</artifactId>
+      <version>${project.version}</version>
+      <scope>test</scope>
+      <classifier>${junixsocket.custom.arch}</classifier>
+      <optional>true</optional>
+    </dependency>
   </dependencies>
 </project>
diff --git a/junixsocket-common/src/main/java/module-info.java b/junixsocket-common/src/main/java/module-info.java
@@ -0,0 +1,4 @@
+module org.newsclub.net.unix {
+  exports org.newsclub.net.unix;
+  requires java.base;
+}
diff --git a/junixsocket-common/src/main/java/org/newsclub/net/unix/AFUNIXServerSocket.java b/junixsocket-common/src/main/java/org/newsclub/net/unix/AFUNIXServerSocket.java
@@ -1,11 +1,11 @@
 /**
  * junixsocket
  *
- * Copyright (c) 2009,2014 Christian Kohlschütter
+ * Copyright 2009-2018 Christian Kohlschütter
  *
- * The author licenses this file to You under the Apache License, Version 2.0
- * (the "License"); you may not use this file except in compliance with
- * the License.  You may obtain a copy of the License at
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
@@ -45,6 +45,11 @@ public void run() {
     }
   };
 
+  /**
+   * Constructs a new, unconnected instance.
+   * 
+   * @throws IOException if the operation fails.
+   */
   protected AFUNIXServerSocket() throws IOException {
     super();
     this.implementation = new AFUNIXSocketImpl();
@@ -58,6 +63,7 @@ protected AFUNIXServerSocket() throws IOException {
    * Returns a new, unbound AF_UNIX {@link ServerSocket}.
    * 
    * @return The new, unbound {@link AFUNIXServerSocket}.
+   * @throws IOException if the operation fails.
    */
   public static AFUNIXServerSocket newInstance() throws IOException {
     AFUNIXServerSocket instance = new AFUNIXServerSocket();
@@ -68,7 +74,9 @@ public static AFUNIXServerSocket newInstance() throws IOException {
    * Returns a new AF_UNIX {@link ServerSocket} that is bound to the given
    * {@link AFUNIXSocketAddress}.
    * 
+   * @param addr The socket file to bind to.
    * @return The new, unbound {@link AFUNIXServerSocket}.
+   * @throws IOException if the operation fails.
    */
   public static AFUNIXServerSocket bindOn(final AFUNIXSocketAddress addr) throws IOException {
     AFUNIXServerSocket socket = newInstance();
@@ -85,8 +93,8 @@ public void bind(SocketAddress endpoint, int backlog) throws IOException {
       throw new SocketException("Already bound");
     }
     if (!(endpoint instanceof AFUNIXSocketAddress)) {
-      throw new IOException("Can only bind to endpoints of type "
-          + AFUNIXSocketAddress.class.getName());
+      throw new IOException("Can only bind to endpoints of type " + AFUNIXSocketAddress.class
+          .getName());
     }
     implementation.bind(backlog, endpoint);
     boundEndpoint = (AFUNIXSocketAddress) endpoint;
@@ -135,6 +143,11 @@ public void close() throws IOException {
     }
   }
 
+  /**
+   * Checks whether everything is setup to support AF_UNIX sockets.
+   * 
+   * @return {@code true} if supported.
+   */
   public static boolean isSupported() {
     return NativeUnixSocket.isLoaded();
   }

diff --git a/junixsocket-common/src/main/java/org/newsclub/net/unix/AFUNIXSocket.java b/junixsocket-common/src/main/java/org/newsclub/net/unix/AFUNIXSocket.java
@@ -1,11 +1,11 @@
 /**
  * junixsocket
  *
- * Copyright (c) 2009,2014 Christian Kohlschütter
+ * Copyright 2009-2018 Christian Kohlschütter
  *
- * The author licenses this file to You under the Apache License, Version 2.0
- * (the "License"); you may not use this file except in compliance with
- * the License.  You may obtain a copy of the License at
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
@@ -27,6 +27,7 @@
  * @author Christian Kohlschütter
  */
 public class AFUNIXSocket extends Socket {
+  private static final String PROP_LIBRARY_LOADED = "org.newsclub.net.unix.library.loaded";
   protected AFUNIXSocketImpl impl;
   AFUNIXSocketAddress addr;
 
@@ -48,6 +49,7 @@ private AFUNIXSocket(final AFUNIXSocketImpl impl) throws IOException {
    * {@link Socket#setTcpNoDelay(boolean)}.
    * 
    * @return A new, unbound socket.
+   * @throws IOException if the operation fails.
    */
   public static AFUNIXSocket newInstance() throws IOException {
     final AFUNIXSocketImpl impl = new AFUNIXSocketImpl.Lenient();
@@ -63,6 +65,7 @@ public static AFUNIXSocket newInstance() throws IOException {
    * {@link #newInstance()}, at least for some cases.
    * 
    * @return A new, unbound socket.
+   * @throws IOException if the operation fails.
    */
   public static AFUNIXSocket newStrictInstance() throws IOException {
     final AFUNIXSocketImpl impl = new AFUNIXSocketImpl();
@@ -76,6 +79,7 @@ public static AFUNIXSocket newStrictInstance() throws IOException {
    * 
    * @param addr The address to connect to.
    * @return A new, connected socket.
+   * @throws IOException if the operation fails.
    */
   public static AFUNIXSocket connectTo(AFUNIXSocketAddress addr) throws IOException {
     AFUNIXSocket socket = newInstance();
@@ -101,8 +105,8 @@ public void connect(SocketAddress endpoint) throws IOException {
   @Override
   public void connect(SocketAddress endpoint, int timeout) throws IOException {
     if (!(endpoint instanceof AFUNIXSocketAddress)) {
-      throw new IOException("Can only connect to endpoints of type "
-          + AFUNIXSocketAddress.class.getName());
+      throw new IOException("Can only connect to endpoints of type " + AFUNIXSocketAddress.class
+          .getName());
     }
     impl.connect(endpoint, timeout);
     this.addr = (AFUNIXSocketAddress) endpoint;
@@ -128,4 +132,16 @@ public String toString() {
   public static boolean isSupported() {
     return NativeUnixSocket.isLoaded();
   }
+
+  /**
+   * Returns an identifier of the loaded native library, or {@code null} if the library hasn't been
+   * loaded yet.
+   * 
+   * The identifier is useful mainly for debugging purposes.
+   * 
+   * @return The identifier of the loaded junixsocket-native library, or {@code null}.
+   */
+  public static String getLoadedLibrary() {
+    return System.getProperty(PROP_LIBRARY_LOADED);
+  }
 }
diff --git a/junixsocket-common/src/main/java/org/newsclub/net/unix/AFUNIXSocketAddress.java b/junixsocket-common/src/main/java/org/newsclub/net/unix/AFUNIXSocketAddress.java
@@ -1,11 +1,11 @@
 /**
  * junixsocket
  *
- * Copyright (c) 2009,2014 Christian Kohlschütter
+ * Copyright 2009-2018 Christian Kohlschütter
  *
- * The author licenses this file to You under the Apache License, Version 2.0
- * (the "License"); you may not use this file except in compliance with
- * the License.  You may obtain a copy of the License at
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
@@ -39,6 +39,7 @@ public class AFUNIXSocketAddress extends InetSocketAddress {
    * given file.
    * 
    * @param socketFile The socket to connect to.
+   * @throws IOException if the operation fails.
    */
   public AFUNIXSocketAddress(final File socketFile) throws IOException {
     this(socketFile, 0);
@@ -50,6 +51,7 @@ public AFUNIXSocketAddress(final File socketFile) throws IOException {
    * 
    * @param socketFile The socket to connect to.
    * @param port The port associated with this socket, or {@code 0} when no port should be assigned.
+   * @throws IOException if the operation fails.
    */
   public AFUNIXSocketAddress(final File socketFile, int port) throws IOException {
     super(0);