net-common: Javadoc fixes
This commit is contained in:
net-common/main/java/org/omegazero/net
@ -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
|
||||
|
Reference in New Issue
Block a user