* Creating and starting an event machine: + *
** EventMachine em = new EventMachine(); * // Start our event machine thread: @@ -94,8 +95,7 @@ public class EventMachine /** * Execute a runnable on the Event/NIO thread. - ** Using regular sockets: - *- * This method is thread-safe. + *
This method is thread-safe.
* * @param runnable the runnable to execute on the server thread as soon as possible, */ @@ -109,8 +109,8 @@ public class EventMachine ** This is the primary way to execute delayed events, typically time-outs and similar * behaviour. - *
- * This method is thread-safe. + *
+ *This method is thread-safe.
* * @param runnable the runnable to execute after the given delay. * @param msDelay the delay until executing this runnable. @@ -138,10 +138,8 @@ public class EventMachine } /** * Execute a runnable on the Event/NIO thread after at a certain time. - * - * This is the primary way to execute scheduled events. - * - * This method is thread-safe. + *This is the primary way to execute scheduled events.
+ *This method is thread-safe.
* * @param runnable the runnable to execute at the given time. * @param date the time date when this runnable should execute. @@ -158,8 +156,8 @@ public class EventMachine ** The observer will receive all exceptions thrown by the underlying NIOService * and by queued events. - *
- * This method is thread-safe. + *
+ *This method is thread-safe.
* * @param observer the observer to use, null will cause exceptions to log to stderr */ @@ -183,9 +181,10 @@ public class EventMachine /** * Causes the event machine to start running on a separate thread together with the * NIOService. - * + ** Note that the NIOService should not be called (using {@link naga.NIOService#selectNonBlocking()} and related * functions) on another thread if the EventMachine is used. + *
*/ public synchronized void start() { --- a/src/main/naga/examples/package-info.java 2020-09-30 03:56:57.000000000 -0600 +++ b/src/main/naga/examples/package-info.java 2020-09-30 16:15:07.211281049 -0600 @@ -1,6 +1,7 @@ /** * Various examples on how to use Naga. - * + ** These classes are only available in the debug version of the naga deliverable. + *
*/ package naga.examples; \ No newline at end of file --- a/src/main/naga/examples/Rot13Server.java 2020-09-30 03:56:57.000000000 -0600 +++ b/src/main/naga/examples/Rot13Server.java 2020-09-30 16:15:07.212281049 -0600 @@ -30,8 +30,9 @@ import java.io.IOException; /** * Creates a Rot13Server that takes a line of text and returns the Rot13 version of the * text. - * + ** Run using {@code java naga.examples.Rot13Server [port]}. + *
* * @author Christoffer Lerno */ --- a/src/main/naga/NIOService.java 2020-09-30 03:56:57.000000000 -0600 +++ b/src/main/naga/NIOService.java 2020-09-30 16:15:07.213281048 -0600 @@ -38,31 +38,36 @@ import java.util.concurrent.ConcurrentLi ** Common usage is to create a single instance of this service and * then run one other the select methods in a loop. + *
** Use {@link naga.NIOService#openSocket(String, int)} to open a socket to a remote server, * and {@link naga.NIOService#openServerSocket(int)} to open a server socket locally. + *
** Note that the NIOServerSocket by default opens in a "refuse connections" state. To * start accepting players, the socket's acceptor must first be set to accept connections. * See documentation for openServerSocket for more details. + *
** Example use: + *
** Using the server socket: - *
+ *
+ *
* NIOService service = new NIOService;
* NIOSocket socket = service.openSocket("www.google.com", 1234);
* socket.listen(myObserver);
* // Asynchronous write by default:
* socket.write("Some message".getBytes());
- *
* This roughly corresponds to creating a regular socket using new Socket(host, port). - *
- * This method is thread-safe. + *
+ *This method is thread-safe.
* * @param host the host we want to connect to. * @param port the port to use for the connection. @@ -183,8 +188,8 @@ public class NIOService * a NIOSocketSSL. ** This roughly corresponds to creating a regular socket using new SSLSocket(host, port). - *
- * This method is thread-safe. + *
+ *This method is thread-safe.
* * @param sslEngine the SSL engine to use for SSL-negotiation. * @param host the host we want to connect to. @@ -202,8 +207,8 @@ public class NIOService * a NIOSocket. ** This roughly corresponds to creating a regular socket using new Socket(inetAddress, port). - *
- * This method is thread-safe. + *
+ *This method is thread-safe.
* * @param inetAddress the address we want to connect to. * @param port the port to use for the connection. @@ -224,8 +229,8 @@ public class NIOService * a NIOSocketSSL. ** This roughly corresponds to creating a regular socket using new SSLSocket(inetAddress, port). - *
- * This method is thread-safe. + *
+ *This method is thread-safe.
* * @param sslEngine the SSL engine to use for SSL-negotiation. * @param inetAddress the address we want to connect to. @@ -248,8 +253,8 @@ public class NIOService * Open a server socket on the given port. ** This roughly corresponds to using new ServerSocket(port, backlog); - *
- * This method is thread-safe. + *
+ *This method is thread-safe.
* * @param port the port to open. * @param backlog the maximum connection backlog (i.e. connections pending accept) @@ -265,8 +270,8 @@ public class NIOService * Open an SSL server socket on the given port. ** This roughly corresponds to using new SSLServerSocket(port, backlog); - *
- * This method is thread-safe. + *
+ *This method is thread-safe.
* * @param sslContext the SSLContext to use for SSL-negotiation. * @param port the port to open. @@ -283,8 +288,8 @@ public class NIOService * Open a server socket on the given port with the default connection backlog. ** This roughly corresponds to using new ServerSocket(port); - *
- * This method is thread-safe. + *
+ *This method is thread-safe.
* * @param port the port to open. * @return a NIOServerSocket for asynchronous connection to the server socket. @@ -299,8 +304,8 @@ public class NIOService * Open an SSL server socket on the given port with the default connection backlog. ** This roughly corresponds to using new SSLServerSocket(port); - *
- * This method is thread-safe. + *
+ *This method is thread-safe.
* * @param sslContext the SSLContext to use for SSL-negotiation. * @param port the port to open. @@ -314,8 +319,7 @@ public class NIOService /** * Open an SSL server socket on the address. - *- * This method is thread-safe. + *
This method is thread-safe.
* * @param sslContext the SSLContext to use for SSL-negotiation. * @param address the address to open. @@ -337,8 +341,7 @@ public class NIOService /** * Open a server socket on the address. - *- * This method is thread-safe. + *
This method is thread-safe.
* * @param address the address to open. * @param backlog the maximum connection backlog (i.e. connections pending accept) @@ -359,8 +362,7 @@ public class NIOService /** * Internal method to mark a socket channel for pending registration * and create a NIOSocket wrapper around it. - *- * This method is thread-safe. + *
This method is thread-safe.
* * @param socketChannel the socket channel to wrap. * @param address the address for this socket. @@ -379,6 +381,7 @@ public class NIOService * Internal method to execute events on the internal event queue. ** This method should only ever be called from the NIOService thread. + *
*/ private void executeQueue() { @@ -400,8 +403,8 @@ public class NIOService * Internal method to handle the key set generated by the internal Selector. ** Will simply remove each entry and handle the key. - *
- * Called on the NIOService thread. + *
+ *Called on the NIOService thread.
*/ private void handleSelectedKeys() { @@ -428,8 +431,7 @@ public class NIOService /** * Set the new shared buffer size. - *- * This method is *not* thread-safe. + *
This method is *not* thread-safe.
* @param newBufferSize the new buffer size. * @throws IllegalArgumentException if the new size is less than 256 bytes. */ @@ -441,8 +443,7 @@ public class NIOService /** * Returns the new shared buffer size. - * - * This method is *not* thread-safe. + *This method is *not* thread-safe.
* * @return the current buffer size, which is the largest packet that can be read. */ @@ -467,8 +468,8 @@ public class NIOService * Internal method to handle a SelectionKey that has changed. ** Will delegate actual actions to the associated ChannelResponder. - *
- * Called on the NIOService thread. + *
+ *Called on the NIOService thread.
* @param key the key to handle. */ private void handleKey(SelectionKey key) @@ -504,10 +505,9 @@ public class NIOService * Close the entire service. ** This will disconnect all sockets associated with this service. - *
- * It is not possible to restart the service once closed. - *
- * This method is thread-safe. + *
+ *It is not possible to restart the service once closed.
+ *This method is thread-safe.
*/ public void close() { @@ -518,8 +518,7 @@ public class NIOService /** * Determine if this service is open. - *- * This method is thread-safe. + *
This method is thread-safe.
* * @return true if the service is open, false otherwise. */ @@ -533,6 +532,7 @@ public class NIOService ** This method is thread-safe, but should in general not be used by * other applications. + *
* * @param event the event to run on the NIOService-thread. */ @@ -578,8 +578,7 @@ public class NIOService /** * Logs an exception using the exception observer. This is mainly for use by the Naga classes. - *- * Should only be used on the NIOService thread. + *
Should only be used on the NIOService thread.
* * @param t the exception thrown. */ --- a/src/main/naga/NIOSocketSSL.java 2020-09-30 03:56:57.000000000 -0600 +++ b/src/main/naga/NIOSocketSSL.java 2020-09-30 16:15:07.213281048 -0600 @@ -40,6 +40,7 @@ public interface NIOSocketSSL extends NI /** * Initiates SSL-handshake, starts encrypted communication. + * @throws SSLException if the handshake fails */ void beginHandshake() throws SSLException; --- a/src/main/naga/NIOUtils.java 2020-09-30 03:56:57.000000000 -0600 +++ b/src/main/naga/NIOUtils.java 2020-09-30 16:15:07.214281048 -0600 @@ -54,7 +54,7 @@ public class NIOUtils * * @param byteBuffer the ByteBuffer to use. * @param headerSize the header size in bytes. 1-4. - * @param valueToEncode the value to encode, 0 <= value < 2^(headerSize * 8) + * @param valueToEncode the value to encode, 0 ≤ value < 2^(headerSize * 8) * @param bigEndian if the encoding is big endian or not. * @throws IllegalArgumentException if the value is out of range for the given header size. */ @@ -81,7 +81,7 @@ public class NIOUtils * * @param buffer the byte array to set the header for * @param headerSize the header size in bytes. 1-4. - * @param valueToEncode the value to encode, 0 <= value < 2^(headerSize * 8) + * @param valueToEncode the value to encode, 0 ≤ value < 2^(headerSize * 8) * @param bigEndian if the encoding is big endian or not. * @throws IllegalArgumentException if the value is out of range for the given header size. */ @@ -107,6 +107,7 @@ public class NIOUtils * encoding. ** Note that trying to decode a value larger than 2^31 - 2 is not supported. + *
* * @param header the header to encode from. * @param size the header size, 1-4. @@ -142,6 +143,7 @@ public class NIOUtils * encoding. ** Note that trying to decode a value larger than 2^31 - 2 is not supported. + *
* * @param data the data to encode from. * @param length the length of the header. --- a/src/main/naga/package-info.java 2020-09-30 03:56:57.000000000 -0600 +++ b/src/main/naga/package-info.java 2020-09-30 16:15:07.214281048 -0600 @@ -1,9 +1,10 @@ /** * The main Naga classes. - * + ** See {@link naga.NIOService} on how to start a new NIOService for asynchronous * socket I/O. - *
+ * + ** The library uses the implementations of {@link naga.NIOSocket} and {@link naga.NIOServerSocket} * as asynchronous counterparts to {@link java.net.Socket} and {@link java.net.ServerSocket}. *
--- a/src/main/naga/packetreader/DelimiterPacketReader.java 2020-09-30 03:56:57.000000000 -0600 +++ b/src/main/naga/packetreader/DelimiterPacketReader.java 2020-09-30 16:15:07.215281047 -0600 @@ -32,8 +32,8 @@ import java.nio.ByteBuffer; * Since packets read with delimiters may potentially grow unbounded, you can also supply * a maximum buffer size to prevent an attacker from causing an out of memory * by continously sending data without the delimiter. - *- * The delimiter will never appear in the packet itself. + *
+ *The delimiter will never appear in the packet itself.
* * @author Christoffer Lerno */ @@ -59,7 +59,7 @@ public class DelimiterPacketReader imple * @param delimiter the byte value of the delimiter. * @param maxPacketSize the maximum number of bytes read before throwing an * IOException. -1 means the packet has no size limit. - * @throws IllegalArgumentException if maxPacketSize < 1 + * @throws IllegalArgumentException if maxPacketSize < 1 */ public DelimiterPacketReader(byte delimiter, int maxPacketSize) { @@ -86,6 +86,7 @@ public class DelimiterPacketReader imple ** This method is thread-safe, but will not * affect reads in progress. + *
* * @param maxPacketSize the new maximum packet size. */ --- a/src/main/naga/PacketReader.java 2020-09-30 03:56:57.000000000 -0600 +++ b/src/main/naga/PacketReader.java 2020-09-30 16:15:07.215281047 -0600 @@ -29,6 +29,7 @@ import java.nio.ByteBuffer; * Interface for packet reader plugins to assist a socket in reading. ** PacketReaders are in general intended to help splitting + *
* * @author Christoffer Lerno */ @@ -40,8 +41,9 @@ public interface PacketReader /** * Create a new packet using the ByteBuffer given. - * + ** If there isn't sufficient data to construct a packet, return null. + *
* * @param byteBuffer the byte buffer to use. * @return the new packet created, or null if no packet could be created. The method will continously --- a/src/main/naga/packetreader/RegularPacketReader.java 2020-09-30 03:56:57.000000000 -0600 +++ b/src/main/naga/packetreader/RegularPacketReader.java 2020-09-30 16:15:07.216281047 -0600 @@ -29,14 +29,13 @@ import java.nio.ByteBuffer; /** * Reads packet of the format - *
- *
- * [header 1-4 bytes] => content size
- *
+ *
- * [content] => 0-255/0-65535/0-16777215/0-2147483646
- *
+ * [header 1-4 bytes] → content size + * [content] → 0-255/0-65535/0-16777215/0-2147483646 + **
* Note that the maximum size for 4 bytes is a signed 32 bit int, not unsigned. + *
* * @author Christoffer Lerno */ --- a/src/main/naga/packetwriter/RegularPacketWriter.java 2020-09-30 03:56:57.000000000 -0600 +++ b/src/main/naga/packetwriter/RegularPacketWriter.java 2020-09-30 16:15:07.216281047 -0600 @@ -28,19 +28,19 @@ import java.nio.ByteBuffer; /** * Writes packet of the format - *
- *
- * [header 1-4 bytes] => content size
- *
+ *
- * [content] => 0-255/0-65535/0-16777215/0-2147483646
- *
+ * [header 1-4 bytes] → content size + * [content] → 0-255/0-65535/0-16777215/0-2147483646 + **
* Note that the maximum size for 4 bytes is a signed 32 bit int, not unsigned. + *
** The packet writer will not validate outgoing packets, so make sure that * the packet content size will fit in the header. I.e. make sure that if you have * a 1 byte header, you do not send packets larger than 255 bytes, if two bytes, larger than 65535 and * so on. + *
* * @author Christoffer Lerno */