net-common: Javadoc fixes

This commit is contained in:
2023-01-08 13:15:59 +01:00
parent 7e1decd80d
commit 63d709dee1
4 changed files with 52 additions and 17 deletions

@ -28,20 +28,20 @@ public final class NetCommon {
public static final String VERSION = "$BUILDVERSION";
/**
* System property <code>org.omegazero.net.printStackTraces</code><br>
* <br>
* Whether the full stack trace of a socket error should be printed instead of just the error message.<br>
* <br>
* System property <code>org.omegazero.net.printStackTraces</code>
* <p>
* Whether the full stack trace of a socket error should be printed instead of just the error message.
* <p>
* <b>Default:</b> <code>false</code>
*/
public static final boolean PRINT_STACK_TRACES = PropertyUtil.getBoolean("org.omegazero.net.printStackTraces", false);
/**
* System property <code>org.omegazero.net.socketErrorDebug</code><br>
* <br>
* System property <code>org.omegazero.net.socketErrorDebug</code>
* <p>
* Whether the default socket error handler should print socket error messages with log level <i>DEBUG</i> instead of <i>WARN</i>. This may be used to reduce log noise on
* public-facing servers where there may be many misbehaving clients connecting to it.<br>
* <br>
* public-facing servers where there may be many misbehaving clients connecting to it.
* <p>
* <b>Default:</b> <code>false</code>
*/
public static final boolean SOCKET_ERROR_DEBUG = PropertyUtil.getBoolean("org.omegazero.net.socketErrorDebug", false);

@ -1,9 +1,15 @@
/*
* Copyright (C) 2022 omegazero.org, user94729
*
* This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
* If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/.
*/
package org.omegazero.net.common;
/**
* Wraps any {@code Throwable} in this unchecked exception, accessible using {@link #getCause()}.
* <p>
* Thrown by {@link SocketConnection} methods if no {@code onError} handler is set. Note that, usually, classes creating and managing a {@link SocketConnection} will set a
* Thrown by {@link org.omegazero.net.socket.SocketConnection} methods if no {@code onError} handler is set. Note that, usually, classes creating and managing a {@code SocketConnection} will set a
* default error handler, which will cause the error handler to be called instead of this exception being thrown.
*
* @since 1.6

@ -26,11 +26,29 @@ import org.omegazero.net.util.SyncWorker;
*/
public abstract class AbstractSocketConnection extends SimpleAttachmentContainer implements SocketConnection {
/**
* Event ID of the {@code connect} event.
*/
protected static final int EV_CONNECT = 0;
/**
* Event ID of the {@code timeout} event.
*/
protected static final int EV_TIMEOUT = 1;
/**
* Event ID of the {@code data} event.
*/
protected static final int EV_DATA = 2;
/**
* Event ID of the {@code writable} event.
*/
protected static final int EV_WRITABLE = 3;
/**
* Event ID of the {@code close} event.
*/
protected static final int EV_CLOSE = 4;
/**
* Event ID of the {@code error} event.
*/
protected static final int EV_ERROR = 5;
/**
@ -233,21 +251,21 @@ public abstract class AbstractSocketConnection extends SimpleAttachmentContainer
/**
* Called internally, by subclasses or by classes managing this {@code SocketConnection} if this socket connects. This method calls the {@code connect} event.
* Called internally, by subclasses or by classes managing this {@code SocketConnection} when this socket connects. This method calls the {@code connect} event.
*/
public final void handleConnect(){
this.runAsync(this::runOnConnect);
}
/**
* Called internally, by subclasses or by classes managing this {@code SocketConnection} if a connection attempt times out. This method calls the {@code timeout} event.
* Called internally, by subclasses or by classes managing this {@code SocketConnection} when a connection attempt times out. This method calls the {@code timeout} event.
*/
public final void handleTimeout(){
this.runAsync(this::runOnTimeout);
}
/**
* Called by classes managing this {@link SocketConnection} if data was received using {@link #read()}. This method calls the {@code data} event.
* Called by classes managing this {@link SocketConnection} when data was received using {@link #read()}. This method calls the {@code data} event.
*
* @param data The data that was received on this connection
* @return <code>false</code> if no {@code data} event handler was set upon entry of this method
@ -259,14 +277,14 @@ public abstract class AbstractSocketConnection extends SimpleAttachmentContainer
}
/**
* Called by subclasses if this socket is writable. This method calls the {@code writable} event.
* Called by subclasses when this socket is writable. This method calls the {@code writable} event.
*/
public final void handleWritable() {
this.runAsync(this::runOnWritable);
}
/**
* Called by subclasses or classes managing this {@link SocketConnection} if this connection closed. This method calls the {@code close} event on the first invocation of
* Called by subclasses or classes managing this {@link SocketConnection} when this connection closed. This method calls the {@code close} event on the first invocation of
* this method.
*/
public final void handleClose() {
@ -280,7 +298,7 @@ public abstract class AbstractSocketConnection extends SimpleAttachmentContainer
/**
* Called by subclasses or classes managing this {@link SocketConnection} if an error occurred in a callback. This method calls the {@code error} event and
* Called by subclasses or classes managing this {@link SocketConnection} when an error occurred in a callback. This method calls the {@code error} event and
* {@linkplain #destroy() forcibly closes} this connection.
* <p>
* Unlike the other {@code handle} methods, this method always runs synchronously.
@ -330,6 +348,11 @@ public abstract class AbstractSocketConnection extends SimpleAttachmentContainer
}
/**
* Delegates the given {@code Runnable} to this {@code AbstractSocketConnection}'s worker.
*
* @param runnable The runnable
*/
protected final void runAsync(Runnable runnable) {
this.worker.accept(() -> {
try{
@ -340,6 +363,12 @@ public abstract class AbstractSocketConnection extends SimpleAttachmentContainer
});
}
/**
* Delegates the given {@code Consumer} to this {@code AbstractSocketConnection}'s worker.
*
* @param runnable The consumer
* @param value The value to pass to the consumer
*/
protected final <T> void runAsync(Consumer<T> runnable, T value) {
this.worker.accept(() -> {
try{

@ -23,7 +23,7 @@ import org.omegazero.common.util.function.ThrowingRunnable;
* for this {@code SocketConnection} is listed in the documentation of this method.
* <p>
* None of the methods in this interface throw any checked exceptions. Exceptions in most callbacks or IO operations are caught internally by the implementation and passed to the
* {@code error} event handlers, which is one of the few callbacks that can and should not throw an exception itself. After an error, the connection is forcibly closed.
* {@code error} event handlers, which is one of the few callbacks that should not throw an exception itself. After an error, the connection is forcibly closed.
* <p>
* Implementations should inherit from {@link AbstractSocketConnection}, because it already contains several implemented methods and utility methods.
*
@ -394,7 +394,7 @@ public interface SocketConnection extends java.io.Closeable {
/**
* Sets a callback that is called when an error occurs on this connection.
* <p>
* This callback is usually followed by a <code>onClose</code> (set using {@link SocketConnection#setOnClose(Runnable)}) callback.
* This callback is usually followed by a <code>onClose</code> callback.
*
* @param onError The callback
* @deprecated Since 2.2.0, use {@link #on(String, GenericRunnable)} instead