add a bunch of documentation

also close down some implementation classes that are not meant for extension at the moment.

closes #35

Author: pschichtel

core/src/main/java/tel/schich/javacan/IsotpCanChannelImpl.java

@@ -30,7 +30,7 @@
 import tel.schich.javacan.platform.linux.LinuxNativeOperationException;
 import tel.schich.javacan.platform.linux.LinuxNetworkDevice;
 
-class IsotpCanChannelImpl extends IsotpCanChannel {
+final class IsotpCanChannelImpl extends IsotpCanChannel {
 
     private NetworkDevice device;
     private IsotpSocketAddress rx;

core/src/main/java/tel/schich/javacan/RawCanChannelImpl.java

@@ -32,7 +32,7 @@
 /**
  * Naming has been adopted from the JDK here (Interface + InterfaceImpl)
  */
-public class RawCanChannelImpl extends RawCanChannel {
+final class RawCanChannelImpl extends RawCanChannel {
 
     private volatile NetworkDevice device;
 

epoll/src/main/java/tel/schich/javacan/platform/linux/epoll/EPoll.java

@@ -25,6 +25,9 @@
 import tel.schich.javacan.platform.Platform;
 import tel.schich.javacan.platform.linux.LinuxNativeOperationException;
 
+/**
+ * This class specifies all supported native operations on the epoll subsystem.
+ */
 class EPoll {
 
     private static final String LIB_NAME = "javacan-epoll";

epoll/src/main/java/tel/schich/javacan/platform/linux/epoll/EPollException.java

@@ -25,6 +25,9 @@
 import tel.schich.javacan.platform.linux.LinuxNativeOperationException;
 import tel.schich.jniaccess.JNIAccess;
 
+/**
+ * Signals a low-level error specific to the epoll subsystem.
+ */
 public class EPollException extends LinuxNativeOperationException {
     @JNIAccess
     public EPollException(String message, int errorNumber, String errorString) {

epoll/src/main/java/tel/schich/javacan/platform/linux/epoll/EPollRegistration.java

@@ -31,10 +31,10 @@
 import java.util.Set;
 
 /**
- * This class implements the {@link java.nio.channels.SelectionKey} API necessary for
- * {@link java.nio.channels.Selector}s.
+ * This class implements the {@link SelectorRegistration} API necessary for
+ * {@link tel.schich.javacan.select.IOSelector}s.
  */
-public class EPollRegistration<ChannelType extends Channel> implements SelectorRegistration<UnixFileDescriptor, ChannelType> {
+final public class EPollRegistration<ChannelType extends Channel> implements SelectorRegistration<UnixFileDescriptor, ChannelType> {
 
     private final EPollSelector selector;
     private final ChannelType channel;

epoll/src/main/java/tel/schich/javacan/platform/linux/epoll/EPollSelector.java

@@ -40,19 +40,15 @@
 import static java.util.Collections.newSetFromMap;
 
 /**
- * This is an implementation of the {@link java.nio.channels.Selector} API relying on Linux' epoll API to poll for
- * IO events from an arbitrary amount of file descriptors. The implementation is based
- * on {@link java.nio.channels.spi.AbstractSelector} and is inspired by Java's own epoll-based Selector implementation.
- * <p>
- * This reimplementation is sadly necessary, because the original implementation does not allow custom
- * {@link java.nio.channels.Channel} implementations as Java's selector is requires the channels to implement non-public
- * interface to expose the underlying file descriptor.
- * <p>
+ * This is an implementation of the {@link IOSelector} API relying on Linux' epoll API to poll for
+ * IO events from an arbitrary amount of file descriptors. The implementation is inspired by Java's
+ * own epoll-based {@link java.nio.channels.Selector} implementation.
+ *
  * This implementation does not expose any more public APIs.
  *
  * @see <a href="https://man7.org/linux/man-pages/man7/epoll.7.html">epoll man page</a>
  */
-public class EPollSelector implements IOSelector<UnixFileDescriptor> {
+final public class EPollSelector implements IOSelector<UnixFileDescriptor> {
 
     static {
         EPoll.initialize();
@@ -120,7 +116,8 @@ private void ensureOpen() {
             throw new ClosedSelectorException();
     }
 
-    public <ChannelType extends Channel> SelectorRegistration<UnixFileDescriptor, ChannelType> updateRegistration(SelectorRegistration<UnixFileDescriptor, ChannelType> key, Set<SelectorRegistration.Operation> newOps) throws IOException {
+    public <ChannelType extends Channel> EPollRegistration<ChannelType> updateRegistration(SelectorRegistration<UnixFileDescriptor, ChannelType> key, Set<SelectorRegistration.Operation> newOps) throws IOException {
+        ensureOpen();
         if (key.getSelector() != this) {
             throw new IllegalArgumentException("Key is not registered here!");
         }
@@ -147,7 +144,7 @@ public <ChannelType extends Channel> SelectorRegistration<UnixFileDescriptor, Ch
         }
     }
 
-    public <ChannelType extends Channel> SelectorRegistration<UnixFileDescriptor, ChannelType> register(ChannelType ch, Set<SelectorRegistration.Operation> ops) throws ClosedChannelException {
+    public <ChannelType extends Channel> EPollRegistration<ChannelType> register(ChannelType ch, Set<SelectorRegistration.Operation> ops) throws IOException {
         ensureOpen();
         if (!ch.isOpen()) {
             throw new ClosedChannelException();
@@ -162,11 +159,7 @@ public <ChannelType extends Channel> SelectorRegistration<UnixFileDescriptor, Ch
         final UnixFileDescriptor handle = (UnixFileDescriptor) nativeHandle;
         int fd = handle.getValue();
 
-        try {
-            EPoll.addFileDescriptor(epollfd, fd, translateInterestsToEPoll(ops));
-        } catch (LinuxNativeOperationException ex) {
-            throw new RuntimeException(ex);
-        }
+        EPoll.addFileDescriptor(epollfd, fd, translateInterestsToEPoll(ops));
 
         EPollRegistration<ChannelType> key = new EPollRegistration<>(this, ch, handle, ops);
         synchronized (keyCollectionsLock) {
@@ -208,6 +201,7 @@ private static Set<SelectorRegistration.Operation> translateInterestsFromEPoll(i
     }
 
     public <ChannelType extends Channel> boolean cancel(SelectorRegistration<UnixFileDescriptor, ChannelType> registration) throws IOException {
+        ensureOpen();
         if (registration.getSelector() != this) {
             return false;
         }

epoll/src/main/java/tel/schich/javacan/select/IOEvent.java

@@ -25,7 +25,14 @@
 import java.util.Objects;
 import java.util.Set;
 
-public class IOEvent<HandleType> {
+/**
+ * This class represents an IO event that happened on a selected channel, which is a tuple consisting
+ * of the {@link SelectorRegistration} and a set of {@link tel.schich.javacan.select.SelectorRegistration.Operation}s
+ * that can be performed now.
+ *
+ * @param <HandleType> The type of the resource handle
+ */
+final public class IOEvent<HandleType> {
     private final SelectorRegistration<HandleType, ?> registration;
     private final Set<SelectorRegistration.Operation> operations;
 
@@ -34,10 +41,21 @@ public IOEvent(SelectorRegistration<HandleType, ?> registration, Set<SelectorReg
         this.operations = operations;
     }
 
+    /**
+     * The registration this event belongs to.
+     * The channel type is not statically known at this point.
+     *
+     * @return the registration
+     */
     public SelectorRegistration<HandleType, ?> getRegistration() {
         return registration;
     }
 
+    /**
+     * The operations that can be performed now.
+     *
+     * @return a set of operations
+     */
     public Set<SelectorRegistration.Operation> getOperations() {
         return operations;
     }

epoll/src/main/java/tel/schich/javacan/select/IOSelector.java

@@ -31,21 +31,116 @@
 import java.util.List;
 import java.util.Set;
 
+/**
+ * This interface is an improved version of {@link java.nio.channels.Selector} that is able to support SocketCAN sockets together with EPoll.
+ * It also tries to model differences between platforms more closely by parameterizing the type of the resource handle.
+ *
+ * The JDK's {@link java.nio.channels.Selector} interface as a bunch of assumptions about the channel types it supports that make it impossible
+ * to correctly use epoll. JavaCAN 2.x attempted to extend the existing JDK interfaces to cover the SocketCAN channel types, however certain
+ * issues were not possible to fix as the JDK interfaces are too restrictive in their extension points, especially around registration and
+ * cancellation.
+ *
+ * @param <HandleType> The type of the resource handle
+ *
+ * @see java.nio.channels.Selector
+ */
 public interface IOSelector<HandleType> extends AutoCloseable {
     boolean isOpen();
 
-    default <ChannelType extends Channel> SelectorRegistration<HandleType, ChannelType> register(ChannelType ch, SelectorRegistration.Operation... ops) throws ClosedChannelException {
+    /**
+     * Registers a channel to this selector and returns a registration.
+     *
+     * @param ch the channel to register
+     * @param ops the operations to register for
+     * @param <ChannelType> the type of the channel
+     * @return the registration
+     * @throws ClosedChannelException if the channel is already closed
+     * @throws IOException if any low level IO operation failed
+     */
+    default <ChannelType extends Channel> SelectorRegistration<HandleType, ChannelType> register(ChannelType ch, SelectorRegistration.Operation... ops) throws IOException {
         return register(ch, EnumSet.copyOf(Arrays.asList(ops)));
     }
 
-    <ChannelType extends Channel> SelectorRegistration<HandleType, ChannelType> register(ChannelType ch, Set<SelectorRegistration.Operation> ops) throws ClosedChannelException;
+    /**
+     * Registers a channel to this selector and returns a registration.
+     *
+     * @param ch the channel to register
+     * @param ops the operations to register for
+     * @param <ChannelType> the type of the channel
+     * @return the registration
+     * @throws ClosedChannelException if the channel is already closed
+     * @throws IOException if any low level IO operation failed
+     */
+    <ChannelType extends Channel> SelectorRegistration<HandleType, ChannelType> register(ChannelType ch, Set<SelectorRegistration.Operation> ops) throws IOException;
+
+    /**
+     * Cancels a given registration.
+     *
+     * @param registration the registration to cancel
+     * @param <ChannelType> the type of the channel
+     * @return true if the cancellation was successful
+     * @throws ClosedChannelException if the channel is already closed
+     * @throws IOException if any low level IO operation failed
+     */
     <ChannelType extends Channel> boolean cancel(SelectorRegistration<HandleType, ChannelType> registration) throws IOException;
+
+    /**
+     * Updates a registration's interested operations.
+     *
+     * The returned registration is a copy of the given registration with the interested ops updated, however the old
+     * registration instance remains valid and can equally be used to perform selector operations.
+     *
+     * @param registration the registration to update
+     * @param ops the new operations
+     * @param <ChannelType> the type of the channel
+     * @return the updated registration
+     * @throws ClosedChannelException if the channel is already closed
+     * @throws IOException if any low level IO operation failed
+     */
     <ChannelType extends Channel> SelectorRegistration<HandleType, ChannelType> updateRegistration(SelectorRegistration<HandleType, ChannelType> registration, Set<SelectorRegistration.Operation> ops) throws IOException;
 
+    /**
+     * This operation selects IO events on this selector possibly blocking indefinitely until events happen.
+     * Depending on the implementation this operation may still return without any events, especially when
+     * {@link #wakeup()} is used.
+     *
+     * @return the events that occurred on channels registered to this selector since the last selection.
+     * @throws IOException if any low level IO operation failed
+     */
     List<IOEvent<HandleType>> select() throws IOException;
+
+    /**
+     * This operation selects IO events on this selector possibly blocking for the given {@link Duration} until events happen.
+     * Depending on the implementation this operation may still return earlier without any events, especially when
+     * {@link #wakeup()} is used.
+     *
+     * @param timeout the maximum time to wait for events
+     * @return the events that occurred on channels registered to this selector since the last selection.
+     * @throws IOException if any low level IO operation failed
+     */
     List<IOEvent<HandleType>> select(Duration timeout) throws IOException;
+
+    /**
+     * This operation selects IO events on this selector without blocking when no events exist.
+     *
+     * @return the events that occurred on channels registered to this selector since the last selection.
+     * @throws IOException if any low level IO operation failed
+     */
     List<IOEvent<HandleType>> selectNow() throws IOException;
+
+    /**
+     * This operation wakes up any blocking {@link #select()} or {@link #select(Duration)} calls, without actually having
+     * any IO events.
+     *
+     * @throws IOException if any low level IO operation failed
+     */
     void wakeup() throws IOException;
 
+
+    /**
+     * This operation closes the selector and frees all resources related to it.
+     *
+     * @throws IOException if any low level IO operation failed
+     */
     void close() throws IOException;
 }

epoll/src/main/java/tel/schich/javacan/select/SelectorRegistration.java

@@ -25,13 +25,61 @@
 import java.nio.channels.Channel;
 import java.util.Set;
 
+/**
+ * This interfaces describes a registration of a certain {@link Channel} to a certain {@link IOSelector}.
+ *
+ * @param <HandleType> The type of the resource handle
+ * @param <ChannelType> The type pf the channel
+ */
 public interface SelectorRegistration<HandleType, ChannelType extends Channel> extends AutoCloseable {
+    /**
+     * The handle of the resources being selected.
+     *
+     * @return the handle
+     */
     HandleType getHandle();
+
+    /**
+     * The selector that issued this registration.
+     *
+     * @return the selector
+     */
     IOSelector<HandleType> getSelector();
+
+    /**
+     * The channel that was registered,
+     *
+     * @return the channel
+     */
     ChannelType getChannel();
+
+    /**
+     * The operations this registration is interested in.
+     * This value might not reflect updates of the registration at a later point in time!
+     *
+     * @return the set of operations this registration is interested in
+     */
     Set<Operation> getOperations();
 
+    /**
+     * A channel operation that can be selected on.
+     */
     enum Operation {
-        READ, WRITE, ACCEPT, CONNECT
+        /**
+         * The channel can be read.
+         */
+        READ,
+        /**
+         * The channel can be written.
+         */
+        WRITE,
+        /**
+         * The channel can accept a connection.
+         */
+        ACCEPT,
+        /**
+         * The channel can connect.
+         */
+        CONNECT
     }
 }

epoll/src/main/java/tel/schich/javacan/util/EventLoop.java

@@ -40,6 +40,13 @@
 import java.util.Set;
 import java.util.concurrent.ThreadFactory;
 
+/**
+ * This is a simple single-threaded event loop implementation.
+ * It supports registering several channels of the same type.
+ *
+ * @param <HandleType>  the type of handles that are supported by the underlying {@link IOSelector}
+ * @param <ChannelType> the type of channels that can be registered
+ */
 public abstract class EventLoop<HandleType, ChannelType extends Channel> implements Closeable {
     private static final Logger LOGGER = LoggerFactory.getLogger(CanBroker.class);
 
@@ -86,7 +93,7 @@ public Duration getTimeout() {
      * @param ops the interested ops
      * @throws ClosedChannelException if the channel is already closed
      */
-    protected final void register(ChannelType ch, Set<SelectorRegistration.Operation> ops) throws ClosedChannelException {
+    protected final void register(ChannelType ch, Set<SelectorRegistration.Operation> ops) throws IOException {
         registrations.put(ch, selector.register(ch, ops));
     }