Module org.newsclub.net.unix
Package org.newsclub.net.unix

Class AFUNIXSocket

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable
    public final class AFUNIXSocket
extends java.net.Socket
    Implementation of an AF_UNIX domain socket.
    Author:
    Christian Kohlschütter

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addCloseable​(java.io.Closeable closeable)
      Registers a Closeable that should be closed when this socket is closed.
      void bind​(java.net.SocketAddress bindpoint)
      Binds this AFUNIXSocket to the given bindpoint.
      void clearReceivedFileDescriptors()
      Clears the queue of incoming FileDescriptors that were sent as ancillary messages.
      void close()  
      void connect​(java.net.SocketAddress endpoint)  
      void connect​(java.net.SocketAddress endpoint, int timeout)  
      static AFUNIXSocket connectTo​(AFUNIXSocketAddress addr)
      Creates a new AFUNIXSocket and connects it to the given AFUNIXSocketAddress.
      void ensureAncillaryReceiveBufferSize​(int minSize)
      Ensures a minimum ancillary receive buffer size.
      int getAncillaryReceiveBufferSize()
      Returns the size of the receive buffer for ancillary messages (in bytes).
      static java.lang.String getLoadedLibrary()
      Returns an identifier of the loaded native library, or null if the library hasn't been loaded yet.
      AFUNIXSocketCredentials getPeerCredentials()
      Retrieves the "peer credentials" for this connection.
      java.io.FileDescriptor[] getReceivedFileDescriptors()
      Retrieves an array of incoming FileDescriptors that were sent as ancillary messages, along with a call to InputStream.read(), etc.
      static java.lang.String getVersion()
      Returns the version of the junixsocket library, as a string, for debugging purposes.
      boolean isClosed()  
      static boolean isSupported()
      Returns true iff AFUNIXSockets are supported by the current Java VM.
      static void main​(java.lang.String[] args)
      Very basic self-test function.
      static AFUNIXSocket newInstance()
      Creates a new, unbound AFUNIXSocket.
      static AFUNIXSocket newStrictInstance()
      Creates a new, unbound, "strict" AFUNIXSocket.
      void removeCloseable​(java.io.Closeable closeable)
      Unregisters a previously registered Closeable.
      void setAncillaryReceiveBufferSize​(int size)
      Sets the size of the receive buffer for ancillary messages (in bytes).
      void setOutboundFileDescriptors​(java.io.FileDescriptor... fdescs)
      Sets a list of FileDescriptors that should be sent as an ancillary message along with the next write.
      static boolean supports​(AFUNIXSocketCapability capability)
      Checks if the current environment (system platform, native library, etc.) supports a given junixsocket capability.
      java.lang.String toString()  

      • Methods inherited from class java.net.Socket

        getChannel, getInetAddress, getInputStream, getKeepAlive, getLocalAddress, getLocalPort, getLocalSocketAddress, getOOBInline, getOption, getOutputStream, getPort, getReceiveBufferSize, getRemoteSocketAddress, getReuseAddress, getSendBufferSize, getSoLinger, getSoTimeout, getTcpNoDelay, getTrafficClass, isBound, isConnected, isInputShutdown, isOutputShutdown, sendUrgentData, setKeepAlive, setOOBInline, setOption, setPerformancePreferences, setReceiveBufferSize, setReuseAddress, setSendBufferSize, setSocketImplFactory, setSoLinger, setSoTimeout, setTcpNoDelay, setTrafficClass, shutdownInput, shutdownOutput, supportedOptions

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Method Detail

      • newInstance

        public static AFUNIXSocket newInstance()
                                throws java.io.IOException
        Creates a new, unbound AFUNIXSocket. This "default" implementation is a bit "lenient" with respect to the specification. In particular, we ignore calls to Socket.getTcpNoDelay() and Socket.setTcpNoDelay(boolean).
        Returns:
        A new, unbound socket.
        Throws:
        java.io.IOException - if the operation fails.

      • newStrictInstance

        public static AFUNIXSocket newStrictInstance()
                                      throws java.io.IOException
        Creates a new, unbound, "strict" AFUNIXSocket. This call uses an implementation that tries to be closer to the specification than newInstance(), at least for some cases.
        Returns:
        A new, unbound socket.
        Throws:
        java.io.IOException - if the operation fails.

      • connectTo

        public static AFUNIXSocket connectTo​(AFUNIXSocketAddress addr)
                              throws java.io.IOException
        Creates a new AFUNIXSocket and connects it to the given AFUNIXSocketAddress.
        Parameters:
        addr - The address to connect to.
        Returns:
        A new, connected socket.
        Throws:
        java.io.IOException - if the operation fails.

      • bind

        public void bind​(java.net.SocketAddress bindpoint)
          throws java.io.IOException
        Binds this AFUNIXSocket to the given bindpoint. Only bindpoints of the type AFUNIXSocketAddress are supported.
        Overrides:
        bind in class java.net.Socket
        Throws:
        java.io.IOException

      • connect

        public void connect​(java.net.SocketAddress endpoint)
             throws java.io.IOException
        Overrides:
        connect in class java.net.Socket
        Throws:
        java.io.IOException

      • connect

        public void connect​(java.net.SocketAddress endpoint,
                    int timeout)
             throws java.io.IOException
        Overrides:
        connect in class java.net.Socket
        Throws:
        java.io.IOException

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.net.Socket

      • isSupported

        public static boolean isSupported()
        Returns true iff AFUNIXSockets are supported by the current Java VM. To support AFUNIXSockets, a custom JNI library must be loaded that is supplied with junixsocket.
        Returns:
        true iff supported.

      • getVersion

        public static java.lang.String getVersion()
        Returns the version of the junixsocket library, as a string, for debugging purposes. NOTE: Do not rely on the format of the version identifier, use socket capabilities instead.
        Returns:
        String The version identfier, or null if it could not be determined.
        See Also:
        supports(AFUNIXSocketCapability)

      • getLoadedLibrary

        public static java.lang.String getLoadedLibrary()
        Returns an identifier of the loaded native library, or null if the library hasn't been loaded yet. The identifier is useful mainly for debugging purposes.
        Returns:
        The identifier of the loaded junixsocket-native library, or null.

      • getPeerCredentials

        public AFUNIXSocketCredentials getPeerCredentials()
                                           throws java.io.IOException
        Retrieves the "peer credentials" for this connection. These credentials may be useful to authenticate the other end of the socket (client or server).
        Returns:
        The peer's credentials.
        Throws:
        java.io.IOException - If there was an error returning these credentials.

      • isClosed

        public boolean isClosed()
        Overrides:
        isClosed in class java.net.Socket

      • getAncillaryReceiveBufferSize

        public int getAncillaryReceiveBufferSize()
        Returns the size of the receive buffer for ancillary messages (in bytes).
        Returns:
        The size.

      • setAncillaryReceiveBufferSize

        public void setAncillaryReceiveBufferSize​(int size)
        Sets the size of the receive buffer for ancillary messages (in bytes). To disable handling ancillary messages, set it to 0 (default).
        Parameters:
        size - The size.

      • ensureAncillaryReceiveBufferSize

        public void ensureAncillaryReceiveBufferSize​(int minSize)
        Ensures a minimum ancillary receive buffer size.
        Parameters:
        minSize - The minimum size (in bytes).

      • getReceivedFileDescriptors

        public java.io.FileDescriptor[] getReceivedFileDescriptors()
                                                    throws java.io.IOException
        Retrieves an array of incoming FileDescriptors that were sent as ancillary messages, along with a call to InputStream.read(), etc. NOTE: Another call to this method will not return the same file descriptors again (most likely, null will be returned).
        Returns:
        The file descriptors, or null if none were available.
        Throws:
        java.io.IOException - if the operation fails.

      • clearReceivedFileDescriptors

        public void clearReceivedFileDescriptors()
        Clears the queue of incoming FileDescriptors that were sent as ancillary messages.

      • setOutboundFileDescriptors

        public void setOutboundFileDescriptors​(java.io.FileDescriptor... fdescs)
                                throws java.io.IOException
        Sets a list of FileDescriptors that should be sent as an ancillary message along with the next write. NOTE: There can only be one set of file descriptors active until the write completes.
        Parameters:
        fdescs - The file descriptors, or null if none.
        Throws:
        java.io.IOException - if the operation fails.

      • supports

        public static boolean supports​(AFUNIXSocketCapability capability)
        Checks if the current environment (system platform, native library, etc.) supports a given junixsocket capability.
        Parameters:
        capability - The capability.
        Returns:
        true if supported.

      • close

        public void close()
           throws java.io.IOException
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Overrides:
        close in class java.net.Socket
        Throws:
        java.io.IOException

      • addCloseable

        public void addCloseable​(java.io.Closeable closeable)
        Registers a Closeable that should be closed when this socket is closed.
        Parameters:
        closeable - The closeable.

      • removeCloseable

        public void removeCloseable​(java.io.Closeable closeable)
        Unregisters a previously registered Closeable.
        Parameters:
        closeable - The closeable.

      • main

        public static void main​(java.lang.String[] args)
        Very basic self-test function. Prints "supported" and "capabilities" status to System.out.
        Parameters:
        args - ignored.