From 8ea3ba6256cb0634937bda9200bd210d7f250273 Mon Sep 17 00:00:00 2001 From: Davis Rollman Date: Wed, 15 Apr 2026 21:28:08 -0400 Subject: [PATCH] Fix jme3-networking javadoc lint issues --- jme3-networking/build.gradle | 7 -- .../com/jme3/network/AbstractMessage.java | 8 ++ .../main/java/com/jme3/network/Client.java | 31 +++++- .../com/jme3/network/ClientStateListener.java | 17 +++ .../com/jme3/network/ConnectionListener.java | 6 ++ .../java/com/jme3/network/ErrorListener.java | 7 ++ .../main/java/com/jme3/network/Filter.java | 5 +- .../main/java/com/jme3/network/Filters.java | 29 ++++- .../com/jme3/network/HostedConnection.java | 16 +++ .../main/java/com/jme3/network/Message.java | 5 + .../com/jme3/network/MessageConnection.java | 6 +- .../com/jme3/network/MessageListener.java | 7 ++ .../main/java/com/jme3/network/Network.java | 53 +++++++++ .../java/com/jme3/network/NetworkClient.java | 6 ++ .../main/java/com/jme3/network/Server.java | 42 +++++++- .../jme3/network/base/ConnectorAdapter.java | 36 +++++++ .../jme3/network/base/ConnectorFactory.java | 8 ++ .../com/jme3/network/base/DefaultClient.java | 75 +++++++++++++ .../com/jme3/network/base/DefaultServer.java | 88 +++++++++++++++ .../com/jme3/network/base/KernelAdapter.java | 72 ++++++++++++- .../com/jme3/network/base/KernelFactory.java | 11 ++ .../com/jme3/network/base/MessageBuffer.java | 8 +- .../network/base/MessageListenerRegistry.java | 33 ++++++ .../jme3/network/base/MessageProtocol.java | 19 +++- .../jme3/network/base/NioKernelFactory.java | 6 ++ .../network/base/TcpConnectorFactory.java | 5 + .../base/protocol/GreedyMessageBuffer.java | 6 +- .../base/protocol/LazyMessageBuffer.java | 6 +- .../protocol/SerializerMessageProtocol.java | 4 +- .../jme3/network/kernel/AbstractKernel.java | 26 +++++ .../com/jme3/network/kernel/Connector.java | 6 ++ .../network/kernel/ConnectorException.java | 11 ++ .../com/jme3/network/kernel/Endpoint.java | 12 +++ .../jme3/network/kernel/EndpointEvent.java | 46 +++++++- .../com/jme3/network/kernel/Envelope.java | 19 ++++ .../java/com/jme3/network/kernel/Kernel.java | 14 +++ .../jme3/network/kernel/KernelException.java | 11 ++ .../network/kernel/NamedThreadFactory.java | 25 ++++- .../jme3/network/kernel/tcp/NioEndpoint.java | 23 ++++ .../network/kernel/tcp/SelectorKernel.java | 101 ++++++++++++++++++ .../network/kernel/tcp/SocketConnector.java | 10 ++ .../jme3/network/kernel/udp/UdpConnector.java | 8 +- .../jme3/network/kernel/udp/UdpEndpoint.java | 13 +++ .../jme3/network/kernel/udp/UdpKernel.java | 74 +++++++++++++ .../network/message/ChannelInfoMessage.java | 19 ++++ .../message/ClientRegistrationMessage.java | 44 ++++++++ .../network/message/CompressedMessage.java | 18 ++++ .../network/message/DisconnectMessage.java | 46 ++++++++ .../message/GZIPCompressedMessage.java | 8 ++ .../SerializerRegistrationsMessage.java | 37 +++++++ .../network/message/ZIPCompressedMessage.java | 19 ++++ .../com/jme3/network/rmi/LocalObject.java | 5 + .../java/com/jme3/network/rmi/MethodDef.java | 5 + .../java/com/jme3/network/rmi/ObjectDef.java | 8 ++ .../com/jme3/network/rmi/ObjectStore.java | 46 ++++++++ .../network/rmi/RemoteMethodCallMessage.java | 3 + .../rmi/RemoteMethodReturnMessage.java | 3 + .../com/jme3/network/rmi/RemoteObject.java | 6 ++ .../network/rmi/RemoteObjectDefMessage.java | 6 ++ .../com/jme3/network/rmi/RmiSerializer.java | 6 ++ .../network/serializing/Serializable.java | 10 ++ .../jme3/network/serializing/Serializer.java | 96 +++++++++++++++++ .../serializing/SerializerException.java | 11 ++ .../serializing/SerializerRegistration.java | 7 ++ .../serializers/ArraySerializer.java | 5 + .../serializers/BooleanSerializer.java | 5 + .../serializers/ByteSerializer.java | 5 + .../serializers/CharSerializer.java | 5 + .../serializers/CollectionSerializer.java | 5 + .../serializers/DateSerializer.java | 5 + .../serializers/DoubleSerializer.java | 5 + .../serializers/EnumSerializer.java | 5 + .../serializers/FieldSerializer.java | 10 ++ .../serializers/FloatSerializer.java | 5 + .../serializers/GZIPSerializer.java | 5 + .../serializers/IntSerializer.java | 5 + .../serializers/LongSerializer.java | 5 + .../serializers/MapSerializer.java | 8 ++ .../serializers/SavableSerializer.java | 8 ++ .../serializers/SerializableSerializer.java | 5 + .../serializers/ShortSerializer.java | 5 + .../serializers/StringSerializer.java | 19 ++++ .../serializers/Vector3Serializer.java | 7 ++ .../serializers/ZIPSerializer.java | 5 + .../service/AbstractClientService.java | 5 + .../AbstractHostedConnectionService.java | 10 ++ .../service/AbstractHostedService.java | 5 + .../jme3/network/service/AbstractService.java | 12 +++ .../network/service/ClientServiceManager.java | 10 ++ .../network/service/HostedServiceManager.java | 23 ++++ .../com/jme3/network/service/Service.java | 5 + .../jme3/network/service/ServiceManager.java | 20 ++++ .../network/service/rmi/Asynchronous.java | 5 + .../jme3/network/service/rmi/ClassInfo.java | 38 +++++++ .../service/rmi/ClassInfoRegistry.java | 9 ++ .../jme3/network/service/rmi/MethodInfo.java | 44 ++++++++ .../service/rmi/RemoteObjectHandler.java | 14 +++ .../network/service/rmi/RmiClientService.java | 38 +++++++ .../jme3/network/service/rmi/RmiContext.java | 2 + .../network/service/rmi/RmiHostedService.java | 44 ++++++++ .../jme3/network/service/rmi/RmiRegistry.java | 91 +++++++++++++++- .../network/service/rpc/RpcClientService.java | 19 ++++ .../network/service/rpc/RpcConnection.java | 29 +++++ .../jme3/network/service/rpc/RpcHandler.java | 6 ++ .../network/service/rpc/RpcHostedService.java | 5 + .../service/rpc/msg/RpcCallMessage.java | 42 ++++++++ .../service/rpc/msg/RpcResponseMessage.java | 41 +++++++ .../ClientSerializerRegistrationsService.java | 8 +- .../ServerSerializerRegistrationsService.java | 7 +- .../util/AbstractMessageDelegator.java | 35 ++++++ .../network/util/ObjectMessageDelegator.java | 4 + .../network/util/SessionDataDelegator.java | 8 ++ 112 files changed, 2105 insertions(+), 25 deletions(-) diff --git a/jme3-networking/build.gradle b/jme3-networking/build.gradle index 510ad429c5..9dd715218e 100644 --- a/jme3-networking/build.gradle +++ b/jme3-networking/build.gradle @@ -1,10 +1,3 @@ dependencies { api project(':jme3-core') } - -javadoc { - // Disable doclint for JDK8+. - if (JavaVersion.current().isJava8Compatible()){ - options.addStringOption('Xdoclint:none', '-quiet') - } -} diff --git a/jme3-networking/src/main/java/com/jme3/network/AbstractMessage.java b/jme3-networking/src/main/java/com/jme3/network/AbstractMessage.java index 2fe7b20b01..50bf1ad4da 100644 --- a/jme3-networking/src/main/java/com/jme3/network/AbstractMessage.java +++ b/jme3-networking/src/main/java/com/jme3/network/AbstractMessage.java @@ -44,10 +44,18 @@ public abstract class AbstractMessage implements Message { private transient boolean reliable = true; + /** + * Creates a reliable message by default. + */ protected AbstractMessage() { } + /** + * Creates a message with the specified reliability. + * + * @param reliable true if the message should be sent reliably + */ protected AbstractMessage( boolean reliable ) { this.reliable = reliable; diff --git a/jme3-networking/src/main/java/com/jme3/network/Client.java b/jme3-networking/src/main/java/com/jme3/network/Client.java index 28c966cb8f..82ad7b73fc 100644 --- a/jme3-networking/src/main/java/com/jme3/network/Client.java +++ b/jme3-networking/src/main/java/com/jme3/network/Client.java @@ -52,12 +52,16 @@ public interface Client extends MessageConnection /** * Returns true if this client is fully connected to the * host. + * + * @return true if the client is connected to the server */ public boolean isConnected(); /** * Returns true if this client has been started and is still * running. + * + * @return true if the client has been started and not yet closed */ public boolean isStarted(); @@ -65,6 +69,8 @@ public interface Client extends MessageConnection * Returns a unique ID for this client within the remote * server or -1 if this client isn't fully connected to the * server. + * + * @return the server-assigned client id, or -1 if not connected */ public int getId(); @@ -72,18 +78,24 @@ public interface Client extends MessageConnection * Returns the 'game name' for servers to which this client should be able * to connect. This should match the 'game name' set on the server or this * client will be turned away. + * + * @return the configured game name */ public String getGameName(); /** * Returns the game-specific version of the server this client should * be able to connect to. + * + * @return the expected game protocol version */ public int getVersion(); /** * Returns the manager for client services. Client services extend * the functionality of the client. + * + * @return the client service manager */ public ClientServiceManager getServices(); @@ -108,35 +120,49 @@ public interface Client extends MessageConnection /** * Adds a listener that will be notified about connection * state changes. + * + * @param listener the listener to add */ public void addClientStateListener( ClientStateListener listener ); /** * Removes a previously registered connection listener. + * + * @param listener the listener to remove */ public void removeClientStateListener( ClientStateListener listener ); /** * Adds a listener that will be notified when any message or object * is received from the server. + * + * @param listener the listener to add */ public void addMessageListener( MessageListener listener ); /** * Adds a listener that will be notified when messages of the specified * types are received. + * + * @param listener the listener to add + * @param classes the message classes the listener should receive */ public void addMessageListener( MessageListener listener, Class... classes ); /** * Removes a previously registered wildcard listener. This does * not remove this listener from any type-specific registrations. + * + * @param listener the listener to remove */ public void removeMessageListener( MessageListener listener ); /** * Removes a previously registered type-specific listener from * the specified types. + * + * @param listener the listener to remove + * @param classes the message classes to unregister */ public void removeMessageListener( MessageListener listener, Class... classes ); @@ -146,13 +172,16 @@ public interface Client extends MessageConnection * is to close the connection and provide an appropriate DisconnectInfo * to any ClientStateListeners. If the application adds its own error * listeners then it must take care of closing the connection itself. + * + * @param listener the listener to add */ public void addErrorListener( ErrorListener listener ); /** * Removes a previously registered error listener. + * + * @param listener the listener to remove */ public void removeErrorListener( ErrorListener listener ); } - diff --git a/jme3-networking/src/main/java/com/jme3/network/ClientStateListener.java b/jme3-networking/src/main/java/com/jme3/network/ClientStateListener.java index fc9ac6bfe1..2ca0b67d88 100644 --- a/jme3-networking/src/main/java/com/jme3/network/ClientStateListener.java +++ b/jme3-networking/src/main/java/com/jme3/network/ClientStateListener.java @@ -44,6 +44,8 @@ public interface ClientStateListener /** * Called when the specified client is fully connected to * the remote server. + * + * @param c the connected client */ public void clientConnected( Client c ); @@ -52,6 +54,9 @@ public interface ClientStateListener * server. If info is null then the client shut down the * connection normally, otherwise the info object contains * additional information about the disconnect. + * + * @param c the disconnected client + * @param info extra disconnect information, or null for a normal close */ public void clientDisconnected( Client c, DisconnectInfo info ); @@ -61,8 +66,20 @@ public interface ClientStateListener */ public class DisconnectInfo { + /** + * A human-readable reason for the disconnect, if provided. + */ public String reason; + /** + * The underlying disconnect cause, if one is available. + */ public Throwable error; + + /** + * Creates an empty disconnect information object. + */ + public DisconnectInfo() { + } @Override public String toString() { diff --git a/jme3-networking/src/main/java/com/jme3/network/ConnectionListener.java b/jme3-networking/src/main/java/com/jme3/network/ConnectionListener.java index 12d3a7262e..33cac128af 100644 --- a/jme3-networking/src/main/java/com/jme3/network/ConnectionListener.java +++ b/jme3-networking/src/main/java/com/jme3/network/ConnectionListener.java @@ -44,12 +44,18 @@ public interface ConnectionListener /** * Called when a connection has been added to the specified server and * is fully setup. + * + * @param server the server that accepted the connection + * @param conn the newly connected client */ public void connectionAdded( Server server, HostedConnection conn ); /** * Called when a connection has been removed from the specified * server. + * + * @param server the server that removed the connection + * @param conn the disconnected client */ public void connectionRemoved( Server server, HostedConnection conn ); } diff --git a/jme3-networking/src/main/java/com/jme3/network/ErrorListener.java b/jme3-networking/src/main/java/com/jme3/network/ErrorListener.java index 3825396d20..8c8fc0cde1 100644 --- a/jme3-networking/src/main/java/com/jme3/network/ErrorListener.java +++ b/jme3-networking/src/main/java/com/jme3/network/ErrorListener.java @@ -35,10 +35,17 @@ /** * Notified when errors happen on a connection. * + * @param the connection or endpoint type that produced the error * @version $Revision$ * @author Paul Speed */ public interface ErrorListener { + /** + * Handles an error that occurred on the specified source. + * + * @param source the connection or endpoint that produced the error + * @param t the error that was raised + */ public void handleError( S source, Throwable t ); } diff --git a/jme3-networking/src/main/java/com/jme3/network/Filter.java b/jme3-networking/src/main/java/com/jme3/network/Filter.java index de8f324e32..6fcfa9b920 100644 --- a/jme3-networking/src/main/java/com/jme3/network/Filter.java +++ b/jme3-networking/src/main/java/com/jme3/network/Filter.java @@ -35,6 +35,7 @@ /** * Determines a true or false value for a given input. * + * @param the input type tested by this filter * @version $Revision$ * @author Paul Speed */ @@ -43,8 +44,10 @@ public interface Filter /** * Returns true if the specified input is accepted by this * filter. + * + * @param input the value to test + * @return true if the input is accepted */ public boolean apply( T input ); } - diff --git a/jme3-networking/src/main/java/com/jme3/network/Filters.java b/jme3-networking/src/main/java/com/jme3/network/Filters.java index be21aeb1bc..0eb4e0a827 100644 --- a/jme3-networking/src/main/java/com/jme3/network/Filters.java +++ b/jme3-networking/src/main/java/com/jme3/network/Filters.java @@ -52,6 +52,10 @@ private Filters() { /** * Creates a filter that returns true for any value in the specified * list of values and false for all other cases. + * + * @param the value type + * @param values the accepted values + * @return a membership filter for the provided values */ @SuppressWarnings("unchecked") public static Filter in( T... values ) @@ -62,6 +66,10 @@ public static Filter in( T... values ) /** * Creates a filter that returns true for any value in the specified * collection and false for all other cases. + * + * @param the value type + * @param collection the accepted values + * @return a membership filter for the provided collection */ public static Filter in( Collection collection ) { @@ -72,6 +80,10 @@ public static Filter in( Collection collection ) * Creates a filter that returns true for any value NOT in the specified * list of values and false for all other cases. This is the equivalent * of calling not(in(values)). + * + * @param the value type + * @param values the rejected values + * @return a negated membership filter for the provided values */ @SuppressWarnings("unchecked") public static Filter notIn( T... values ) @@ -83,6 +95,10 @@ public static Filter notIn( T... values ) * Creates a filter that returns true for any value NOT in the specified * collection and false for all other cases. This is the equivalent * of calling not(in(collection)). + * + * @param the value type + * @param collection the rejected values + * @return a negated membership filter for the provided collection */ public static Filter notIn( Collection collection ) { @@ -92,6 +108,10 @@ public static Filter notIn( Collection collection ) /** * Creates a filter that returns true for inputs that are .equals() * equivalent to the specified value. + * + * @param the value type + * @param value the accepted value + * @return an equality filter */ public static Filter equalTo( T value ) { @@ -102,6 +122,10 @@ public static Filter equalTo( T value ) * Creates a filter that returns true for inputs that are NOT .equals() * equivalent to the specified value. This is the equivalent of calling * not(equalTo(value)). + * + * @param the value type + * @param value the rejected value + * @return an inequality filter */ public static Filter notEqualTo( T value ) { @@ -111,6 +135,10 @@ public static Filter notEqualTo( T value ) /** * Creates a filter that returns true when the specified delegate filter * returns false, and vice versa. + * + * @param the value type + * @param f the delegate filter + * @return a negated filter */ public static Filter not( Filter f ) { @@ -166,4 +194,3 @@ public boolean apply( T input ) } } - diff --git a/jme3-networking/src/main/java/com/jme3/network/HostedConnection.java b/jme3-networking/src/main/java/com/jme3/network/HostedConnection.java index 1aaf517301..779c9687b7 100644 --- a/jme3-networking/src/main/java/com/jme3/network/HostedConnection.java +++ b/jme3-networking/src/main/java/com/jme3/network/HostedConnection.java @@ -44,11 +44,15 @@ public interface HostedConnection extends MessageConnection { /** * Returns the Server instance that is hosting this connection. + * + * @return the owning server */ public Server getServer(); /** * Returns the server-unique ID for this client. + * + * @return the hosted connection id */ public int getId(); @@ -57,12 +61,16 @@ public interface HostedConnection extends MessageConnection * as a string. This may or may not be unique per connection depending * on the type of transport. It is provided for information and filtering * purposes. + * + * @return the remote address string */ public String getAddress(); /** * Closes and removes this connection from the server * sending the optional reason to the remote client. + * + * @param reason the optional disconnect reason */ public void close( String reason ); @@ -70,6 +78,8 @@ public interface HostedConnection extends MessageConnection * Sets a session attribute specific to this connection. If the value * is set to null then the attribute is removed. * + * @param name the attribute name + * @param value the attribute value, or null to remove it * @return The previous session value for this key or null * if there was no previous value. */ @@ -78,12 +88,18 @@ public interface HostedConnection extends MessageConnection /** * Retrieves a previously stored session attribute or * null if no such attribute exists. + * + * @param the expected attribute type + * @param name the attribute name + * @return the stored attribute value, or null if none exists */ public T getAttribute( String name ); /** * Returns a read-only set of attribute names currently stored * for this client session. + * + * @return the current attribute names */ public Set attributeNames(); } diff --git a/jme3-networking/src/main/java/com/jme3/network/Message.java b/jme3-networking/src/main/java/com/jme3/network/Message.java index 9586b039e5..df8677bebf 100644 --- a/jme3-networking/src/main/java/com/jme3/network/Message.java +++ b/jme3-networking/src/main/java/com/jme3/network/Message.java @@ -45,12 +45,17 @@ public interface Message /** * Sets this message to 'reliable' or not and returns this * message. + * + * @param f true to send the message reliably + * @return this message for chaining */ public Message setReliable(boolean f); /** * Indicates which way an outgoing message should be sent * or which way an incoming message was sent. + * + * @return true if the message is or was sent reliably */ public boolean isReliable(); } diff --git a/jme3-networking/src/main/java/com/jme3/network/MessageConnection.java b/jme3-networking/src/main/java/com/jme3/network/MessageConnection.java index 0938e1e452..45d1cbd44c 100644 --- a/jme3-networking/src/main/java/com/jme3/network/MessageConnection.java +++ b/jme3-networking/src/main/java/com/jme3/network/MessageConnection.java @@ -69,13 +69,17 @@ public interface MessageConnection /** * Sends a message to the other end of the connection. + * + * @param message the message to send */ public void send( Message message ); /** * Sends a message to the other end of the connection using * the specified alternate channel. + * + * @param channel the transport channel to use + * @param message the message to send */ public void send( int channel, Message message ); } - diff --git a/jme3-networking/src/main/java/com/jme3/network/MessageListener.java b/jme3-networking/src/main/java/com/jme3/network/MessageListener.java index 68c708b160..26342731e2 100644 --- a/jme3-networking/src/main/java/com/jme3/network/MessageListener.java +++ b/jme3-networking/src/main/java/com/jme3/network/MessageListener.java @@ -44,10 +44,17 @@ * and the messages will always be delivered to that connection in the * order that they were delivered.

* + * @param the source connection type that delivers messages * @version $Revision$ * @author Paul Speed */ public interface MessageListener { + /** + * Called when a message is received from a source. + * + * @param source the connection or endpoint that delivered the message + * @param m the received message + */ public void messageReceived( S source, Message m ); } diff --git a/jme3-networking/src/main/java/com/jme3/network/Network.java b/jme3-networking/src/main/java/com/jme3/network/Network.java index 8e05e4c2f0..489ffe7235 100644 --- a/jme3-networking/src/main/java/com/jme3/network/Network.java +++ b/jme3-networking/src/main/java/com/jme3/network/Network.java @@ -50,7 +50,13 @@ */ public class Network { + /** + * Default game name used by the convenience factory methods. + */ public static final String DEFAULT_GAME_NAME = "Unnamed jME3 Game"; + /** + * Default protocol version used by the convenience factory methods. + */ public static final int DEFAULT_VERSION = 42; /** @@ -63,6 +69,10 @@ private Network() { * Creates a Server that will utilize both reliable and fast * transports to communicate with clients. The specified port * will be used for both TCP and UDP communication. + * + * @param port the port used for both TCP and UDP communication + * @return the created server + * @throws IOException if the server cannot be created */ public static Server createServer( int port ) throws IOException { @@ -73,6 +83,11 @@ public static Server createServer( int port ) throws IOException * Creates a Server that will utilize both reliable and fast * transports to communicate with clients. The specified port * will be used for both TCP and UDP communication. + * + * @param tcpPort the TCP listening port + * @param udpPort the UDP listening port + * @return the created server + * @throws IOException if the server cannot be created */ public static Server createServer( int tcpPort, int udpPort ) throws IOException { @@ -92,6 +107,8 @@ public static Server createServer( int tcpPort, int udpPort ) throws IOException * @param udpPort The port upon which the UDP hosting will listen for new 'fast' UDP * messages. Set to -1 if 'fast' traffic should go over TCP. This will * completely disable UDP traffic for this server. + * @return the created server + * @throws IOException if the server cannot be created */ public static Server createServer( String gameName, int version, int tcpPort, int udpPort ) throws IOException { @@ -103,6 +120,8 @@ public static Server createServer( String gameName, int version, int tcpPort, in /** * Creates a client that can be connected at a later time. + * + * @return the created client */ public static NetworkClient createClient() { @@ -113,6 +132,10 @@ public static NetworkClient createClient() * Creates a client that can be connected at a later time. The specified * game name and version must match the server or the client will be turned * away. + * + * @param gameName the expected game name + * @param version the expected protocol version + * @return the created client */ public static NetworkClient createClient( String gameName, int version ) { @@ -122,6 +145,11 @@ public static NetworkClient createClient( String gameName, int version ) /** * Creates a Client that communicates with the specified host and port * using both reliable and fast transports. + * + * @param host the remote host name or address + * @param hostPort the remote TCP and UDP port + * @return the connected client + * @throws IOException if the client cannot connect */ public static Client connectToServer( String host, int hostPort ) throws IOException { @@ -131,6 +159,12 @@ public static Client connectToServer( String host, int hostPort ) throws IOExcep /** * Creates a Client that communicates with the specified host and separate TCP and UDP ports * using both reliable and fast transports. + * + * @param host the remote host name or address + * @param hostPort the remote TCP port + * @param remoteUdpPort the remote UDP port + * @return the connected client + * @throws IOException if the client cannot connect */ public static Client connectToServer( String host, int hostPort, int remoteUdpPort ) throws IOException { @@ -140,6 +174,13 @@ public static Client connectToServer( String host, int hostPort, int remoteUdpPo /** * Creates a Client that communicates with the specified host and port * using both reliable and fast transports. + * + * @param gameName the expected game name + * @param version the expected protocol version + * @param host the remote host name or address + * @param hostPort the remote TCP and UDP port + * @return the connected client + * @throws IOException if the client cannot connect */ public static Client connectToServer( String gameName, int version, String host, int hostPort ) throws IOException @@ -156,12 +197,15 @@ public static Client connectToServer( String gameName, int version, * @param version This is a game-specific version that helps detect when out-of-date * clients have connected to an incompatible server. This must match * the server's version of this client will be turned away. + * @param host the remote host name or address * @param hostPort The remote TCP port on the server to which this client should * send reliable messages. * @param remoteUdpPort The remote UDP port on the server to which this client should * send 'fast'/unreliable messages. Set to -1 if 'fast' traffic should * go over TCP. This will completely disable UDP traffic for this * client. + * @return the connected client + * @throws IOException if the client cannot connect */ public static Client connectToServer( String gameName, int version, String host, int hostPort, int remoteUdpPort ) throws IOException @@ -174,8 +218,17 @@ public static Client connectToServer( String gameName, int version, } + /** + * Client implementation used by the convenience factory methods. + */ protected static class NetworkClientImpl extends DefaultClient implements NetworkClient { + /** + * Creates a network client implementation. + * + * @param gameName the expected game name + * @param version the expected protocol version + */ public NetworkClientImpl(String gameName, int version) { super( gameName, version ); diff --git a/jme3-networking/src/main/java/com/jme3/network/NetworkClient.java b/jme3-networking/src/main/java/com/jme3/network/NetworkClient.java index 846b283f22..f4a16154f7 100644 --- a/jme3-networking/src/main/java/com/jme3/network/NetworkClient.java +++ b/jme3-networking/src/main/java/com/jme3/network/NetworkClient.java @@ -47,6 +47,11 @@ public interface NetworkClient extends Client { /** * Connects this client to the specified remote server and ports. + * + * @param host the remote host name or address + * @param port the remote TCP port + * @param remoteUdpPort the remote UDP port + * @throws IOException if the client cannot connect */ public void connectToServer( String host, int port, int remoteUdpPort ) throws IOException; @@ -60,6 +65,7 @@ public interface NetworkClient extends Client * send 'fast'/unreliable messages. Set to -1 if 'fast' traffic should * go over TCP. This will completely disable UDP traffic for this * client. + * @throws IOException if the client cannot connect */ public void connectToServer( InetAddress address, int port, int remoteUdpPort ) throws IOException; diff --git a/jme3-networking/src/main/java/com/jme3/network/Server.java b/jme3-networking/src/main/java/com/jme3/network/Server.java index d5f40f1b23..06f667a513 100644 --- a/jme3-networking/src/main/java/com/jme3/network/Server.java +++ b/jme3-networking/src/main/java/com/jme3/network/Server.java @@ -47,23 +47,31 @@ public interface Server /** * Returns the 'game name' for this server. This should match the * 'game name' set on connecting clients or they will be turned away. + * + * @return the server game name */ public String getGameName(); /** * Returns the game-specific version of this server used for detecting * mismatched clients. + * + * @return the server protocol version */ public int getVersion(); /** * Returns the manager for hosted services. Hosted services extend * the functionality of the server. + * + * @return the hosted service manager */ public HostedServiceManager getServices(); /** * Sends the specified message to all connected clients. + * + * @param message the message to broadcast */ public void broadcast( Message message ); @@ -80,6 +88,9 @@ public interface Server * // Broadcast to all connections exception source * server.broadcast( Filters.notEqualTo( source ), message ); * + * + * @param filter the connection filter, or null to target all connections + * @param message the message to broadcast */ public void broadcast( Filter filter, Message message ); @@ -96,6 +107,10 @@ public interface Server * // Broadcast to all connections exception source * server.broadcast( Filters.notEqualTo( source ), message ); * + * + * @param channel the alternate channel to use + * @param filter the connection filter, or null to target all connections + * @param message the message to broadcast */ public void broadcast( int channel, Filter filter, Message message ); @@ -113,11 +128,16 @@ public interface Server * Returns the ID of the created channel for use when specifying the channel in send or * broadcast calls. The ID is returned entirely out of convenience since the IDs * are predictably incremented. The first channel is 0, second is 1, and so on. + * + * @param port the port to bind for the new channel + * @return the newly assigned channel id */ public int addChannel( int port ); /** * Returns true if the server has been started. + * + * @return true if the server is running */ public boolean isRunning(); @@ -129,28 +149,39 @@ public interface Server /** * Retrieves a hosted connection by ID. + * + * @param id the server-assigned connection id + * @return the matching connection, or null if none exists */ public HostedConnection getConnection( int id ); /** * Retrieves a read-only collection of all currently connected connections. + * + * @return the current hosted connections */ public Collection getConnections(); /** * Returns true if the server has active connections at the time of this * call. + * + * @return true if at least one connection is active */ public boolean hasConnections(); /** * Adds a listener that will be notified when new hosted connections * arrive. + * + * @param listener the listener to add */ public void addConnectionListener( ConnectionListener listener ); /** * Removes a previously registered connection listener. + * + * @param listener the listener to remove */ public void removeConnectionListener( ConnectionListener listener ); @@ -167,27 +198,36 @@ public interface Server * and the messages will always be delivered to that connection in the * order that they were delivered. This is the only restriction placed * upon server message dispatch pool implementations.

+ * + * @param listener the listener to add */ public void addMessageListener( MessageListener listener ); /** * Adds a listener that will be notified when messages of the specified * types are received from one of the clients. + * + * @param listener the listener to add + * @param classes the message classes to match */ public void addMessageListener( MessageListener listener, Class... classes ); /** * Removes a previously registered wildcard listener. This does * not remove this listener from any type-specific registrations. + * + * @param listener the listener to remove */ public void removeMessageListener( MessageListener listener ); /** * Removes a previously registered type-specific listener from * the specified types. + * + * @param listener the listener to remove + * @param classes the message classes to unregister */ public void removeMessageListener( MessageListener listener, Class... classes ); } - diff --git a/jme3-networking/src/main/java/com/jme3/network/base/ConnectorAdapter.java b/jme3-networking/src/main/java/com/jme3/network/base/ConnectorAdapter.java index 1e434806c1..8a8ac275ab 100644 --- a/jme3-networking/src/main/java/com/jme3/network/base/ConnectorAdapter.java +++ b/jme3-networking/src/main/java/com/jme3/network/base/ConnectorAdapter.java @@ -76,6 +76,15 @@ public class ConnectorAdapter extends Thread // through this connector. private boolean reliable; + /** + * Creates an adapter for a connector and starts a background writer thread. + * + * @param connector the transport connector to wrap + * @param protocol the message protocol used to decode incoming messages + * @param dispatcher the listener that receives decoded messages + * @param errorHandler the error listener for connector failures + * @param reliable true if this adapter represents a reliable channel + */ public ConnectorAdapter( Connector connector, MessageProtocol protocol, MessageListener dispatcher, ErrorListener errorHandler, boolean reliable ) @@ -116,6 +125,9 @@ public ConnectorAdapter( Connector connector, MessageProtocol protocol, writer.start(); } + /** + * Closes the adapter and its underlying connector. + */ public void close() { go.set(false); @@ -130,11 +142,21 @@ public void close() } } + /** + * Dispatches a decoded message to the configured listener. + * + * @param m the decoded message + */ protected void dispatch( Message m ) { dispatcher.messageReceived( null, m ); } + /** + * Queues outbound bytes for writing on the background writer thread. + * + * @param data the bytes to write + */ public void write( ByteBuffer data ) { try { @@ -144,6 +166,11 @@ public void write( ByteBuffer data ) } } + /** + * Reports an adapter or connector error if the adapter is still active. + * + * @param e the error to report + */ protected void handleError( Exception e ) { if( !go.get() ) @@ -183,13 +210,22 @@ public void run() } } + /** + * Background writer thread that drains the outbound queue. + */ protected class WriterThread extends Thread { + /** + * Creates the background writer thread. + */ public WriterThread() { super( String.valueOf(connector) + "-writer" ); } + /** + * Stops the writer thread by interrupting its blocking wait. + */ public void shutdown() { interrupt(); diff --git a/jme3-networking/src/main/java/com/jme3/network/base/ConnectorFactory.java b/jme3-networking/src/main/java/com/jme3/network/base/ConnectorFactory.java index 9a15f17b06..3bd046f8bf 100644 --- a/jme3-networking/src/main/java/com/jme3/network/base/ConnectorFactory.java +++ b/jme3-networking/src/main/java/com/jme3/network/base/ConnectorFactory.java @@ -43,5 +43,13 @@ */ public interface ConnectorFactory { + /** + * Creates a connector for the specified channel and remote port. + * + * @param channel the logical channel index + * @param port the remote port to connect to + * @return the created connector + * @throws IOException if the connector cannot be created + */ public Connector createConnector( int channel, int port ) throws IOException; } diff --git a/jme3-networking/src/main/java/com/jme3/network/base/DefaultClient.java b/jme3-networking/src/main/java/com/jme3/network/base/DefaultClient.java index 2bb3d48031..7b04c4385e 100644 --- a/jme3-networking/src/main/java/com/jme3/network/base/DefaultClient.java +++ b/jme3-networking/src/main/java/com/jme3/network/base/DefaultClient.java @@ -86,6 +86,12 @@ public class DefaultClient implements Client private ClientServiceManager services; private MessageProtocol protocol = new SerializerMessageProtocol(); + /** + * Creates a client with the specified game name and protocol version. + * + * @param gameName the expected game name + * @param version the expected protocol version + */ public DefaultClient( String gameName, int version ) { this.gameName = gameName; @@ -94,6 +100,15 @@ public DefaultClient( String gameName, int version ) addStandardServices(); } + /** + * Creates a client with preconfigured reliable and optional fast connectors. + * + * @param gameName the expected game name + * @param version the expected protocol version + * @param reliable the reliable transport connector + * @param fast the optional fast transport connector + * @param connectorFactory the factory used for any additional channels + */ public DefaultClient( String gameName, int version, Connector reliable, Connector fast, ConnectorFactory connectorFactory ) { @@ -101,11 +116,21 @@ public DefaultClient( String gameName, int version, Connector reliable, Connecto setPrimaryConnectors( reliable, fast, connectorFactory ); } + /** + * Adds the default client services. + */ protected void addStandardServices() { log.fine("Adding standard services..."); services.addService(new ClientSerializerRegistrationsService()); } + /** + * Sets the primary transport connectors used by this client. + * + * @param reliable the reliable connector + * @param fast the optional fast connector + * @param connectorFactory the factory used for additional channels + */ protected void setPrimaryConnectors( Connector reliable, Connector fast, ConnectorFactory connectorFactory ) { if( reliable == null ) @@ -125,6 +150,9 @@ protected void setPrimaryConnectors( Connector reliable, Connector fast, Connect } } + /** + * Ensures the client has been started. + */ protected void checkRunning() { if( !isRunning ) @@ -188,6 +216,9 @@ public boolean isStarted() { return isRunning; } + /** + * Blocks until the client finishes connecting. + */ protected void waitForConnected() { if( isConnected() ) @@ -264,6 +295,13 @@ public void send( int channel, Message message ) send(channel + CH_FIRST, message, true); } + /** + * Sends a message over a specific internal channel. + * + * @param channel the internal channel index + * @param message the message to send + * @param waitForConnected true to wait until the client is connected first + */ protected void send( int channel, Message message, boolean waitForConnected ) { checkRunning(); @@ -301,6 +339,11 @@ public void close() closeConnections( null ); } + /** + * Closes all connectors and terminates client services. + * + * @param info optional disconnect information to report to listeners + */ protected void closeConnections( DisconnectInfo info ) { synchronized(this) { @@ -385,6 +428,9 @@ public void removeErrorListener( ErrorListener listener ) errorListeners.remove( listener ); } + /** + * Notifies registered state listeners that the client connected. + */ protected void fireConnected() { for( ClientStateListener l : stateListeners ) { @@ -392,6 +438,9 @@ protected void fireConnected() } } + /** + * Starts the client services after connection setup completes. + */ protected void startServices() { log.fine("Starting client services."); @@ -399,6 +448,11 @@ protected void startServices() services.start(); } + /** + * Notifies registered state listeners that the client disconnected. + * + * @param info optional disconnect information + */ protected void fireDisconnected( DisconnectInfo info ) { for( ClientStateListener l : stateListeners ) { @@ -409,6 +463,8 @@ protected void fireDisconnected( DisconnectInfo info ) /** * Either calls the ErrorListener or closes the connection * if there are no listeners. + * + * @param t the error to handle */ @SuppressWarnings("unchecked") protected void handleError( Throwable t ) @@ -429,6 +485,12 @@ protected void handleError( Throwable t ) } } + /** + * Configures any additional channels announced by the server. + * + * @param tempId the temporary client registration id + * @param ports the alternate channel ports announced by the server + */ protected void configureChannels( long tempId, int[] ports ) { try { @@ -452,6 +514,11 @@ protected void configureChannels( long tempId, int[] ports ) { } } + /** + * Dispatches a received message, handling connection-management messages internally. + * + * @param m the received message + */ protected void dispatch( Message m ) { if( log.isLoggable(Level.FINER) ) { @@ -503,8 +570,16 @@ protected void dispatch( Message m ) } } + /** + * Bridges connector callbacks back into this client instance. + */ protected class Redispatch implements MessageListener, ErrorListener { + /** + * Creates the redispatch bridge. + */ + protected Redispatch() { + } @Override public void messageReceived( Object source, Message m ) { diff --git a/jme3-networking/src/main/java/com/jme3/network/base/DefaultServer.java b/jme3-networking/src/main/java/com/jme3/network/base/DefaultServer.java index 1364e2b179..d74023eae2 100644 --- a/jme3-networking/src/main/java/com/jme3/network/base/DefaultServer.java +++ b/jme3-networking/src/main/java/com/jme3/network/base/DefaultServer.java @@ -91,6 +91,14 @@ public class DefaultServer implements Server private HostedServiceManager services; private MessageProtocol protocol = new SerializerMessageProtocol(); + /** + * Creates a server with the specified game name, version, and primary kernels. + * + * @param gameName the expected game name + * @param version the expected protocol version + * @param reliable the reliable kernel + * @param fast the optional fast kernel + */ public DefaultServer( String gameName, int version, Kernel reliable, Kernel fast ) { if( reliable == null ) @@ -109,6 +117,9 @@ public DefaultServer( String gameName, int version, Kernel reliable, Kernel fast } } + /** + * Adds the default hosted services. + */ protected void addStandardServices() { log.fine("Adding standard services..."); services.addService(new ServerSerializerRegistrationsService()); @@ -163,6 +174,11 @@ public int addChannel( int port ) } } + /** + * Validates an alternate server channel index. + * + * @param channel the channel index to validate + */ protected void checkChannel( int channel ) { if( channel < MessageConnection.CHANNEL_DEFAULT_RELIABLE @@ -326,6 +342,12 @@ public void removeMessageListener( MessageListener lis messageListeners.removeMessageListener( listener, classes ); } + /** + * Dispatches a received message to registered listeners. + * + * @param source the hosted connection that sent the message, or null + * @param m the received message + */ protected void dispatch( HostedConnection source, Message m ) { if( log.isLoggable(Level.FINER) ) { @@ -345,6 +367,11 @@ protected void dispatch( HostedConnection source, Message m ) } } + /** + * Notifies registered listeners that a connection was added. + * + * @param conn the added connection + */ protected void fireConnectionAdded( HostedConnection conn ) { for( ConnectionListener l : connectionListeners ) { @@ -352,6 +379,11 @@ protected void fireConnectionAdded( HostedConnection conn ) } } + /** + * Notifies registered listeners that a connection was removed. + * + * @param conn the removed connection + */ protected void fireConnectionRemoved( HostedConnection conn ) { for( ConnectionListener l : connectionListeners ) { @@ -359,11 +391,24 @@ protected void fireConnectionRemoved( HostedConnection conn ) } } + /** + * Returns the internal channel index for the specified adapter. + * + * @param ka the kernel adapter + * @return the adapter index + */ protected int getChannel( KernelAdapter ka ) { return channels.indexOf(ka); } + /** + * Registers or completes registration for a connecting client. + * + * @param ka the adapter that received the registration + * @param p the endpoint that sent the registration + * @param m the registration message + */ protected void registerClient( KernelAdapter ka, Endpoint p, ClientRegistrationMessage m ) { Connection addedConnection = null; @@ -457,11 +502,22 @@ protected void registerClient( KernelAdapter ka, Endpoint p, ClientRegistrationM } } + /** + * Resolves a hosted connection from an endpoint. + * + * @param endpoint the endpoint to resolve + * @return the hosted connection, or null if none is mapped + */ protected HostedConnection getConnection( Endpoint endpoint ) { return endpointConnections.get(endpoint); } + /** + * Removes partially connected state associated with the specified endpoint. + * + * @param p the endpoint to remove + */ protected void removeConnecting( Endpoint p ) { // No easy lookup for connecting Connections @@ -474,6 +530,11 @@ protected void removeConnecting( Endpoint p ) } } + /** + * Handles closure of an endpoint and removes any associated connection state. + * + * @param p the closed endpoint + */ protected void connectionClosed( Endpoint p ) { if( p.isConnected() ) { @@ -516,6 +577,9 @@ protected void connectionClosed( Endpoint p ) } } + /** + * Hosted connection implementation backed by one or more endpoints. + */ protected class Connection implements HostedConnection { private final int id; @@ -525,6 +589,11 @@ protected class Connection implements HostedConnection private final Map sessionData = new ConcurrentHashMap<>(); + /** + * Creates a hosted connection state holder. + * + * @param channelCount the number of endpoint slots to allocate + */ public Connection( int channelCount ) { id = nextId.getAndIncrement(); @@ -600,6 +669,9 @@ public void send( int channel, Message message ) channels[channel+CH_FIRST].send(buffer); } + /** + * Closes all endpoints associated with this hosted connection. + */ protected void closeConnection() { if( closed ) @@ -668,8 +740,16 @@ public String toString() } } + /** + * Bridges kernel adapter callbacks back into the server. + */ protected class Redispatch implements MessageListener { + /** + * Creates the redispatch bridge. + */ + protected Redispatch() { + } @Override public void messageReceived( HostedConnection source, Message m ) { @@ -677,10 +757,18 @@ public void messageReceived( HostedConnection source, Message m ) } } + /** + * Adapts hosted-connection filters to endpoint filters. + */ protected class FilterAdapter implements Filter { private final Filter delegate; + /** + * Creates a filter adapter. + * + * @param delegate the hosted-connection filter to delegate to + */ public FilterAdapter( Filter delegate ) { this.delegate = delegate; diff --git a/jme3-networking/src/main/java/com/jme3/network/base/KernelAdapter.java b/jme3-networking/src/main/java/com/jme3/network/base/KernelAdapter.java index 598858723d..3496ea0fbc 100644 --- a/jme3-networking/src/main/java/com/jme3/network/base/KernelAdapter.java +++ b/jme3-networking/src/main/java/com/jme3/network/base/KernelAdapter.java @@ -81,6 +81,15 @@ public class KernelAdapter extends Thread // through this connector. private boolean reliable; + /** + * Creates an adapter for a kernel used by {@link DefaultServer}. + * + * @param server the owning server + * @param kernel the kernel to wrap + * @param protocol the message protocol used to decode envelopes + * @param messageDispatcher the listener that receives decoded messages + * @param reliable true if this adapter represents a reliable channel + */ public KernelAdapter( DefaultServer server, Kernel kernel, MessageProtocol protocol, MessageListener messageDispatcher, boolean reliable ) { @@ -93,22 +102,43 @@ public KernelAdapter( DefaultServer server, Kernel kernel, MessageProtocol proto setDaemon(true); } + /** + * Returns the wrapped kernel. + * + * @return the wrapped kernel + */ public Kernel getKernel() { return kernel; } + /** + * Initializes the wrapped kernel. + */ public void initialize() { kernel.initialize(); } + /** + * Broadcasts raw bytes through the wrapped kernel. + * + * @param filter the endpoint filter, or null to target all endpoints + * @param data the bytes to broadcast + * @param reliable true to request reliable transport + * @param copy true to copy the buffer before dispatch + */ public void broadcast( Filter filter, ByteBuffer data, boolean reliable, boolean copy ) { kernel.broadcast( filter, data, reliable, copy ); } + /** + * Closes the adapter and terminates the wrapped kernel. + * + * @throws InterruptedException if interrupted while waiting for shutdown + */ public void close() throws InterruptedException { go.set(false); @@ -119,6 +149,13 @@ public void close() throws InterruptedException join(); } + /** + * Reports an adapter or kernel error and closes the endpoint when possible. + * + * @param p the endpoint involved in the failure + * @param context additional context for the failure + * @param e the error that occurred + */ protected void reportError( Endpoint p, Object context, Exception e ) { // Should really be queued up so the outer thread can @@ -131,11 +168,22 @@ protected void reportError( Endpoint p, Object context, Exception e ) } } + /** + * Resolves a hosted connection from an endpoint. + * + * @param p the endpoint to resolve + * @return the hosted connection, or null if none exists + */ protected HostedConnection getConnection( Endpoint p ) { return server.getConnection(p); } + /** + * Handles endpoint closure and clears any buffered message state. + * + * @param p the closed endpoint + */ protected void connectionClosed( Endpoint p ) { // Remove any message buffer we've been accumulating @@ -166,6 +214,9 @@ protected void connectionClosed( Endpoint p ) *

And that's why this note is here. DefaultServer does a rudimentary * per-connection locking but it couldn't possibly guard against * out of order Envelope processing.

+ * + * @param p the endpoint that sent the message + * @param m the decoded message */ protected void dispatch( Endpoint p, Message m ) { @@ -193,6 +244,12 @@ protected void dispatch( Endpoint p, Message m ) } } + /** + * Returns the message buffer used to accumulate bytes for an endpoint. + * + * @param p the endpoint supplying bytes + * @return the message buffer for that endpoint + */ protected MessageBuffer getMessageBuffer( Endpoint p ) { if( !reliable ) { @@ -213,6 +270,11 @@ protected MessageBuffer getMessageBuffer( Endpoint p ) } } + /** + * Decodes an envelope into messages and dispatches them. + * + * @param env the received envelope + */ protected void createAndDispatch( Envelope env ) { MessageBuffer protocol = getMessageBuffer(env.getSource()); @@ -244,6 +306,11 @@ protected void createAndDispatch( Envelope env ) } } + /** + * Handles a kernel endpoint event. + * + * @param event the endpoint event + */ protected void createAndDispatch( EndpointEvent event ) { // Only need to tell the server about disconnects @@ -252,6 +319,9 @@ protected void createAndDispatch( EndpointEvent event ) } } + /** + * Drains and processes all currently queued kernel events. + */ protected void flushEvents() { EndpointEvent event; @@ -298,5 +368,3 @@ public void run() } } - - diff --git a/jme3-networking/src/main/java/com/jme3/network/base/KernelFactory.java b/jme3-networking/src/main/java/com/jme3/network/base/KernelFactory.java index 6450190395..9fbeaef52d 100644 --- a/jme3-networking/src/main/java/com/jme3/network/base/KernelFactory.java +++ b/jme3-networking/src/main/java/com/jme3/network/base/KernelFactory.java @@ -44,7 +44,18 @@ */ public interface KernelFactory { + /** + * Default kernel factory implementation. + */ public static final KernelFactory DEFAULT = new NioKernelFactory(); + /** + * Creates a kernel for the specified channel and port. + * + * @param channel the logical channel index + * @param port the bound port + * @return the created kernel + * @throws IOException if the kernel cannot be created + */ public Kernel createKernel( int channel, int port ) throws IOException; } diff --git a/jme3-networking/src/main/java/com/jme3/network/base/MessageBuffer.java b/jme3-networking/src/main/java/com/jme3/network/base/MessageBuffer.java index 2e4ca4e380..ba01a3f4d1 100644 --- a/jme3-networking/src/main/java/com/jme3/network/base/MessageBuffer.java +++ b/jme3-networking/src/main/java/com/jme3/network/base/MessageBuffer.java @@ -48,18 +48,24 @@ public interface MessageBuffer { /** * Returns the next message in the buffer or null if there are no more * messages in the buffer. + * + * @return the next buffered message, or null if none are ready */ public Message pollMessage(); /** * Returns true if there is a message waiting in the buffer. + * + * @return true if a message can be polled immediately */ public boolean hasMessages(); /** * Adds byte data to the message buffer. Returns true if there is * a message waiting after this call. + * + * @param buffer the bytes to add + * @return true if a complete message is now available */ public boolean addBytes( ByteBuffer buffer ); } - diff --git a/jme3-networking/src/main/java/com/jme3/network/base/MessageListenerRegistry.java b/jme3-networking/src/main/java/com/jme3/network/base/MessageListenerRegistry.java index 4f75737e21..5ce251e33b 100644 --- a/jme3-networking/src/main/java/com/jme3/network/base/MessageListenerRegistry.java +++ b/jme3-networking/src/main/java/com/jme3/network/base/MessageListenerRegistry.java @@ -45,6 +45,7 @@ * Keeps track of message listeners registered to specific * types or to any type. * + * @param the message source type * @version $Revision$ * @author Paul Speed */ @@ -56,6 +57,9 @@ public class MessageListenerRegistry implements MessageListener private final Map>> typeListeners = new ConcurrentHashMap<>(); + /** + * Creates an empty listener registry. + */ public MessageListenerRegistry() { } @@ -87,6 +91,13 @@ public void messageReceived( S source, Message m ) } } + /** + * Returns the listeners registered for a specific message class. + * + * @param c the message class + * @param create true to create a listener list when absent + * @return the listeners registered for that class + */ protected List> getListeners( Class c, boolean create ) { List> result = typeListeners.get(c); @@ -101,6 +112,11 @@ protected List> getListeners( Class c, boolean create return result; } + /** + * Adds a wildcard listener that receives all messages. + * + * @param listener the listener to add + */ public void addMessageListener( MessageListener listener ) { if( listener == null ) @@ -108,11 +124,22 @@ public void addMessageListener( MessageListener listener ) listeners.add(listener); } + /** + * Removes a wildcard listener. + * + * @param listener the listener to remove + */ public void removeMessageListener( MessageListener listener ) { listeners.remove(listener); } + /** + * Adds a listener for the specified message classes. + * + * @param listener the listener to add + * @param classes the message classes to listen for + */ public void addMessageListener( MessageListener listener, Class... classes ) { if( listener == null ) @@ -122,6 +149,12 @@ public void addMessageListener( MessageListener listener, Class... cl } } + /** + * Removes a listener from the specified message classes. + * + * @param listener the listener to remove + * @param classes the message classes to unregister + */ public void removeMessageListener( MessageListener listener, Class... classes ) { for( Class c : classes ) { diff --git a/jme3-networking/src/main/java/com/jme3/network/base/MessageProtocol.java b/jme3-networking/src/main/java/com/jme3/network/base/MessageProtocol.java index 74aad907cb..f0bc0fd37a 100644 --- a/jme3-networking/src/main/java/com/jme3/network/base/MessageProtocol.java +++ b/jme3-networking/src/main/java/com/jme3/network/base/MessageProtocol.java @@ -48,10 +48,27 @@ * @author Paul Speed */ public interface MessageProtocol { + /** + * Serializes a message into a byte buffer. + * + * @param message the message to serialize + * @param target the optional target buffer to reuse + * @return a buffer containing the serialized message + */ public ByteBuffer toByteBuffer( Message message, ByteBuffer target ); + /** + * Deserializes a message from a byte buffer. + * + * @param bytes the serialized message bytes + * @return the decoded message + */ public Message toMessage( ByteBuffer bytes ); + /** + * Creates a rolling message buffer compatible with this protocol. + * + * @return a new message buffer + */ public MessageBuffer createBuffer(); } - diff --git a/jme3-networking/src/main/java/com/jme3/network/base/NioKernelFactory.java b/jme3-networking/src/main/java/com/jme3/network/base/NioKernelFactory.java index 6f1a552c6b..b998c490ec 100644 --- a/jme3-networking/src/main/java/com/jme3/network/base/NioKernelFactory.java +++ b/jme3-networking/src/main/java/com/jme3/network/base/NioKernelFactory.java @@ -45,6 +45,12 @@ */ public class NioKernelFactory implements KernelFactory { + /** + * Creates a TCP NIO kernel factory. + */ + public NioKernelFactory() { + } + @Override public Kernel createKernel( int channel, int port ) throws IOException { diff --git a/jme3-networking/src/main/java/com/jme3/network/base/TcpConnectorFactory.java b/jme3-networking/src/main/java/com/jme3/network/base/TcpConnectorFactory.java index 5a952e040c..f17d14b403 100644 --- a/jme3-networking/src/main/java/com/jme3/network/base/TcpConnectorFactory.java +++ b/jme3-networking/src/main/java/com/jme3/network/base/TcpConnectorFactory.java @@ -47,6 +47,11 @@ public class TcpConnectorFactory implements ConnectorFactory { private InetAddress remoteAddress; + /** + * Creates a factory that connects to the specified remote address. + * + * @param remoteAddress the remote address for created TCP connectors + */ public TcpConnectorFactory( InetAddress remoteAddress ) { this.remoteAddress = remoteAddress; diff --git a/jme3-networking/src/main/java/com/jme3/network/base/protocol/GreedyMessageBuffer.java b/jme3-networking/src/main/java/com/jme3/network/base/protocol/GreedyMessageBuffer.java index 0bdbf6f328..6954882574 100644 --- a/jme3-networking/src/main/java/com/jme3/network/base/protocol/GreedyMessageBuffer.java +++ b/jme3-networking/src/main/java/com/jme3/network/base/protocol/GreedyMessageBuffer.java @@ -60,6 +60,11 @@ public class GreedyMessageBuffer implements MessageBuffer { private int size; private Byte carry; + /** + * Creates a greedy message buffer for the specified protocol. + * + * @param protocol the protocol used to deserialize complete messages + */ public GreedyMessageBuffer( MessageProtocol protocol ) { this.protocol = protocol; } @@ -156,4 +161,3 @@ else if( buffer.remaining() < 2 ) { } } - diff --git a/jme3-networking/src/main/java/com/jme3/network/base/protocol/LazyMessageBuffer.java b/jme3-networking/src/main/java/com/jme3/network/base/protocol/LazyMessageBuffer.java index a52799aac6..a51569e9b1 100644 --- a/jme3-networking/src/main/java/com/jme3/network/base/protocol/LazyMessageBuffer.java +++ b/jme3-networking/src/main/java/com/jme3/network/base/protocol/LazyMessageBuffer.java @@ -57,6 +57,11 @@ public class LazyMessageBuffer implements MessageBuffer { private int size; private Byte carry; + /** + * Creates a lazy message buffer for the specified protocol. + * + * @param protocol the protocol used to deserialize buffered messages + */ public LazyMessageBuffer( MessageProtocol protocol ) { this.protocol = protocol; } @@ -174,4 +179,3 @@ else if( buffer.remaining() < 2 ) { } } - diff --git a/jme3-networking/src/main/java/com/jme3/network/base/protocol/SerializerMessageProtocol.java b/jme3-networking/src/main/java/com/jme3/network/base/protocol/SerializerMessageProtocol.java index 1d3cee2cc6..e20fcfd979 100644 --- a/jme3-networking/src/main/java/com/jme3/network/base/protocol/SerializerMessageProtocol.java +++ b/jme3-networking/src/main/java/com/jme3/network/base/protocol/SerializerMessageProtocol.java @@ -51,6 +51,9 @@ */ public class SerializerMessageProtocol implements MessageProtocol { + /** + * Creates a serializer-backed message protocol. + */ public SerializerMessageProtocol() { } @@ -101,4 +104,3 @@ public MessageBuffer createBuffer() { } - diff --git a/jme3-networking/src/main/java/com/jme3/network/kernel/AbstractKernel.java b/jme3-networking/src/main/java/com/jme3/network/kernel/AbstractKernel.java index d953b972d4..576dd94fd5 100644 --- a/jme3-networking/src/main/java/com/jme3/network/kernel/AbstractKernel.java +++ b/jme3-networking/src/main/java/com/jme3/network/kernel/AbstractKernel.java @@ -65,10 +65,18 @@ public abstract class AbstractKernel implements Kernel */ private LinkedBlockingQueue envelopes = new LinkedBlockingQueue<>(); + /** + * Creates a kernel base with empty event and envelope queues. + */ protected AbstractKernel() { } + /** + * Reports an internal kernel error. + * + * @param e the error to report + */ protected void reportError( Exception e ) { // Should really be queued up so the outer thread can @@ -76,6 +84,9 @@ protected void reportError( Exception e ) log.log( Level.SEVERE, "Unhandled kernel error", e ); } + /** + * Wakes a waiting reader by enqueueing the {@link #EVENTS_PENDING} marker if needed. + */ protected void wakeupReader() { // If there are no pending messages then add one so that the // kernel-user knows to wake up if it is only listening for @@ -88,6 +99,11 @@ protected void wakeupReader() { } } + /** + * Returns the next unique endpoint identifier. + * + * @return the next endpoint id + */ protected long nextEndpointId() { return nextId.getAndIncrement(); @@ -122,11 +138,21 @@ public EndpointEvent nextEvent() return endpointEvents.poll(); } + /** + * Adds an endpoint event to the pending event queue. + * + * @param e the event to enqueue + */ protected void addEvent( EndpointEvent e ) { endpointEvents.add( e ); } + /** + * Adds an envelope to the pending message queue. + * + * @param env the envelope to enqueue + */ protected void addEnvelope( Envelope env ) { if( !envelopes.offer( env ) ) { diff --git a/jme3-networking/src/main/java/com/jme3/network/kernel/Connector.java b/jme3-networking/src/main/java/com/jme3/network/kernel/Connector.java index cc6fc3f315..11ad954607 100644 --- a/jme3-networking/src/main/java/com/jme3/network/kernel/Connector.java +++ b/jme3-networking/src/main/java/com/jme3/network/kernel/Connector.java @@ -46,6 +46,8 @@ public interface Connector { /** * Returns true if this connector is currently connected. + * + * @return true if the connector is connected */ public boolean isConnected(); @@ -60,6 +62,8 @@ public interface Connector * reading. Some connector implementations may not be able * to answer this question accurately and will always return * false. + * + * @return true if data may be available to read without blocking */ public boolean available(); @@ -77,6 +81,8 @@ public interface Connector /** * Writes a chunk of data to the connection from data.position() * to data.limit(). + * + * @param data the bytes to write */ public void write( ByteBuffer data ); } diff --git a/jme3-networking/src/main/java/com/jme3/network/kernel/ConnectorException.java b/jme3-networking/src/main/java/com/jme3/network/kernel/ConnectorException.java index 7c55a4eeaa..c17d20cab3 100644 --- a/jme3-networking/src/main/java/com/jme3/network/kernel/ConnectorException.java +++ b/jme3-networking/src/main/java/com/jme3/network/kernel/ConnectorException.java @@ -41,11 +41,22 @@ */ public class ConnectorException extends RuntimeException { + /** + * Creates a connector exception with a message and cause. + * + * @param message the exception message + * @param cause the underlying cause + */ public ConnectorException( String message, Throwable cause ) { super( message, cause ); } + /** + * Creates a connector exception with a message. + * + * @param message the exception message + */ public ConnectorException( String message ) { super( message ); diff --git a/jme3-networking/src/main/java/com/jme3/network/kernel/Endpoint.java b/jme3-networking/src/main/java/com/jme3/network/kernel/Endpoint.java index e05859daaa..41a138361b 100644 --- a/jme3-networking/src/main/java/com/jme3/network/kernel/Endpoint.java +++ b/jme3-networking/src/main/java/com/jme3/network/kernel/Endpoint.java @@ -45,6 +45,8 @@ public interface Endpoint /** * Returns an ID that is unique for this endpoint within its * Kernel instance. + * + * @return the endpoint id */ public long getId(); @@ -52,22 +54,30 @@ public interface Endpoint * Returns the transport specific remote address of this endpoint * as a string. This may or may not be unique per endpoint depending * on the type of transport. + * + * @return the remote address string */ public String getAddress(); /** * Returns the kernel to which this endpoint belongs. + * + * @return the owning kernel */ public Kernel getKernel(); /** * Returns true if this endpoint is currently connected. + * + * @return true if the endpoint is connected */ public boolean isConnected(); /** * Sends data to the other end of the connection represented * by this endpoint. + * + * @param data the bytes to send */ public void send( ByteBuffer data ); @@ -82,6 +92,8 @@ public interface Endpoint * data before closing. As soon as this method is called, * new send() calls will fail with an exception... even while * close() is still flushing the earlier queued messages. + * + * @param flushData true to flush queued data before closing */ public void close(boolean flushData); } diff --git a/jme3-networking/src/main/java/com/jme3/network/kernel/EndpointEvent.java b/jme3-networking/src/main/java/com/jme3/network/kernel/EndpointEvent.java index 86599da771..53cc164484 100644 --- a/jme3-networking/src/main/java/com/jme3/network/kernel/EndpointEvent.java +++ b/jme3-networking/src/main/java/com/jme3/network/kernel/EndpointEvent.java @@ -41,12 +41,27 @@ */ public class EndpointEvent { - public enum Type { ADD, REMOVE }; + /** + * Enumerates the supported endpoint event types. + */ + public enum Type { + /** Endpoint added. */ + ADD, + /** Endpoint removed. */ + REMOVE + }; private Kernel source; private Endpoint endpoint; private Type type; + /** + * Creates an endpoint event. + * + * @param source the kernel that produced the event + * @param p the endpoint involved in the event + * @param type the event type + */ public EndpointEvent( Kernel source, Endpoint p, Type type ) { this.source = source; @@ -54,26 +69,55 @@ public EndpointEvent( Kernel source, Endpoint p, Type type ) this.type = type; } + /** + * Creates an endpoint-added event. + * + * @param source the kernel that produced the event + * @param p the added endpoint + * @return the created event + */ public static EndpointEvent createAdd( Kernel source, Endpoint p ) { return new EndpointEvent( source, p, Type.ADD ); } + /** + * Creates an endpoint-removed event. + * + * @param source the kernel that produced the event + * @param p the removed endpoint + * @return the created event + */ public static EndpointEvent createRemove( Kernel source, Endpoint p ) { return new EndpointEvent( source, p, Type.REMOVE ); } + /** + * Returns the kernel that produced the event. + * + * @return the source kernel + */ public Kernel getSource() { return source; } + /** + * Returns the endpoint involved in the event. + * + * @return the event endpoint + */ public Endpoint getEndpoint() { return endpoint; } + /** + * Returns the event type. + * + * @return the event type + */ public Type getType() { return type; diff --git a/jme3-networking/src/main/java/com/jme3/network/kernel/Envelope.java b/jme3-networking/src/main/java/com/jme3/network/kernel/Envelope.java index 3739c86118..1df5c9f718 100644 --- a/jme3-networking/src/main/java/com/jme3/network/kernel/Envelope.java +++ b/jme3-networking/src/main/java/com/jme3/network/kernel/Envelope.java @@ -48,6 +48,10 @@ public class Envelope * Creates an incoming envelope holding the data from the specified * source. The 'reliable' flag further indicates on which mode of * transport the data arrived. + * + * @param source the endpoint that produced the data + * @param data the received bytes + * @param reliable true if the data arrived over a reliable transport */ public Envelope( Endpoint source, byte[] data, boolean reliable ) { @@ -56,16 +60,31 @@ public Envelope( Endpoint source, byte[] data, boolean reliable ) this.reliable = reliable; } + /** + * Returns the endpoint that produced the data. + * + * @return the source endpoint + */ public Endpoint getSource() { return source; } + /** + * Returns the received bytes. + * + * @return the received data + */ public byte[] getData() { return data; } + /** + * Returns whether the data arrived over a reliable transport. + * + * @return true if the envelope is reliable + */ public boolean isReliable() { return reliable; diff --git a/jme3-networking/src/main/java/com/jme3/network/kernel/Kernel.java b/jme3-networking/src/main/java/com/jme3/network/kernel/Kernel.java index 97362c5847..1c54489a85 100644 --- a/jme3-networking/src/main/java/com/jme3/network/kernel/Kernel.java +++ b/jme3-networking/src/main/java/com/jme3/network/kernel/Kernel.java @@ -59,6 +59,8 @@ public interface Kernel * Gracefully terminates the kernel and stops any internal * daemon processing. This method will not return until all * internal threads have been shut down. + * + * @throws InterruptedException if the calling thread is interrupted while waiting */ public void terminate() throws InterruptedException; @@ -70,24 +72,36 @@ public interface Kernel * the data buffer. Though it is important that the buffer not be changed * by another thread while this call is running. * Only the bytes from data.position() to data.remaining() are sent. + * + * @param filter the endpoint filter used to select recipients + * @param data the payload to send + * @param reliable true to use reliable transport semantics + * @param copy true to copy the buffer before dispatching it */ public void broadcast( Filter filter, ByteBuffer data, boolean reliable, boolean copy ); /** * Returns true if there are waiting envelopes. + * + * @return true if at least one envelope is queued */ public boolean hasEnvelopes(); /** * Removes one envelope from the received messages queue or * blocks until one is available. + * + * @return the next queued envelope + * @throws InterruptedException if interrupted while waiting for an envelope */ public Envelope read() throws InterruptedException; /** * Removes and returns one endpoint event from the event queue or * null if there are no endpoint events. + * + * @return the next endpoint event, or null if none are queued */ public EndpointEvent nextEvent(); } diff --git a/jme3-networking/src/main/java/com/jme3/network/kernel/KernelException.java b/jme3-networking/src/main/java/com/jme3/network/kernel/KernelException.java index d000d2a722..0693a22ced 100644 --- a/jme3-networking/src/main/java/com/jme3/network/kernel/KernelException.java +++ b/jme3-networking/src/main/java/com/jme3/network/kernel/KernelException.java @@ -41,11 +41,22 @@ */ public class KernelException extends RuntimeException { + /** + * Creates a kernel exception with a message and cause. + * + * @param message the exception message + * @param cause the underlying cause + */ public KernelException( String message, Throwable cause ) { super( message, cause ); } + /** + * Creates a kernel exception with a message. + * + * @param message the exception message + */ public KernelException( String message ) { super( message ); diff --git a/jme3-networking/src/main/java/com/jme3/network/kernel/NamedThreadFactory.java b/jme3-networking/src/main/java/com/jme3/network/kernel/NamedThreadFactory.java index efc055d633..84e0e0aac0 100644 --- a/jme3-networking/src/main/java/com/jme3/network/kernel/NamedThreadFactory.java +++ b/jme3-networking/src/main/java/com/jme3/network/kernel/NamedThreadFactory.java @@ -48,21 +48,45 @@ public class NamedThreadFactory implements ThreadFactory private boolean daemon; private ThreadFactory delegate; + /** + * Creates a named thread factory using the default thread factory. + * + * @param name the thread name prefix + */ public NamedThreadFactory( String name ) { this( name, Executors.defaultThreadFactory() ); } + /** + * Creates a named thread factory using the default thread factory. + * + * @param name the thread name prefix + * @param daemon true to mark created threads as daemon threads + */ public NamedThreadFactory( String name, boolean daemon ) { this( name, daemon, Executors.defaultThreadFactory() ); } + /** + * Creates a named thread factory that wraps another thread factory. + * + * @param name the thread name prefix + * @param delegate the wrapped thread factory + */ public NamedThreadFactory( String name, ThreadFactory delegate ) { this( name, false, delegate ); } + /** + * Creates a named thread factory that wraps another thread factory. + * + * @param name the thread name prefix + * @param daemon true to mark created threads as daemon threads + * @param delegate the wrapped thread factory + */ public NamedThreadFactory( String name, boolean daemon, ThreadFactory delegate ) { this.name = name; @@ -80,4 +104,3 @@ public Thread newThread( Runnable r ) return result; } } - diff --git a/jme3-networking/src/main/java/com/jme3/network/kernel/tcp/NioEndpoint.java b/jme3-networking/src/main/java/com/jme3/network/kernel/tcp/NioEndpoint.java index b124bf7572..1b1724ef22 100644 --- a/jme3-networking/src/main/java/com/jme3/network/kernel/tcp/NioEndpoint.java +++ b/jme3-networking/src/main/java/com/jme3/network/kernel/tcp/NioEndpoint.java @@ -50,6 +50,9 @@ */ public class NioEndpoint implements Endpoint { + /** + * Marker queued to request endpoint closure after pending writes flush. + */ protected static final ByteBuffer CLOSE_MARKER = ByteBuffer.allocate(0); private long id; @@ -58,6 +61,13 @@ public class NioEndpoint implements Endpoint private ConcurrentLinkedQueue outbound = new ConcurrentLinkedQueue<>(); private boolean closing = false; + /** + * Creates an endpoint backed by a socket channel. + * + * @param kernel the owning selector kernel + * @param id the endpoint id + * @param socket the socket channel + */ public NioEndpoint( SelectorKernel kernel, long id, SocketChannel socket ) { this.id = id; @@ -122,6 +132,10 @@ public boolean isConnected() * The wakeup option is used internally when the kernel is * broadcasting out to a bunch of endpoints and doesn't want to * necessarily wakeup right away. + * + * @param data the bytes to queue + * @param copy true to copy the provided buffer + * @param wakeup true to wake the selector after enqueueing */ protected void send( ByteBuffer data, boolean copy, boolean wakeup ) { @@ -148,6 +162,8 @@ protected void send( ByteBuffer data, boolean copy, boolean wakeup ) /** * Called by the SelectorKernel to get the current top * buffer for writing. + * + * @return the current pending buffer, or null if none are queued */ protected ByteBuffer peekPending() { @@ -157,12 +173,19 @@ protected ByteBuffer peekPending() /** * Called by the SelectorKernel when the top buffer * has been exhausted. + * + * @return the removed pending buffer, or null if none are queued */ protected ByteBuffer removePending() { return outbound.poll(); } + /** + * Returns true if outbound data is queued for this endpoint. + * + * @return true if pending outbound data exists + */ protected boolean hasPending() { return !outbound.isEmpty(); diff --git a/jme3-networking/src/main/java/com/jme3/network/kernel/tcp/SelectorKernel.java b/jme3-networking/src/main/java/com/jme3/network/kernel/tcp/SelectorKernel.java index 50c432310e..c9f21a6a5f 100644 --- a/jme3-networking/src/main/java/com/jme3/network/kernel/tcp/SelectorKernel.java +++ b/jme3-networking/src/main/java/com/jme3/network/kernel/tcp/SelectorKernel.java @@ -63,21 +63,43 @@ public class SelectorKernel extends AbstractKernel private Map endpoints = new ConcurrentHashMap<>(); + /** + * Creates a selector kernel for the specified host and port. + * + * @param host the local bind address + * @param port the local bind port + */ public SelectorKernel( InetAddress host, int port ) { this( new InetSocketAddress(host, port) ); } + /** + * Creates a selector kernel bound to the specified port on the wildcard address. + * + * @param port the local bind port + * @throws IOException if the address cannot be prepared + */ public SelectorKernel( int port ) throws IOException { this( new InetSocketAddress(port) ); } + /** + * Creates a selector kernel for the specified socket address. + * + * @param address the local socket address + */ public SelectorKernel( InetSocketAddress address ) { this.address = address; } + /** + * Creates the selector thread implementation used by this kernel. + * + * @return the selector thread + */ protected SelectorThread createSelectorThread() { return new SelectorThread(); @@ -147,6 +169,12 @@ public void broadcast( Filter filter, ByteBuffer data, boolean wakeupSelector(); } + /** + * Creates and registers a new endpoint for the accepted channel. + * + * @param c the accepted socket channel + * @return the created endpoint + */ protected NioEndpoint addEndpoint( SocketChannel c ) { // Note: we purposely do NOT put the key in the endpoint. @@ -162,6 +190,12 @@ protected NioEndpoint addEndpoint( SocketChannel c ) return p; } + /** + * Removes bookkeeping for a closed endpoint. + * + * @param p the endpoint being removed + * @param c the underlying socket channel + */ protected void removeEndpoint( NioEndpoint p, SocketChannel c ) { endpoints.remove( p.getId() ); @@ -175,6 +209,9 @@ protected void removeEndpoint( NioEndpoint p, SocketChannel c ) /** * Called by the endpoints when they need to be closed. + * + * @param p the endpoint to close + * @throws IOException if the endpoint cannot be closed cleanly */ protected void closeEndpoint( NioEndpoint p ) throws IOException { @@ -192,6 +229,14 @@ protected void wakeupSelector() thread.wakeupSelector(); } + /** + * Queues newly read endpoint data as an envelope. + * + * @param p the source endpoint + * @param c the source socket channel + * @param shared the shared read buffer + * @param size the number of valid bytes in {@code shared} + */ protected void newData( NioEndpoint p, SocketChannel c, ByteBuffer shared, int size ) { // Note: if ever desirable, it would be possible to accumulate @@ -229,12 +274,20 @@ protected class SelectorThread extends Thread */ private Map endpointKeys = new ConcurrentHashMap<>(); + /** + * Creates the selector thread. + */ public SelectorThread() { setName( "Selector@" + address ); setDaemon(true); } + /** + * Opens and binds the selector infrastructure. + * + * @throws IOException if the selector or socket cannot be opened + */ public void connect() throws IOException { // Create a new selector @@ -254,6 +307,12 @@ public void connect() throws IOException log.log( Level.FINE, "Hosting TCP connection:{0}.", address ); } + /** + * Stops the selector thread and closes its resources. + * + * @throws IOException if socket shutdown fails + * @throws InterruptedException if interrupted while waiting for shutdown + */ public void close() throws IOException, InterruptedException { // Set the thread to stop @@ -269,11 +328,17 @@ public void close() throws IOException, InterruptedException join(); } + /** + * Wakes the selector if it is blocked in {@link #select()}. + */ protected void wakeupSelector() { selector.wakeup(); } + /** + * Recomputes selector interest ops for endpoints with pending output. + */ protected void setupSelectorOptions() { // For now, selection keys will either be in OP_READ @@ -294,6 +359,12 @@ protected void setupSelectorOptions() } } + /** + * Accepts a new incoming TCP connection. + * + * @param key the selected accept key + * @throws IOException if the connection cannot be accepted or configured + */ protected void accept( SelectionKey key ) throws IOException { // Would only get accepts on a server channel @@ -318,6 +389,12 @@ protected void accept( SelectionKey key ) throws IOException endpointKeys.put(p, endKey); } + /** + * Cancels and closes the specified endpoint. + * + * @param p the endpoint to cancel + * @throws IOException if closing the channel fails + */ protected void cancel( NioEndpoint p ) throws IOException { SelectionKey key = endpointKeys.remove(p); @@ -338,6 +415,13 @@ protected void cancel( NioEndpoint p ) throws IOException removeEndpoint( p, c ); } + /** + * Cancels and closes the specified selection key and channel. + * + * @param key the key to cancel + * @param c the channel to close + * @throws IOException if closing the channel fails + */ protected void cancel( SelectionKey key, SocketChannel c ) throws IOException { NioEndpoint p = (NioEndpoint)key.attachment(); @@ -351,6 +435,12 @@ protected void cancel( SelectionKey key, SocketChannel c ) throws IOException removeEndpoint( p, c ); } + /** + * Reads pending bytes from a readable channel. + * + * @param key the readable key + * @throws IOException if the read fails + */ protected void read( SelectionKey key ) throws IOException { NioEndpoint p = (NioEndpoint)key.attachment(); @@ -377,6 +467,12 @@ protected void read( SelectionKey key ) throws IOException newData( p, c, working, size ); } + /** + * Flushes pending endpoint data to a writable channel. + * + * @param key the writable key + * @throws IOException if writing fails + */ protected void write( SelectionKey key ) throws IOException { NioEndpoint p = (NioEndpoint)key.attachment(); @@ -406,6 +502,11 @@ protected void write( SelectionKey key ) throws IOException } } + /** + * Waits for and dispatches selector activity. + * + * @throws IOException if selector processing fails + */ protected void select() throws IOException { selector.select(); diff --git a/jme3-networking/src/main/java/com/jme3/network/kernel/tcp/SocketConnector.java b/jme3-networking/src/main/java/com/jme3/network/kernel/tcp/SocketConnector.java index be4682bd9e..7360687c06 100644 --- a/jme3-networking/src/main/java/com/jme3/network/kernel/tcp/SocketConnector.java +++ b/jme3-networking/src/main/java/com/jme3/network/kernel/tcp/SocketConnector.java @@ -60,6 +60,13 @@ public class SocketConnector implements Connector private byte[] buffer = new byte[65535]; private AtomicBoolean connected = new AtomicBoolean(false); + /** + * Creates a TCP connector to the specified remote address. + * + * @param address the remote address + * @param port the remote port + * @throws IOException if the socket cannot be opened + */ public SocketConnector( InetAddress address, int port ) throws IOException { this.sock = new Socket(address, port); @@ -75,6 +82,9 @@ public SocketConnector( InetAddress address, int port ) throws IOException connected.set(true); } + /** + * Ensures the connector has not been closed. + */ protected void checkClosed() { if( sock == null ) diff --git a/jme3-networking/src/main/java/com/jme3/network/kernel/udp/UdpConnector.java b/jme3-networking/src/main/java/com/jme3/network/kernel/udp/UdpConnector.java index 642b9d7815..28752a4132 100644 --- a/jme3-networking/src/main/java/com/jme3/network/kernel/udp/UdpConnector.java +++ b/jme3-networking/src/main/java/com/jme3/network/kernel/udp/UdpConnector.java @@ -56,6 +56,10 @@ public class UdpConnector implements Connector /** * Creates a new UDP connection that send datagrams to the * specified address and port. + * + * @param remote the remote address + * @param remotePort the remote port + * @throws IOException if the socket cannot be opened */ public UdpConnector( InetAddress remote, int remotePort ) throws IOException { @@ -69,6 +73,9 @@ public UdpConnector( InetAddress remote, int remotePort ) throws IOException connected.set(true); } + /** + * Ensures the connector has not been closed. + */ protected void checkClosed() { if( sock == null ) @@ -139,4 +146,3 @@ public void write( ByteBuffer data ) } } } - diff --git a/jme3-networking/src/main/java/com/jme3/network/kernel/udp/UdpEndpoint.java b/jme3-networking/src/main/java/com/jme3/network/kernel/udp/UdpEndpoint.java index a88833da3a..327b93776d 100644 --- a/jme3-networking/src/main/java/com/jme3/network/kernel/udp/UdpEndpoint.java +++ b/jme3-networking/src/main/java/com/jme3/network/kernel/udp/UdpEndpoint.java @@ -58,6 +58,14 @@ public class UdpEndpoint implements Endpoint private UdpKernel kernel; private boolean connected = true; // it's connectionless but we track logical state + /** + * Creates a UDP endpoint. + * + * @param kernel the owning kernel + * @param id the endpoint id + * @param address the remote socket address + * @param socket the datagram socket used for replies + */ public UdpEndpoint( UdpKernel kernel, long id, SocketAddress address, DatagramSocket socket ) { this.id = id; @@ -72,6 +80,11 @@ public Kernel getKernel() return kernel; } + /** + * Returns the remote socket address for this endpoint. + * + * @return the remote socket address + */ protected SocketAddress getRemoteAddress() { return address; diff --git a/jme3-networking/src/main/java/com/jme3/network/kernel/udp/UdpKernel.java b/jme3-networking/src/main/java/com/jme3/network/kernel/udp/UdpKernel.java index 2f9ac14a18..b255346154 100644 --- a/jme3-networking/src/main/java/com/jme3/network/kernel/udp/UdpKernel.java +++ b/jme3-networking/src/main/java/com/jme3/network/kernel/udp/UdpKernel.java @@ -64,21 +64,43 @@ public class UdpKernel extends AbstractKernel // can't really be NAT'ed. private Map socketEndpoints = new ConcurrentHashMap<>(); + /** + * Creates a UDP kernel for the specified host and port. + * + * @param host the local bind address + * @param port the local bind port + */ public UdpKernel( InetAddress host, int port ) { this( new InetSocketAddress(host, port) ); } + /** + * Creates a UDP kernel bound to the specified port on the wildcard address. + * + * @param port the local bind port + * @throws IOException if the address cannot be prepared + */ public UdpKernel( int port ) throws IOException { this( new InetSocketAddress(port) ); } + /** + * Creates a UDP kernel for the specified socket address. + * + * @param address the local socket address + */ public UdpKernel( InetSocketAddress address ) { this.address = address; } + /** + * Creates the host thread implementation used by this kernel. + * + * @return the host thread + */ protected HostThread createHostThread() { return new HostThread(); @@ -149,6 +171,13 @@ public void broadcast( Filter filter, ByteBuffer data, boolean } } + /** + * Returns the endpoint for the specified socket address, optionally creating it. + * + * @param address the remote socket address + * @param create true to create the endpoint if missing + * @return the existing or newly created endpoint + */ protected Endpoint getEndpoint( SocketAddress address, boolean create ) { UdpEndpoint p = socketEndpoints.get(address); @@ -164,6 +193,9 @@ protected Endpoint getEndpoint( SocketAddress address, boolean create ) /** * Called by the endpoints when they need to be closed. + * + * @param p the endpoint to close + * @throws IOException if cleanup fails */ protected void closeEndpoint( UdpEndpoint p ) throws IOException { @@ -179,6 +211,11 @@ protected void closeEndpoint( UdpEndpoint p ) throws IOException wakeupReader(); } + /** + * Queues newly received datagram data as an envelope. + * + * @param packet the received packet + */ protected void newData( DatagramPacket packet ) { // So the tricky part here is figuring out the endpoint and @@ -196,16 +233,31 @@ protected void newData( DatagramPacket packet ) addEnvelope( env ); } + /** + * Queues a datagram for asynchronous sending. + * + * @param endpoint the source endpoint + * @param packet the packet to send + */ protected void enqueueWrite( Endpoint endpoint, DatagramPacket packet ) { writer.execute( new MessageWriter(endpoint, packet) ); } + /** + * Writes queued UDP packets on behalf of endpoints. + */ protected class MessageWriter implements Runnable { private Endpoint endpoint; private DatagramPacket packet; + /** + * Creates a queued UDP packet writer. + * + * @param endpoint the source endpoint + * @param packet the packet to send + */ public MessageWriter( Endpoint endpoint, DatagramPacket packet ) { this.endpoint = endpoint; @@ -231,6 +283,9 @@ public void run() } } + /** + * Host thread that receives UDP packets for this kernel. + */ protected class HostThread extends Thread { private DatagramSocket socket; @@ -238,23 +293,42 @@ protected class HostThread extends Thread private byte[] buffer = new byte[65535]; // slightly bigger than needed. + /** + * Creates the host thread. + */ public HostThread() { setName( "UDP Host@" + address ); setDaemon(true); } + /** + * Returns the datagram socket used by the host thread. + * + * @return the datagram socket + */ protected DatagramSocket getSocket() { return socket; } + /** + * Opens and binds the host datagram socket. + * + * @throws IOException if the socket cannot be opened + */ public void connect() throws IOException { socket = new DatagramSocket( address ); log.log( Level.FINE, "Hosting UDP connection:{0}.", address ); } + /** + * Stops the host thread and closes its socket. + * + * @throws IOException if socket shutdown fails + * @throws InterruptedException if interrupted while waiting for shutdown + */ public void close() throws IOException, InterruptedException { // Set the thread to stop diff --git a/jme3-networking/src/main/java/com/jme3/network/message/ChannelInfoMessage.java b/jme3-networking/src/main/java/com/jme3/network/message/ChannelInfoMessage.java index 231fe19ff6..2211fea03e 100644 --- a/jme3-networking/src/main/java/com/jme3/network/message/ChannelInfoMessage.java +++ b/jme3-networking/src/main/java/com/jme3/network/message/ChannelInfoMessage.java @@ -46,10 +46,19 @@ public class ChannelInfoMessage extends AbstractMessage { private long id; private int[] ports; + /** + * Creates an empty channel info message for serialization. + */ public ChannelInfoMessage() { super( true ); } + /** + * Creates a message describing the server id and extra ports. + * + * @param id the server identifier + * @param ports the additional ports exposed by the server + */ public ChannelInfoMessage( long id, List ports ) { super( true ); this.id = id; @@ -59,10 +68,20 @@ public ChannelInfoMessage( long id, List ports ) { } } + /** + * Returns the server identifier associated with this message. + * + * @return the server identifier + */ public long getId() { return id; } + /** + * Returns the extra ports advertised by the server. + * + * @return the advertised ports + */ public int[] getPorts() { return ports; } diff --git a/jme3-networking/src/main/java/com/jme3/network/message/ClientRegistrationMessage.java b/jme3-networking/src/main/java/com/jme3/network/message/ClientRegistrationMessage.java index 50272e9deb..9c6edb96b4 100644 --- a/jme3-networking/src/main/java/com/jme3/network/message/ClientRegistrationMessage.java +++ b/jme3-networking/src/main/java/com/jme3/network/message/ClientRegistrationMessage.java @@ -49,32 +49,71 @@ @Serializable() public class ClientRegistrationMessage extends AbstractMessage { + /** + * Serializer id reserved for backwards-compatible client registration messages. + */ public static final short SERIALIZER_ID = -44; private long id; private String gameName; private int version; + /** + * Creates an empty registration message for serialization. + */ + public ClientRegistrationMessage() { + } + + /** + * Returns the client identifier that couples reliable and unreliable channels. + * + * @return the client identifier + */ public long getId() { return id; } + /** + * Sets the client identifier that couples reliable and unreliable channels. + * + * @param id the client identifier + */ public void setId(long id) { this.id = id; } + /** + * Sets the game name expected by the server. + * + * @param name the game name + */ public void setGameName( String name ) { this.gameName = name; } + /** + * Returns the game name expected by the server. + * + * @return the game name + */ public String getGameName() { return gameName; } + /** + * Sets the protocol or game version expected by the server. + * + * @param version the game version + */ public void setVersion( int version ) { this.version = version; } + /** + * Returns the protocol or game version expected by the server. + * + * @return the game version + */ public int getVersion() { return version; } @@ -91,6 +130,11 @@ public String toString() { * SM serializer registrations... and now will be forever. */ public static class ClientRegistrationSerializer extends Serializer { + /** + * Creates the serializer used for client registration messages. + */ + public ClientRegistrationSerializer() { + } @Override public ClientRegistrationMessage readObject( ByteBuffer data, Class c ) throws IOException { diff --git a/jme3-networking/src/main/java/com/jme3/network/message/CompressedMessage.java b/jme3-networking/src/main/java/com/jme3/network/message/CompressedMessage.java index 40f20bf6ee..a6cdf0238d 100644 --- a/jme3-networking/src/main/java/com/jme3/network/message/CompressedMessage.java +++ b/jme3-networking/src/main/java/com/jme3/network/message/CompressedMessage.java @@ -45,16 +45,34 @@ public class CompressedMessage extends AbstractMessage { private Message message; + /** + * Creates an empty compressed message for serialization. + */ public CompressedMessage() { } + /** + * Creates a compressed wrapper for the specified message. + * + * @param msg the wrapped message + */ public CompressedMessage(Message msg) { this.message = msg; } + /** + * Sets the wrapped message payload. + * + * @param message the wrapped message + */ public void setMessage(Message message) { this.message = message; } + /** + * Returns the wrapped message payload. + * + * @return the wrapped message + */ public Message getMessage() { return message; } diff --git a/jme3-networking/src/main/java/com/jme3/network/message/DisconnectMessage.java b/jme3-networking/src/main/java/com/jme3/network/message/DisconnectMessage.java index 29f732768c..5408f4c7fd 100644 --- a/jme3-networking/src/main/java/com/jme3/network/message/DisconnectMessage.java +++ b/jme3-networking/src/main/java/com/jme3/network/message/DisconnectMessage.java @@ -45,28 +45,69 @@ @Serializable() public class DisconnectMessage extends AbstractMessage { + /** + * Serializer id reserved for backwards-compatible disconnect messages. + */ public static final short SERIALIZER_ID = -42; + /** + * Disconnect type used when a client is kicked by the server. + */ public static final String KICK = "Kick"; + /** + * Disconnect type used when the user requested closure. + */ public static final String USER_REQUESTED = "User requested"; + /** + * Disconnect type used when an error closed the connection. + */ public static final String ERROR = "Error"; + /** + * Disconnect type used when a message or client was filtered. + */ public static final String FILTERED = "Filtered"; private String reason; private String type; + /** + * Creates an empty disconnect message for serialization. + */ + public DisconnectMessage() { + } + + /** + * Returns the disconnect reason text. + * + * @return the disconnect reason, or null + */ public String getReason() { return reason; } + /** + * Sets the disconnect reason text. + * + * @param reason the disconnect reason + */ public void setReason(String reason) { this.reason = reason; } + /** + * Returns the disconnect category. + * + * @return the disconnect type + */ public String getType() { return type; } + /** + * Sets the disconnect category. + * + * @param type the disconnect type + */ public void setType(String type) { this.type = type; } @@ -83,6 +124,11 @@ public String toString() { * SM serializer registrations... and now will be forever. */ public static class DisconnectSerializer extends Serializer { + /** + * Creates the serializer used for disconnect messages. + */ + public DisconnectSerializer() { + } @Override public DisconnectMessage readObject( ByteBuffer data, Class c ) throws IOException { diff --git a/jme3-networking/src/main/java/com/jme3/network/message/GZIPCompressedMessage.java b/jme3-networking/src/main/java/com/jme3/network/message/GZIPCompressedMessage.java index a3065589a7..ae64531ed6 100644 --- a/jme3-networking/src/main/java/com/jme3/network/message/GZIPCompressedMessage.java +++ b/jme3-networking/src/main/java/com/jme3/network/message/GZIPCompressedMessage.java @@ -42,10 +42,18 @@ */ @Serializable() public class GZIPCompressedMessage extends CompressedMessage { + /** + * Creates an empty gzip-compressed message for serialization. + */ public GZIPCompressedMessage() { super(); } + /** + * Creates a gzip-compressed wrapper for the specified message. + * + * @param msg the wrapped message + */ public GZIPCompressedMessage(Message msg) { super(msg); } diff --git a/jme3-networking/src/main/java/com/jme3/network/message/SerializerRegistrationsMessage.java b/jme3-networking/src/main/java/com/jme3/network/message/SerializerRegistrationsMessage.java index 331c7ab096..905198a823 100644 --- a/jme3-networking/src/main/java/com/jme3/network/message/SerializerRegistrationsMessage.java +++ b/jme3-networking/src/main/java/com/jme3/network/message/SerializerRegistrationsMessage.java @@ -68,6 +68,9 @@ public class SerializerRegistrationsMessage extends AbstractMessage { private static final Logger log = Logger.getLogger(SerializerRegistrationsMessage.class.getName()); + /** + * Classes that are already built into serializer initialization and should not be re-sent. + */ public static final Set ignore = new HashSet(); static { // We could build this automatically, but then we @@ -116,21 +119,38 @@ public class SerializerRegistrationsMessage extends AbstractMessage { ignore.add(SerializerRegistrationsMessage.Registration.class); } + /** + * Cached compiled registration message used for new connections. + */ public static SerializerRegistrationsMessage INSTANCE; + /** + * Cached compiled registration entries. + */ public static Registration[] compiled; private static final Serializer fieldSerializer = new FieldSerializer(); private Registration[] registrations; + /** + * Creates an empty registrations message for serialization. + */ public SerializerRegistrationsMessage() { setReliable(true); } + /** + * Creates a registrations message containing the specified entries. + * + * @param registrations the registrations to send + */ public SerializerRegistrationsMessage( Registration... registrations ) { setReliable(true); this.registrations = registrations; } + /** + * Compiles the current serializer registry into a transferable message. + */ public static void compile() { // Let's just see what they are here @@ -158,6 +178,9 @@ public static void compile() { Serializer.setReadOnly(true); } + /** + * Applies all registrations carried by this message to the local serializer registry. + */ public void registerAll() { // See if we will have problems because our registry is locked @@ -185,6 +208,9 @@ public void registerAll() { log.log(Level.FINE, "Done registering serializable classes."); } + /** + * Transfer object describing a single serializer registration. + */ @Serializable public static final class Registration { @@ -192,9 +218,17 @@ public static final class Registration { private String className; private String serializerClassName; + /** + * Creates an empty transfer registration for serialization. + */ public Registration() { } + /** + * Creates a transfer registration from a live serializer registration. + * + * @param reg the live registration to copy + */ public Registration( SerializerRegistration reg ) { this.id = reg.getId(); @@ -204,6 +238,9 @@ public Registration( SerializerRegistration reg ) { } } + /** + * Registers this transfer entry with the local serializer registry. + */ @SuppressWarnings("unchecked") public void register() { try { diff --git a/jme3-networking/src/main/java/com/jme3/network/message/ZIPCompressedMessage.java b/jme3-networking/src/main/java/com/jme3/network/message/ZIPCompressedMessage.java index c39e8b226f..a0ed12764f 100644 --- a/jme3-networking/src/main/java/com/jme3/network/message/ZIPCompressedMessage.java +++ b/jme3-networking/src/main/java/com/jme3/network/message/ZIPCompressedMessage.java @@ -43,14 +43,28 @@ public class ZIPCompressedMessage extends CompressedMessage { private static int compressionLevel = 6; + /** + * Creates an empty ZIP-compressed message for serialization. + */ public ZIPCompressedMessage() { super(); } + /** + * Creates a ZIP-compressed wrapper for the specified message. + * + * @param msg the message to compress + */ public ZIPCompressedMessage(Message msg) { super(msg); } + /** + * Creates a ZIP-compressed wrapper for the specified message and compression level. + * + * @param msg the message to compress + * @param level the compression level to apply + */ public ZIPCompressedMessage(Message msg, int level) { super(msg); setLevel(level); @@ -66,5 +80,10 @@ public static void setLevel(int level) { compressionLevel = level; } + /** + * Returns the currently configured ZIP compression level. + * + * @return the ZIP compression level + */ public int getLevel() { return compressionLevel; } } diff --git a/jme3-networking/src/main/java/com/jme3/network/rmi/LocalObject.java b/jme3-networking/src/main/java/com/jme3/network/rmi/LocalObject.java index 277756a080..ee8c8b507e 100644 --- a/jme3-networking/src/main/java/com/jme3/network/rmi/LocalObject.java +++ b/jme3-networking/src/main/java/com/jme3/network/rmi/LocalObject.java @@ -39,6 +39,11 @@ * @author Kirill Vainer */ public class LocalObject { + /** + * Creates an empty local object descriptor. + */ + public LocalObject() { + } /** * Object name diff --git a/jme3-networking/src/main/java/com/jme3/network/rmi/MethodDef.java b/jme3-networking/src/main/java/com/jme3/network/rmi/MethodDef.java index 1b04c8a2a9..119e49a5d6 100644 --- a/jme3-networking/src/main/java/com/jme3/network/rmi/MethodDef.java +++ b/jme3-networking/src/main/java/com/jme3/network/rmi/MethodDef.java @@ -39,6 +39,11 @@ * @author Kirill Vainer */ public class MethodDef { + /** + * Creates an empty method definition. + */ + public MethodDef() { + } /** * Method name diff --git a/jme3-networking/src/main/java/com/jme3/network/rmi/ObjectDef.java b/jme3-networking/src/main/java/com/jme3/network/rmi/ObjectDef.java index 64ffe3057c..62c95dd352 100644 --- a/jme3-networking/src/main/java/com/jme3/network/rmi/ObjectDef.java +++ b/jme3-networking/src/main/java/com/jme3/network/rmi/ObjectDef.java @@ -35,8 +35,16 @@ import com.jme3.network.serializing.Serializable; import java.lang.reflect.Method; +/** + * Describes a remotely shared object and its callable methods. + */ @Serializable public class ObjectDef { + /** + * Creates an empty object definition. + */ + public ObjectDef() { + } /** * The object name, can be null if undefined. diff --git a/jme3-networking/src/main/java/com/jme3/network/rmi/ObjectStore.java b/jme3-networking/src/main/java/com/jme3/network/rmi/ObjectStore.java index 3e820ff5b4..da5e04b498 100644 --- a/jme3-networking/src/main/java/com/jme3/network/rmi/ObjectStore.java +++ b/jme3-networking/src/main/java/com/jme3/network/rmi/ObjectStore.java @@ -45,6 +45,9 @@ import java.util.logging.Level; import java.util.logging.Logger; +/** + * Legacy RMI object registry for exposing local objects and resolving remote proxies. + */ public class ObjectStore { private static final Logger logger = Logger.getLogger(ObjectStore.class.getName()); @@ -84,8 +87,16 @@ public String toString(){ private final Object receiveObjectLock = new Object(); + /** + * Handles server-side RMI message and connection callbacks. + */ public class ServerEventHandler implements MessageListener, ConnectionListener { + /** + * Creates the server-side event handler. + */ + public ServerEventHandler() { + } @Override public void messageReceived(HostedConnection source, Message m) { @@ -103,8 +114,16 @@ public void connectionRemoved(Server server, HostedConnection conn) { } + /** + * Handles client-side RMI message and connection callbacks. + */ public class ClientEventHandler implements MessageListener, ClientStateListener { + /** + * Creates the client-side event handler. + */ + public ClientEventHandler() { + } @Override public void messageReceived(Object source, Message m) { @@ -129,6 +148,11 @@ public void clientDisconnected(Client c, DisconnectInfo info) { Serializer.registerClass(RemoteMethodReturnMessage.class, s); } + /** + * Creates an object store bound to a client. + * + * @param client the client that owns the store + */ @SuppressWarnings("unchecked") public ObjectStore(Client client) { this.client = client; @@ -139,6 +163,11 @@ public ObjectStore(Client client) { client.addClientStateListener(clientEventHandler); } + /** + * Creates an object store bound to a server. + * + * @param server the server that owns the store + */ public ObjectStore(Server server) { this.server = server; server.addMessageListener(serverEventHandler, @@ -156,6 +185,13 @@ private ObjectDef makeObjectDef(LocalObject localObj){ return def; } + /** + * Exposes a local object to the remote side under the specified name. + * + * @param name the exported object name + * @param obj the local object to expose + * @throws IOException if serialization or transport setup fails + */ public void exposeObject(String name, Object obj) throws IOException{ // Create a local object LocalObject localObj = new LocalObject(); @@ -188,6 +224,16 @@ public void exposeObject(String name, Object obj) throws IOException{ } } + /** + * Looks up an exposed remote object and returns a proxy implementing the requested type. + * + * @param the requested proxy type + * @param name the exported object name + * @param type the interface the proxy should implement + * @param waitFor true to wait until the object appears + * @return the remote object proxy + * @throws InterruptedException if interrupted while waiting + */ @SuppressWarnings("unchecked") public T getExposedObject(String name, Class type, boolean waitFor) throws InterruptedException{ RemoteObject ro = remoteObjects.get(name); diff --git a/jme3-networking/src/main/java/com/jme3/network/rmi/RemoteMethodCallMessage.java b/jme3-networking/src/main/java/com/jme3/network/rmi/RemoteMethodCallMessage.java index 8c43c2842c..fddf456680 100644 --- a/jme3-networking/src/main/java/com/jme3/network/rmi/RemoteMethodCallMessage.java +++ b/jme3-networking/src/main/java/com/jme3/network/rmi/RemoteMethodCallMessage.java @@ -42,6 +42,9 @@ @Serializable public class RemoteMethodCallMessage extends AbstractMessage { + /** + * Creates an empty remote method call message. + */ public RemoteMethodCallMessage(){ super(true); } diff --git a/jme3-networking/src/main/java/com/jme3/network/rmi/RemoteMethodReturnMessage.java b/jme3-networking/src/main/java/com/jme3/network/rmi/RemoteMethodReturnMessage.java index 31f2b396de..14fc21552d 100644 --- a/jme3-networking/src/main/java/com/jme3/network/rmi/RemoteMethodReturnMessage.java +++ b/jme3-networking/src/main/java/com/jme3/network/rmi/RemoteMethodReturnMessage.java @@ -43,6 +43,9 @@ @Serializable public class RemoteMethodReturnMessage extends AbstractMessage { + /** + * Creates an empty remote method return message. + */ public RemoteMethodReturnMessage(){ super(true); } diff --git a/jme3-networking/src/main/java/com/jme3/network/rmi/RemoteObject.java b/jme3-networking/src/main/java/com/jme3/network/rmi/RemoteObject.java index 9f46c11bdb..727478232b 100644 --- a/jme3-networking/src/main/java/com/jme3/network/rmi/RemoteObject.java +++ b/jme3-networking/src/main/java/com/jme3/network/rmi/RemoteObject.java @@ -72,6 +72,12 @@ public class RemoteObject implements InvocationHandler { */ HostedConnection client; + /** + * Creates remote object metadata for a shared object proxy. + * + * @param store the owning object store + * @param client the hosting connection, or null for client-side usage + */ public RemoteObject(ObjectStore store, HostedConnection client){ this.store = store; this.client = client; diff --git a/jme3-networking/src/main/java/com/jme3/network/rmi/RemoteObjectDefMessage.java b/jme3-networking/src/main/java/com/jme3/network/rmi/RemoteObjectDefMessage.java index a15ca5ccb6..c94c5a6271 100644 --- a/jme3-networking/src/main/java/com/jme3/network/rmi/RemoteObjectDefMessage.java +++ b/jme3-networking/src/main/java/com/jme3/network/rmi/RemoteObjectDefMessage.java @@ -41,8 +41,14 @@ @Serializable public class RemoteObjectDefMessage extends AbstractMessage { + /** + * The object definitions being announced to the remote side. + */ public ObjectDef[] objects; + /** + * Creates an empty remote object definition message. + */ public RemoteObjectDefMessage(){ super(true); } diff --git a/jme3-networking/src/main/java/com/jme3/network/rmi/RmiSerializer.java b/jme3-networking/src/main/java/com/jme3/network/rmi/RmiSerializer.java index 5e28d0ecee..feb44175ac 100644 --- a/jme3-networking/src/main/java/com/jme3/network/rmi/RmiSerializer.java +++ b/jme3-networking/src/main/java/com/jme3/network/rmi/RmiSerializer.java @@ -52,6 +52,12 @@ public class RmiSerializer extends Serializer { // not good for multithreaded applications private char[] chrBuf = new char[256]; + /** + * Creates an RMI serializer. + */ + public RmiSerializer() { + } + private void writeString(ByteBuffer buffer, String string) throws IOException{ int length = string.length(); if (length > 255){ diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/Serializable.java b/jme3-networking/src/main/java/com/jme3/network/serializing/Serializable.java index 456a7f4320..5535464638 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/Serializable.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/Serializable.java @@ -43,6 +43,16 @@ */ @Retention(RetentionPolicy.RUNTIME) public @interface Serializable { + /** + * Returns the serializer class to use for the annotated type. + * + * @return the serializer class + */ Class serializer() default FieldSerializer.class; + /** + * Returns the fixed serializer id for the annotated type, or {@code 0} for auto-assignment. + * + * @return the serializer id + */ short id() default 0; } diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/Serializer.java b/jme3-networking/src/main/java/com/jme3/network/serializing/Serializer.java index c787ff6887..ce52f309f8 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/Serializer.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/Serializer.java @@ -55,6 +55,9 @@ * @author Lars Wesselius */ public abstract class Serializer { + /** + * Shared logger for serializer infrastructure. + */ protected static final Logger log = Logger.getLogger(Serializer.class.getName()); private static final SerializerRegistration NULL_CLASS = new SerializerRegistration( null, Void.class, (short)-1 ); @@ -71,6 +74,12 @@ public abstract class Serializer { private static boolean strictRegistration = true; private static volatile boolean locked = false; + + /** + * Creates a serializer. + */ + protected Serializer() { + } // Registers the classes we already have serializers for. @@ -78,6 +87,9 @@ public abstract class Serializer { initialize(); } + /** + * Reinitializes the global serializer registry with the built-in registrations. + */ public static void initialize() { // Reset all of the indices and tracking variables just in case @@ -155,15 +167,28 @@ public static void initialize() { * {@code @Serializable } will not be auto-registered during write. Defaults * to true since this is almost never desired behavior with the way * this code works. Set to false to get the old permissive behavior. + * + * @param b true to forbid automatic registration for classes without fixed ids */ public static void setStrictRegistration( boolean b ) { strictRegistration = b; } + /** + * Registers the specified serializable class. + * + * @param cls the class to register + * @return the resulting serializer registration + */ public static SerializerRegistration registerClass(Class cls) { return registerClass(cls, true); } + /** + * Registers each of the specified classes. + * + * @param classes the classes to register + */ public static void registerClasses(Class... classes) { for( Class c : classes ) { registerClass(c); @@ -188,11 +213,18 @@ private static short nextId() { * to register classes will fail. This can be used by servers to lock the * registry to avoid accidentally registering classes after a full registry * set has been compiled. + * + * @param b true to lock the registry against future registrations */ public static void setReadOnly( boolean b ) { locked = b; } + /** + * Returns whether the registry is locked against new registrations. + * + * @return true if the registry is read-only + */ public static boolean isReadOnly() { return locked; } @@ -201,6 +233,11 @@ public static boolean isReadOnly() { * Directly registers a class for a specific ID. Generally, use the regular * registerClass() method. This method is intended for framework code that might * be maintaining specific ID maps across client and server. + * + * @param id the serializer id to bind to the class + * @param cls the class being registered + * @param serializer the serializer instance to use for the class + * @return the created serializer registration */ public static SerializerRegistration registerClassForId( short id, Class cls, Serializer serializer ) { @@ -227,6 +264,10 @@ public static SerializerRegistration registerClassForId( short id, Class cls, Se /** * Registers the specified class. The failOnMiss flag controls whether * this method returns null for failed registration or throws an exception. + * + * @param cls the class to register + * @param failOnMiss true to throw if the class is not serializable + * @return the serializer registration, or null if registration is skipped */ @SuppressWarnings("unchecked") public static SerializerRegistration registerClass(Class cls, boolean failOnMiss) { @@ -258,6 +299,9 @@ public static SerializerRegistration registerClass(Class cls, boolean failOnMiss /** * @deprecated This cannot be implemented in a reasonable way that works in * all deployment methods. + * + * @param pkgName the package name to scan + * @return the registrations created for classes found in the package */ @Deprecated public static SerializerRegistration[] registerPackage(String pkgName) { @@ -304,6 +348,13 @@ private static List findClasses(File dir, String pkgName) throws ClassNot return classes; } + /** + * Registers a class using the specified serializer instance. + * + * @param cls the class to register + * @param serializer the serializer instance to bind + * @return the resulting serializer registration + */ public static SerializerRegistration registerClass(Class cls, Serializer serializer) { SerializerRegistration existingReg = getExactSerializerRegistration(cls); @@ -316,30 +367,73 @@ public static SerializerRegistration registerClass(Class cls, Serializer seriali return registerClassForId( id, cls, serializer ); } + /** + * Returns the serializer registered directly for the specified class. + * + * @param cls the class to resolve + * @return the directly registered serializer + */ public static Serializer getExactSerializer(Class cls) { return classRegistrations.get(cls).getSerializer(); } + /** + * Returns the serializer for the specified class using the configured miss behavior. + * + * @param cls the class to resolve + * @return the serializer for the class + */ public static Serializer getSerializer(Class cls) { return getSerializer(cls, true); } + /** + * Returns the serializer for the specified class. + * + * @param cls the class to resolve + * @param failOnMiss true to fail if no serializer can be resolved + * @return the serializer for the class + */ public static Serializer getSerializer(Class cls, boolean failOnMiss) { return getSerializerRegistration(cls, failOnMiss).getSerializer(); } + /** + * Returns the ordered collection of current serializer registrations. + * + * @return the serializer registrations + */ public static Collection getSerializerRegistrations() { return registrations; } + /** + * Returns the registration directly associated with the specified class. + * + * @param cls the class to resolve + * @return the direct registration, or {@code null} + */ public static SerializerRegistration getExactSerializerRegistration(Class cls) { return classRegistrations.get(cls); } + /** + * Returns the registration for the specified class using the configured miss behavior. + * + * @param cls the class to resolve + * @return the resolved serializer registration + */ public static SerializerRegistration getSerializerRegistration(Class cls) { return getSerializerRegistration(cls, strictRegistration); } + /** + * Returns the registration for the specified class. + * + * @param cls the class to resolve + * @param failOnMiss true to fail if no registration can be resolved + * @return the resolved serializer registration + */ @SuppressWarnings("unchecked") public static SerializerRegistration getSerializerRegistration(Class cls, boolean failOnMiss) { SerializerRegistration reg = classRegistrations.get(cls); @@ -411,6 +505,7 @@ public static Object readClassAndObject(ByteBuffer buffer) throws IOException { * @param buffer The buffer to write the given class to. * @param type The class to write. * @return The SerializerRegistration that's registered to the class. + * @throws IOException If writing to the buffer fails. */ public static SerializerRegistration writeClass(ByteBuffer buffer, Class type) throws IOException { SerializerRegistration reg = getSerializerRegistration(type); @@ -460,6 +555,7 @@ public static void writeClassAndObject(ByteBuffer buffer, Object object) throws /** * Read an object from the buffer, effectively deserializing it. * + * @param The object type expected from the serializer. * @param data The buffer to read from. * @param c The class of the object. * @return The object read. diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/SerializerException.java b/jme3-networking/src/main/java/com/jme3/network/serializing/SerializerException.java index 655e31d7a1..6248076021 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/SerializerException.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/SerializerException.java @@ -41,12 +41,23 @@ */ public class SerializerException extends IOException { + /** + * Creates a serializer exception with a message and cause. + * + * @param msg the failure message + * @param cause the underlying cause + */ public SerializerException( String msg, Throwable cause ) { super( msg ); initCause(cause); } + /** + * Creates a serializer exception with a message. + * + * @param msg the failure message + */ public SerializerException( String msg ) { super( msg ); diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/SerializerRegistration.java b/jme3-networking/src/main/java/com/jme3/network/serializing/SerializerRegistration.java index 7b1de57384..e8fd1e2502 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/SerializerRegistration.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/SerializerRegistration.java @@ -42,6 +42,13 @@ public final class SerializerRegistration { private short id; private Class type; + /** + * Creates a serializer registration. + * + * @param serializer the serializer instance + * @param cls the registered type + * @param id the serializer id + */ public SerializerRegistration(Serializer serializer, Class cls, short id) { this.serializer = serializer; type = cls; diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/ArraySerializer.java b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/ArraySerializer.java index ade05a59f8..9331a1aa68 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/ArraySerializer.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/ArraySerializer.java @@ -44,6 +44,11 @@ */ @SuppressWarnings("unchecked") public class ArraySerializer extends Serializer { + /** + * Creates an array serializer. + */ + public ArraySerializer() { + } private int[] getDimensions (Object array) { int depth = 0; Class nextClass = array.getClass().getComponentType(); diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/BooleanSerializer.java b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/BooleanSerializer.java index 7393edd1a3..1fdd99c3c6 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/BooleanSerializer.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/BooleanSerializer.java @@ -42,6 +42,11 @@ */ @SuppressWarnings("unchecked") public class BooleanSerializer extends Serializer { + /** + * Creates a boolean serializer. + */ + public BooleanSerializer() { + } @Override public Boolean readObject(ByteBuffer data, Class c) throws IOException { diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/ByteSerializer.java b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/ByteSerializer.java index 9c36954f97..27bbf759e7 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/ByteSerializer.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/ByteSerializer.java @@ -42,6 +42,11 @@ */ @SuppressWarnings("unchecked") public class ByteSerializer extends Serializer { + /** + * Creates a byte serializer. + */ + public ByteSerializer() { + } @Override public Byte readObject(ByteBuffer data, Class c) throws IOException { diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/CharSerializer.java b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/CharSerializer.java index be32765658..fef0abdcba 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/CharSerializer.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/CharSerializer.java @@ -42,6 +42,11 @@ */ @SuppressWarnings("unchecked") public class CharSerializer extends Serializer { + /** + * Creates a char serializer. + */ + public CharSerializer() { + } @Override public Character readObject(ByteBuffer data, Class c) throws IOException { diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/CollectionSerializer.java b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/CollectionSerializer.java index c0580e348e..be3a00e42c 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/CollectionSerializer.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/CollectionSerializer.java @@ -46,6 +46,11 @@ * @author Lars Wesselius */ public class CollectionSerializer extends Serializer { + /** + * Creates a collection serializer. + */ + public CollectionSerializer() { + } @SuppressWarnings("unchecked") @Override diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/DateSerializer.java b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/DateSerializer.java index 7ce507a702..020a35a478 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/DateSerializer.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/DateSerializer.java @@ -43,6 +43,11 @@ */ @SuppressWarnings("unchecked") public class DateSerializer extends Serializer { + /** + * Creates a date serializer. + */ + public DateSerializer() { + } @Override public Date readObject(ByteBuffer data, Class c) throws IOException { diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/DoubleSerializer.java b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/DoubleSerializer.java index 5472d7b065..fb498ac6a1 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/DoubleSerializer.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/DoubleSerializer.java @@ -42,6 +42,11 @@ */ @SuppressWarnings("unchecked") public class DoubleSerializer extends Serializer { + /** + * Creates a double serializer. + */ + public DoubleSerializer() { + } @Override public Double readObject(ByteBuffer data, Class c) throws IOException { diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/EnumSerializer.java b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/EnumSerializer.java index 6740ea0389..eb57de4239 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/EnumSerializer.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/EnumSerializer.java @@ -42,6 +42,11 @@ * @author Lars Wesselius */ public class EnumSerializer extends Serializer { + /** + * Creates an enum serializer. + */ + public EnumSerializer() { + } @Override public T readObject(ByteBuffer data, Class c) throws IOException { try { diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/FieldSerializer.java b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/FieldSerializer.java index 3178892b05..fd3896d3dc 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/FieldSerializer.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/FieldSerializer.java @@ -49,12 +49,22 @@ * @author Lars Wesselius, Nathan Sweet */ public class FieldSerializer extends Serializer { + /** + * Creates a reflective field serializer. + */ + public FieldSerializer() { + } private static final Logger log = Logger.getLogger(FieldSerializer.class.getName()); private static Map savedFields = new HashMap(); private static Map savedCtors = new HashMap(); + /** + * Validates and caches the reflective access metadata for a class. + * + * @param clazz the class to inspect + */ @SuppressWarnings("unchecked") protected void checkClass(Class clazz) { diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/FloatSerializer.java b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/FloatSerializer.java index 42e65487f7..b1cd9fa2c3 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/FloatSerializer.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/FloatSerializer.java @@ -42,6 +42,11 @@ */ @SuppressWarnings("unchecked") public class FloatSerializer extends Serializer { + /** + * Creates a float serializer. + */ + public FloatSerializer() { + } @Override public Float readObject(ByteBuffer data, Class c) throws IOException { diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/GZIPSerializer.java b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/GZIPSerializer.java index 63b264e6c6..eff38feb41 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/GZIPSerializer.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/GZIPSerializer.java @@ -47,6 +47,11 @@ * @author Lars Wesselius */ public class GZIPSerializer extends Serializer { + /** + * Creates a gzip serializer. + */ + public GZIPSerializer() { + } @SuppressWarnings("unchecked") @Override diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/IntSerializer.java b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/IntSerializer.java index 373ab89dbd..20a6287dd1 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/IntSerializer.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/IntSerializer.java @@ -42,6 +42,11 @@ */ @SuppressWarnings("unchecked") public class IntSerializer extends Serializer { + /** + * Creates an integer serializer. + */ + public IntSerializer() { + } @Override public Integer readObject(ByteBuffer data, Class c) throws IOException { diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/LongSerializer.java b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/LongSerializer.java index 6545d4b4d0..5cb5f63e1e 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/LongSerializer.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/LongSerializer.java @@ -42,6 +42,11 @@ */ @SuppressWarnings("unchecked") public class LongSerializer extends Serializer { + /** + * Creates a long serializer. + */ + public LongSerializer() { + } @Override public Long readObject(ByteBuffer data, Class c) throws IOException { diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/MapSerializer.java b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/MapSerializer.java index 09043ac412..719fa6eb0d 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/MapSerializer.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/MapSerializer.java @@ -42,7 +42,15 @@ import java.util.Set; import java.util.logging.Level; +/** + * Serializes map implementations and their key/value entries. + */ public class MapSerializer extends Serializer { + /** + * Creates a map serializer. + */ + public MapSerializer() { + } /* diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/SavableSerializer.java b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/SavableSerializer.java index c91c8e4c5c..c040f99a4e 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/SavableSerializer.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/SavableSerializer.java @@ -40,7 +40,15 @@ import java.io.OutputStream; import java.nio.ByteBuffer; +/** + * Serializes {@link Savable} instances using the binary exporter/importer pipeline. + */ public class SavableSerializer extends Serializer { + /** + * Creates a savable serializer. + */ + public SavableSerializer() { + } private BinaryExporter exporter = new BinaryExporter(); private BinaryImporter importer = new BinaryImporter(); diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/SerializableSerializer.java b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/SerializableSerializer.java index 927053e557..4ee005a995 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/SerializableSerializer.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/SerializableSerializer.java @@ -44,6 +44,11 @@ */ @SuppressWarnings("unchecked") public class SerializableSerializer extends Serializer { + /** + * Creates a serializer for {@link java.io.Serializable} values. + */ + public SerializableSerializer() { + } @Override public Serializable readObject(ByteBuffer data, Class c) throws IOException { diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/ShortSerializer.java b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/ShortSerializer.java index c306335165..587d11b456 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/ShortSerializer.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/ShortSerializer.java @@ -42,6 +42,11 @@ */ @SuppressWarnings("unchecked") public class ShortSerializer extends Serializer { + /** + * Creates a short serializer. + */ + public ShortSerializer() { + } @Override public Short readObject(ByteBuffer data, Class c) throws IOException { return data.getShort(); diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/StringSerializer.java b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/StringSerializer.java index 2f3bd80027..185d5de124 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/StringSerializer.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/StringSerializer.java @@ -43,7 +43,19 @@ */ @SuppressWarnings("unchecked") public class StringSerializer extends Serializer { + /** + * Creates a string serializer. + */ + public StringSerializer() { + } + /** + * Writes a UTF-8 string with a compact length prefix. + * + * @param s the string to write + * @param buffer the target buffer + * @throws IOException if the string cannot be encoded + */ public static void writeString( String s, ByteBuffer buffer ) throws IOException { if (s == null) { // Write that it's 0. @@ -71,6 +83,13 @@ public static void writeString( String s, ByteBuffer buffer ) throws IOException } } + /** + * Reads a UTF-8 string with a compact length prefix. + * + * @param data the source buffer + * @return the decoded string, or {@code null} + * @throws IOException if the encoded value is invalid + */ public static String readString( ByteBuffer data ) throws IOException { int length = -1; byte type = data.get(); diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/Vector3Serializer.java b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/Vector3Serializer.java index 8c4251acb3..ad05f8f7c6 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/Vector3Serializer.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/Vector3Serializer.java @@ -37,10 +37,17 @@ import java.nio.ByteBuffer; /** + * Serializes {@link Vector3f} instances. + * * @author Kirill Vainer */ @SuppressWarnings("unchecked") public class Vector3Serializer extends Serializer { + /** + * Creates a vector serializer. + */ + public Vector3Serializer() { + } @Override public Vector3f readObject(ByteBuffer data, Class c) throws IOException { diff --git a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/ZIPSerializer.java b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/ZIPSerializer.java index cb8bd2a189..0c7da32fac 100644 --- a/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/ZIPSerializer.java +++ b/jme3-networking/src/main/java/com/jme3/network/serializing/serializers/ZIPSerializer.java @@ -48,6 +48,11 @@ * @author Lars Wesselius */ public class ZIPSerializer extends Serializer { + /** + * Creates a zip serializer. + */ + public ZIPSerializer() { + } @SuppressWarnings("unchecked") @Override diff --git a/jme3-networking/src/main/java/com/jme3/network/service/AbstractClientService.java b/jme3-networking/src/main/java/com/jme3/network/service/AbstractClientService.java index d1a848dac4..9d58584e06 100644 --- a/jme3-networking/src/main/java/com/jme3/network/service/AbstractClientService.java +++ b/jme3-networking/src/main/java/com/jme3/network/service/AbstractClientService.java @@ -46,12 +46,17 @@ public abstract class AbstractClientService extends AbstractService implements ClientService { + /** + * Creates an uninitialized client service. + */ protected AbstractClientService() { } /** * Returns the client for this client service or null if * the service is not yet attached. + * + * @return the attached client, or null if the service is detached */ protected Client getClient() { ClientServiceManager csm = getServiceManager(); diff --git a/jme3-networking/src/main/java/com/jme3/network/service/AbstractHostedConnectionService.java b/jme3-networking/src/main/java/com/jme3/network/service/AbstractHostedConnectionService.java index e7b6724070..14b4cc59b9 100644 --- a/jme3-networking/src/main/java/com/jme3/network/service/AbstractHostedConnectionService.java +++ b/jme3-networking/src/main/java/com/jme3/network/service/AbstractHostedConnectionService.java @@ -72,6 +72,8 @@ protected AbstractHostedConnectionService() { /** * Creates a new HostedService that will automatically host * connections only if autoHost is true. + * + * @param autoHost true to automatically host new connections */ protected AbstractHostedConnectionService( boolean autoHost ) { this.autoHost = autoHost; @@ -86,6 +88,8 @@ protected AbstractHostedConnectionService( boolean autoHost ) { *

Reasons for doing this vary but usually would be because * the client shouldn't be allowed to perform any service-related calls until * it has provided more information... for example, logging in.

+ * + * @param b true to auto-host new connections */ public void setAutoHost( boolean b ) { this.autoHost = b; @@ -94,6 +98,8 @@ public void setAutoHost( boolean b ) { /** * Returns true if this service automatically attaches * hosting capabilities to new connections. + * + * @return true if new connections are auto-hosted */ public boolean getAutoHost() { return autoHost; @@ -106,6 +112,8 @@ public boolean getAutoHost() { * attributes on the connection. If autoHost is true then this * method is called automatically during connectionAdded() * processing. + * + * @param hc the hosted connection to initialize */ public abstract void startHostingOnConnection( HostedConnection hc ); @@ -114,6 +122,8 @@ public boolean getAutoHost() { * This will be called automatically when the connectionRemoved() * event occurs... whether the application has already called it * or not. + * + * @param hc the hosted connection to tear down */ public abstract void stopHostingOnConnection( HostedConnection hc ); diff --git a/jme3-networking/src/main/java/com/jme3/network/service/AbstractHostedService.java b/jme3-networking/src/main/java/com/jme3/network/service/AbstractHostedService.java index 6c6e8d2130..575f79fbf7 100644 --- a/jme3-networking/src/main/java/com/jme3/network/service/AbstractHostedService.java +++ b/jme3-networking/src/main/java/com/jme3/network/service/AbstractHostedService.java @@ -48,12 +48,17 @@ public abstract class AbstractHostedService extends AbstractService implements HostedService { + /** + * Creates an uninitialized hosted service. + */ protected AbstractHostedService() { } /** * Returns the server for this hosted service or null if * the service is not yet attached. + * + * @return the attached server, or null if the service is detached */ protected Server getServer() { HostedServiceManager hsm = getServiceManager(); diff --git a/jme3-networking/src/main/java/com/jme3/network/service/AbstractService.java b/jme3-networking/src/main/java/com/jme3/network/service/AbstractService.java index 46ffb22916..2b154a9290 100644 --- a/jme3-networking/src/main/java/com/jme3/network/service/AbstractService.java +++ b/jme3-networking/src/main/java/com/jme3/network/service/AbstractService.java @@ -39,18 +39,24 @@ * and getService(type). Subclasses must at least override the * onInitialize() method to handle service initialization. * + * @param the service manager type * @author Paul Speed */ public abstract class AbstractService implements Service { private S serviceManager; + /** + * Creates an uninitialized service. + */ protected AbstractService() { } /** * Returns the ServiceManager that was passed to * initialize() during service initialization. + * + * @return the owning service manager, or null if not yet initialized */ protected S getServiceManager() { return serviceManager; @@ -59,6 +65,10 @@ protected S getServiceManager() { /** * Retrieves the first sibling service of the specified * type. + * + * @param the requested service type + * @param type the class of the service to look up + * @return the first matching sibling service, or null if none is registered */ @SuppressWarnings("unchecked") protected > T getService( Class type ) { @@ -78,6 +88,8 @@ public final void initialize( S serviceManager ) { /** * Called during initialize() for the subclass to perform * implementation specific initialization. + * + * @param serviceManager the service manager initializing this service */ protected abstract void onInitialize( S serviceManager ); diff --git a/jme3-networking/src/main/java/com/jme3/network/service/ClientServiceManager.java b/jme3-networking/src/main/java/com/jme3/network/service/ClientServiceManager.java index 667e6fe578..1bc8f4c802 100644 --- a/jme3-networking/src/main/java/com/jme3/network/service/ClientServiceManager.java +++ b/jme3-networking/src/main/java/com/jme3/network/service/ClientServiceManager.java @@ -46,6 +46,8 @@ public class ClientServiceManager extends ServiceManager { /** * Creates a new ClientServiceManager for the specified network Client. + * + * @param client the client whose services are being managed */ public ClientServiceManager( Client client ) { this.client = client; @@ -53,6 +55,8 @@ public ClientServiceManager( Client client ) { /** * Returns the network Client associated with this ClientServiceManager. + * + * @return the managed client */ public Client getClient() { return client; @@ -70,6 +74,8 @@ protected final ClientServiceManager getParent() { /** * Adds the specified ClientService and initializes it. If the service manager * has already been started then the service will also be started. + * + * @param s the client service to add */ public void addService( ClientService s ) { super.addService(s); @@ -81,6 +87,8 @@ public void addService( ClientService s ) { * This is a convenience method that delegates to addService(), thus each * service will be initialized (and possibly started) in sequence rather * than doing them all at the end. + * + * @param services the client services to add */ public void addServices( ClientService... services ) { for( ClientService s : services ) { @@ -93,6 +101,8 @@ public void addServices( ClientService... services ) { * and terminating it as required. If this service manager is in a * started state then the service will be stopped. After removal, * the service will be terminated. + * + * @param s the client service to remove */ public void removeService( ClientService s ) { super.removeService(s); diff --git a/jme3-networking/src/main/java/com/jme3/network/service/HostedServiceManager.java b/jme3-networking/src/main/java/com/jme3/network/service/HostedServiceManager.java index f918729582..eab8f52c32 100644 --- a/jme3-networking/src/main/java/com/jme3/network/service/HostedServiceManager.java +++ b/jme3-networking/src/main/java/com/jme3/network/service/HostedServiceManager.java @@ -51,6 +51,8 @@ public class HostedServiceManager extends ServiceManager { /** * Creates a HostedServiceManager for the specified network Server. + * + * @param server the server whose services are managed here */ public HostedServiceManager( Server server ) { this.server = server; @@ -60,6 +62,8 @@ public HostedServiceManager( Server server ) { /** * Returns the network Server associated with this HostedServiceManager. + * + * @return the managed server */ public Server getServer() { return server; @@ -77,6 +81,8 @@ protected final HostedServiceManager getParent() { /** * Adds the specified HostedService and initializes it. If the service manager * has already been started then the service will also be started. + * + * @param s the hosted service to add */ public void addService( HostedService s ) { super.addService(s); @@ -88,6 +94,8 @@ public void addService( HostedService s ) { * This is a convenience method that delegates to addService(), thus each * service will be initialized (and possibly started) in sequence rather * than doing them all at the end. + * + * @param services the hosted services to add */ public void addServices( HostedService... services ) { for( HostedService s : services ) { @@ -100,6 +108,8 @@ public void addServices( HostedService... services ) { * and terminating it as required. If this service manager is in a * started state then the service will be stopped. After removal, * the service will be terminated. + * + * @param s the hosted service to remove */ public void removeService( HostedService s ) { super.removeService(s); @@ -108,6 +118,8 @@ public void removeService( HostedService s ) { /** * Called internally when a new connection has been added so that the * services can be notified. + * + * @param hc the added hosted connection */ protected void addConnection( HostedConnection hc ) { for( Service s : getServices() ) { @@ -118,6 +130,8 @@ protected void addConnection( HostedConnection hc ) { /** * Called internally when a connection has been removed so that the * services can be notified. + * + * @param hc the removed hosted connection */ protected void removeConnection( HostedConnection hc ) { for( Service s : getServices() ) { @@ -125,8 +139,17 @@ protected void removeConnection( HostedConnection hc ) { } } + /** + * Observes server connection events and forwards them to hosted services. + */ protected class ConnectionObserver implements ConnectionListener { + /** + * Creates the connection observer. + */ + protected ConnectionObserver() { + } + @Override public void connectionAdded(Server server, HostedConnection hc) { addConnection(hc); diff --git a/jme3-networking/src/main/java/com/jme3/network/service/Service.java b/jme3-networking/src/main/java/com/jme3/network/service/Service.java index f56c90dda7..53d4dd25d7 100644 --- a/jme3-networking/src/main/java/com/jme3/network/service/Service.java +++ b/jme3-networking/src/main/java/com/jme3/network/service/Service.java @@ -36,6 +36,7 @@ /** * The base interface for managed services. * + * @param the service manager type that owns the service * @author Paul Speed */ public interface Service { @@ -43,6 +44,8 @@ public interface Service { /** * Called when the service is first attached to the service * manager. + * + * @param serviceManager the manager that is initializing this service */ public void initialize( S serviceManager ); @@ -62,6 +65,8 @@ public interface Service { /** * The service manager is fully shutting down. All services * have been stopped and related connections closed. + * + * @param serviceManager the manager that is terminating this service */ public void terminate( S serviceManager ); } diff --git a/jme3-networking/src/main/java/com/jme3/network/service/ServiceManager.java b/jme3-networking/src/main/java/com/jme3/network/service/ServiceManager.java index 0100b65111..d05c57fdfe 100644 --- a/jme3-networking/src/main/java/com/jme3/network/service/ServiceManager.java +++ b/jme3-networking/src/main/java/com/jme3/network/service/ServiceManager.java @@ -42,6 +42,7 @@ * and ClientServiceManager classes are derived. This manages * the underlying services and their life cycles. * + * @param the parent type exposed to managed services * @author Paul Speed */ public abstract class ServiceManager { @@ -51,6 +52,9 @@ public abstract class ServiceManager { private final List> services = new CopyOnWriteArrayList<>(); private volatile boolean started = false; + /** + * Creates a service manager. + */ protected ServiceManager() { } @@ -58,6 +62,8 @@ protected ServiceManager() { * Retrieves the 'parent' of this service manager, usually * a more specifically typed version of 'this' but it can be * anything the services are expecting. + * + * @return the parent object exposed to managed services */ protected abstract T getParent(); @@ -65,6 +71,8 @@ protected ServiceManager() { * Returns the complete list of services managed by this * service manager. This list is thread safe following the * CopyOnWriteArrayList semantics. + * + * @return the managed services list */ protected List> getServices() { return services; @@ -90,6 +98,8 @@ public void start() { /** * Returns true if this service manager has been started. + * + * @return true if the manager is started */ public boolean isStarted() { return started; @@ -114,6 +124,9 @@ public void stop() { /** * Adds the specified service and initializes it. If the service manager * has already been started then the service will also be started. + * + * @param the concrete service type + * @param s the service to add */ public > void addService( S s ) { if( log.isLoggable(Level.FINE) ) { @@ -137,6 +150,9 @@ public > void addService( S s ) { * and terminating it as required. If this service manager is in a * started state then the service will be stopped. After removal, * the service will be terminated. + * + * @param the concrete service type + * @param s the service to remove */ public > void removeService( S s ) { if( log.isLoggable(Level.FINE) ) { @@ -170,6 +186,10 @@ public void terminate() { /** * Retrieves the first service of the specified type. + * + * @param the concrete service type + * @param type the service class to look up + * @return the first matching service, or null if none exists */ public > S getService( Class type ) { for( Service s : services ) { diff --git a/jme3-networking/src/main/java/com/jme3/network/service/rmi/Asynchronous.java b/jme3-networking/src/main/java/com/jme3/network/service/rmi/Asynchronous.java index a26d09635b..f52c6f804b 100644 --- a/jme3-networking/src/main/java/com/jme3/network/service/rmi/Asynchronous.java +++ b/jme3-networking/src/main/java/com/jme3/network/service/rmi/Asynchronous.java @@ -50,6 +50,11 @@ @Retention(value=RUNTIME) @Target(value=METHOD) public @interface Asynchronous { + /** + * Indicates whether the asynchronous invocation should use reliable transport. + * + * @return true to send the invocation reliably + */ boolean reliable() default true; } diff --git a/jme3-networking/src/main/java/com/jme3/network/service/rmi/ClassInfo.java b/jme3-networking/src/main/java/com/jme3/network/service/rmi/ClassInfo.java index d2a8c2886a..3bf433b2a7 100644 --- a/jme3-networking/src/main/java/com/jme3/network/service/rmi/ClassInfo.java +++ b/jme3-networking/src/main/java/com/jme3/network/service/rmi/ClassInfo.java @@ -56,16 +56,32 @@ public final class ClassInfo { public ClassInfo() { } + /** + * Creates shared class metadata for the specified type. + * + * @param typeId the network id assigned to the shared type + * @param type the reflected shared interface type + */ public ClassInfo( short typeId, Class type ) { this.typeId = typeId; this.name = type.getName(); this.methods = toMethodInfo(type, type.getMethods()); } + /** + * Returns the binary name of the shared type. + * + * @return the shared type name + */ public String getName() { return name; } + /** + * Resolves the shared type into a {@link Class}. + * + * @return the resolved class + */ public Class getType() { try { return Class.forName(name); @@ -74,14 +90,31 @@ public Class getType() { } } + /** + * Returns the network id assigned to this type. + * + * @return the type id + */ public short getId() { return typeId; } + /** + * Returns the method metadata associated with the specified id. + * + * @param id the method id + * @return the matching method metadata + */ public MethodInfo getMethod( short id ) { return methods[id]; } + /** + * Finds method metadata matching the specified reflected method. + * + * @param m the reflected method + * @return the matching method metadata, or null if none matches + */ public MethodInfo getMethod( Method m ) { for( MethodInfo mi : methods ) { if( mi.matches(m) ) { @@ -101,6 +134,11 @@ private MethodInfo[] toMethodInfo( Class type, Method[] methods ) { return result.toArray(new MethodInfo[result.size()]); } + /** + * Returns the method metadata array for this shared type. + * + * @return the shared method metadata + */ public MethodInfo[] getMethods() { return methods; } diff --git a/jme3-networking/src/main/java/com/jme3/network/service/rmi/ClassInfoRegistry.java b/jme3-networking/src/main/java/com/jme3/network/service/rmi/ClassInfoRegistry.java index 61f47b3adf..a3df579a4c 100644 --- a/jme3-networking/src/main/java/com/jme3/network/service/rmi/ClassInfoRegistry.java +++ b/jme3-networking/src/main/java/com/jme3/network/service/rmi/ClassInfoRegistry.java @@ -52,10 +52,19 @@ public class ClassInfoRegistry { private final AtomicInteger nextClassId = new AtomicInteger(); private final ReadWriteLock lock = new ReentrantReadWriteLock(); + /** + * Creates an empty registry for shared class metadata. + */ public ClassInfoRegistry() { //this.cache = CacheBuilder.newBuilder().build(new ClassInfoLoader()); // Guava version } + /** + * Returns cached metadata for a shared type, creating it on first access. + * + * @param type the shared interface type + * @return the cached class metadata + */ public ClassInfo getClassInfo( Class type ) { //return cache.getUnchecked(type); // Guava version diff --git a/jme3-networking/src/main/java/com/jme3/network/service/rmi/MethodInfo.java b/jme3-networking/src/main/java/com/jme3/network/service/rmi/MethodInfo.java index 050bc21c1c..68d0ef8df9 100644 --- a/jme3-networking/src/main/java/com/jme3/network/service/rmi/MethodInfo.java +++ b/jme3-networking/src/main/java/com/jme3/network/service/rmi/MethodInfo.java @@ -47,6 +47,9 @@ @Serializable public final class MethodInfo { + /** + * Sentinel used to represent a null method info entry. + */ public static final MethodInfo NULL_INFO = new MethodInfo(); private String representation; @@ -60,6 +63,12 @@ public final class MethodInfo { public MethodInfo() { } + /** + * Creates metadata for a shared method. + * + * @param id the shared method id + * @param m the reflected method + */ public MethodInfo( short id, Method m ) { this.id = id; this.method = m; @@ -67,6 +76,13 @@ public MethodInfo( short id, Method m ) { this.callType = getCallType(m); } + /** + * Invokes the reflected method on the specified target. + * + * @param target the invocation target + * @param parms the invocation parameters + * @return the invocation result + */ public Object invoke( Object target, Object... parms ) { try { return method.invoke(target, parms); @@ -77,18 +93,40 @@ public Object invoke( Object target, Object... parms ) { } } + /** + * Returns the shared method id. + * + * @return the method id + */ public short getId() { return id; } + /** + * Returns the call type for the shared method. + * + * @return the call type + */ public CallType getCallType() { return callType; } + /** + * Returns true if the reflected method matches this method metadata. + * + * @param m the reflected method to compare + * @return true if the method signatures match + */ public boolean matches( Method m ) { return representation.equals(methodToString(m)); } + /** + * Converts a reflected method into its serialized signature representation. + * + * @param m the reflected method + * @return the serialized signature + */ public static String methodToString( Method m ) { StringBuilder sb = new StringBuilder(); for( Class t : m.getParameterTypes() ) { @@ -99,6 +137,12 @@ public static String methodToString( Method m ) { return m.getReturnType().getName() + " " + m.getName() + "(" + sb + ")"; } + /** + * Resolves the call type for a reflected method. + * + * @param m the reflected method + * @return the call type + */ public static CallType getCallType( Method m ) { if( m.getReturnType() != Void.TYPE ) { return CallType.Synchronous; diff --git a/jme3-networking/src/main/java/com/jme3/network/service/rmi/RemoteObjectHandler.java b/jme3-networking/src/main/java/com/jme3/network/service/rmi/RemoteObjectHandler.java index f1c168ac53..701cba3a87 100644 --- a/jme3-networking/src/main/java/com/jme3/network/service/rmi/RemoteObjectHandler.java +++ b/jme3-networking/src/main/java/com/jme3/network/service/rmi/RemoteObjectHandler.java @@ -51,6 +51,14 @@ public class RemoteObjectHandler implements InvocationHandler { private final ClassInfo typeInfo; private final Map methodIndex = new ConcurrentHashMap<>(); + /** + * Creates a remote object invocation handler. + * + * @param rmi the owning registry + * @param channel the network channel to use + * @param objectId the remote object id + * @param typeInfo the shared type metadata + */ public RemoteObjectHandler( RmiRegistry rmi, byte channel, short objectId, ClassInfo typeInfo ) { this.rmi = rmi; this.channel = channel; @@ -58,6 +66,12 @@ public RemoteObjectHandler( RmiRegistry rmi, byte channel, short objectId, Class this.typeInfo = typeInfo; } + /** + * Resolves cached method metadata for a reflected method. + * + * @param method the reflected method + * @return the method metadata, or null if none matches + */ protected MethodInfo getMethodInfo( Method method ) { MethodInfo mi = methodIndex.get(method); if( mi == null ) { diff --git a/jme3-networking/src/main/java/com/jme3/network/service/rmi/RmiClientService.java b/jme3-networking/src/main/java/com/jme3/network/service/rmi/RmiClientService.java index 0dc3eac2be..85a294a9a7 100644 --- a/jme3-networking/src/main/java/com/jme3/network/service/rmi/RmiClientService.java +++ b/jme3-networking/src/main/java/com/jme3/network/service/rmi/RmiClientService.java @@ -71,10 +71,19 @@ public class RmiClientService extends AbstractClientService { private final List pending = new ArrayList<>(); + /** + * Creates an RMI client service using the default object id and reliable channel. + */ public RmiClientService() { this((short)-1, (byte)MessageConnection.CHANNEL_DEFAULT_RELIABLE); } + /** + * Creates an RMI client service. + * + * @param rmiObjectId the shared RMI object id + * @param defaultChannel the default network channel for RMI traffic + */ public RmiClientService( short rmiObjectId, byte defaultChannel ) { this.defaultChannel = defaultChannel; this.rmiObjectId = rmiObjectId; @@ -84,6 +93,10 @@ public RmiClientService( short rmiObjectId, byte defaultChannel ) { * Shares the specified object with the server and associates it with the * specified type. Objects shared in this way are available in the connection-specific * RMI registry on the server and are not available to other connections. + * + * @param the shared object type + * @param object the object to share + * @param type the shared interface type */ public void share( T object, Class type ) { share(defaultChannel, object, type); @@ -95,6 +108,11 @@ public void share( T object, Class type ) { * RMI registry on the server and are not available to other connections. * All object related communication will be done over the specified connection * channel. + * + * @param the shared object type + * @param channel the network channel to use + * @param object the object to share + * @param type the shared interface type */ public void share( byte channel, T object, Class type ) { share(channel, type.getName(), object, type); @@ -104,6 +122,11 @@ public void share( byte channel, T object, Class type ) { * Shares the specified object with the server and associates it with the * specified name. Objects shared in this way are available in the connection-specific * RMI registry on the server and are not available to other connections. + * + * @param the shared object type + * @param name the exported object name + * @param object the object to share + * @param type the shared interface type */ public void share( String name, T object, Class type ) { share(defaultChannel, name, object, type); @@ -115,6 +138,12 @@ public void share( String name, T object, Class type ) { * RMI registry on the server and are not available to other connections. * All object related communication will be done over the specified connection * channel. + * + * @param the shared object type + * @param channel the network channel to use + * @param name the exported object name + * @param object the object to share + * @param type the shared interface type */ public void share( byte channel, String name, T object, Class type ) { if( !isStarted ) { @@ -133,6 +162,10 @@ public void share( byte channel, String name, T object, Class typ /** * Looks up a remote object on the server by type and returns a local proxy to the * remote object that was shared on the other end of the network connection. + * + * @param the requested proxy type + * @param type the shared interface type + * @return the remote object proxy */ public T getRemoteObject( Class type ) { return rmi.getRemoteObject(type); @@ -141,6 +174,11 @@ public T getRemoteObject( Class type ) { /** * Looks up a remote object on the server by name and returns a local proxy to the * remote object that was shared on the other end of the network connection. + * + * @param the requested proxy type + * @param name the exported object name + * @param type the shared interface type + * @return the remote object proxy */ public T getRemoteObject( String name, Class type ) { return rmi.getRemoteObject(name, type); diff --git a/jme3-networking/src/main/java/com/jme3/network/service/rmi/RmiContext.java b/jme3-networking/src/main/java/com/jme3/network/service/rmi/RmiContext.java index de19304561..58b98f0964 100644 --- a/jme3-networking/src/main/java/com/jme3/network/service/rmi/RmiContext.java +++ b/jme3-networking/src/main/java/com/jme3/network/service/rmi/RmiContext.java @@ -55,6 +55,8 @@ private RmiContext() { /** * Returns the HostedConnection that is responsible for any * RMI-related calls on this thread. + * + * @return the current RMI caller connection, or null if none is set */ public static HostedConnection getRmiConnection() { return connection.get(); diff --git a/jme3-networking/src/main/java/com/jme3/network/service/rmi/RmiHostedService.java b/jme3-networking/src/main/java/com/jme3/network/service/rmi/RmiHostedService.java index 5e7effff07..3e6f057fb9 100644 --- a/jme3-networking/src/main/java/com/jme3/network/service/rmi/RmiHostedService.java +++ b/jme3-networking/src/main/java/com/jme3/network/service/rmi/RmiHostedService.java @@ -77,6 +77,9 @@ public class RmiHostedService extends AbstractHostedService { private static final Logger log = Logger.getLogger(RpcHostedService.class.getName()); + /** + * Hosted connection attribute used to store the connection-specific RMI registry. + */ public static final String ATTRIBUTE_NAME = "rmi"; private RpcHostedService rpcService; @@ -85,14 +88,29 @@ public class RmiHostedService extends AbstractHostedService { private boolean autoHost; private final Map globalShares = new ConcurrentHashMap<>(); + /** + * Creates an RMI hosted service using the default object id and reliable channel. + */ public RmiHostedService() { this((short)-1, (byte)MessageConnection.CHANNEL_DEFAULT_RELIABLE, true); } + /** + * Creates an RMI hosted service using the specified default channel. + * + * @param defaultChannel the default network channel for RMI traffic + */ public RmiHostedService( byte defaultChannel ) { this((short)-1, defaultChannel, true); } + /** + * Creates an RMI hosted service. + * + * @param rmiId the shared RMI object id + * @param defaultChannel the default network channel for RMI traffic + * @param autoHost true to start hosting automatically for new connections + */ public RmiHostedService( short rmiId, byte defaultChannel, boolean autoHost ) { this.rmiId = rmiId; this.defaultChannel = defaultChannel; @@ -106,6 +124,10 @@ public RmiHostedService( short rmiId, byte defaultChannel, boolean autoHost ) { * with RMI hosting started will have access to this shared object as soon as they * connect, and they will all share the same instance. It is up to the shared object * to handle any multithreading that might be required. + * + * @param the shared object type + * @param object the object to share + * @param type the shared interface type */ public void shareGlobal( T object, Class type ) { shareGlobal(defaultChannel, type.getName(), object, type); @@ -116,6 +138,11 @@ public void shareGlobal( T object, Class type ) { * with RMI hosting started will have access to this shared object as soon as they * connect, and they will all share the same instance. It is up to the shared object * to handle any multithreading that might be required. + * + * @param the shared object type + * @param name the exported object name + * @param object the object to share + * @param type the shared interface type */ public void shareGlobal( String name, T object, Class type ) { shareGlobal(defaultChannel, name, object, type); @@ -128,6 +155,12 @@ public void shareGlobal( String name, T object, Class type ) { * to the shared object to handle any multithreading that might be required. * All network communication associated with the shared object will be done over * the specified channel. + * + * @param the shared object type + * @param channel the network channel to use + * @param name the exported object name + * @param object the object to share + * @param type the shared interface type */ public void shareGlobal( byte channel, String name, T object, Class type ) { GlobalShare share = new GlobalShare(channel, object, type); @@ -154,6 +187,8 @@ public void shareGlobal( byte channel, String name, T object, Class the shared object type + * @param object the object to share + * @param type the shared interface type */ public void share( T object, Class type ) { share(defaultChannel, object, type); @@ -102,6 +121,11 @@ public void share( T object, Class type ) { * The object can be looked up by type on the other end. * The specified channel will be used for all network communication * specific to this object. + * + * @param the shared object type + * @param channel the network channel to use + * @param object the object to share + * @param type the shared interface type */ public void share( byte channel, T object, Class type ) { share(channel, type.getName(), object, type); @@ -112,6 +136,11 @@ public void share( byte channel, T object, Class type ) { * the specified interface type and associates it with the specified name. * The object can be looked up by the associated name on the other end of * the connection. + * + * @param the shared object type + * @param name the exported object name + * @param object the object to share + * @param type the shared interface type */ public void share( String name, T object, Class type ) { share(defaultChannel, name, object, type); @@ -125,6 +154,12 @@ public void share( String name, T object, Class type ) { * the connection. * The specified channel will be used for all network communication * specific to this object. + * + * @param the shared object type + * @param channel the network channel to use + * @param name the exported object name + * @param object the object to share + * @param type the shared interface type */ public void share( byte channel, String name, T object, Class type ) { @@ -182,6 +217,10 @@ public void share( byte channel, String name, T object, Class typ /** * Returns a local object that was previously registered with share() using * just type registration. + * + * @param the requested object type + * @param type the shared interface type + * @return the shared local object */ public T getLocalObject( Class type ) { return getLocalObject(type.getName(), type); @@ -190,6 +229,11 @@ public T getLocalObject( Class type ) { /** * Returns a local object that was previously registered with share() using * name registration. + * + * @param the requested object type + * @param name the exported object name + * @param type the shared interface type + * @return the shared local object */ public T getLocalObject( String name, Class type ) { local.lock.readLock().lock(); @@ -206,6 +250,10 @@ public T getLocalObject( String name, Class type ) { * from a client then it is accessing a shared object registered on the server. * If this is called from the server then it is accessing a shared object registered * on the client. + * + * @param the requested proxy type + * @param type the shared interface type + * @return the remote object proxy */ public T getRemoteObject( Class type ) { return getRemoteObject(type.getName(), type); @@ -217,6 +265,11 @@ public T getRemoteObject( Class type ) { * from a client then it is accessing a shared object registered on the server. * If this is called from the server then it is accessing a shared object registered * on the client. + * + * @param the requested proxy type + * @param name the exported object name + * @param type the shared interface type + * @return the remote object proxy */ public T getRemoteObject( String name, Class type ) { remote.lock.readLock().lock(); @@ -227,12 +280,22 @@ public T getRemoteObject( String name, Class type ) { } } + /** + * Registers remote class metadata announced by the far end. + * + * @param info the remote class metadata + */ protected void addRemoteClass( ClassInfo info ) { if( remote.classes.put(info.getId(), info) != null ) { throw new RuntimeException("Error class already exists for ID:" + info.getId()); } } + /** + * Removes a previously registered remote object. + * + * @param objectId the remote object id + */ protected void removeRemoteObject( short objectId ) { if( log.isLoggable(Level.FINEST) ) { log.log(Level.FINEST, "removeRemoteObject({0})", objectId); @@ -240,6 +303,14 @@ protected void removeRemoteObject( short objectId ) { throw new UnsupportedOperationException("Removal not yet implemented."); } + /** + * Registers a remote object proxy from metadata received over the wire. + * + * @param channel the message channel used for method calls + * @param objectId the remote object id + * @param name the exported object name + * @param typeInfo the remote object type metadata + */ protected void addRemoteObject( byte channel, short objectId, String name, ClassInfo typeInfo ) { if( log.isLoggable(Level.FINEST) ) { log.finest("addRemoveObject(" + objectId + ", " + name + ", " + typeInfo + ")"); @@ -264,6 +335,16 @@ protected void addRemoteObject( byte channel, short objectId, String name, Class } } + /** + * Invokes a remote procedure through the configured RPC layer. + * + * @param channel the message channel to use + * @param objectId the remote object id + * @param procId the remote procedure id + * @param callType the invocation mode + * @param args the invocation arguments + * @return the remote return value for synchronous calls, or {@code null} otherwise + */ protected Object invokeRemote( byte channel, short objectId, short procId, CallType callType, Object[] args ) { if( log.isLoggable(Level.FINEST) ) { log.finest("invokeRemote(" + channel + ", " + objectId + ", " + procId + ", " @@ -291,6 +372,9 @@ protected Object invokeRemote( byte channel, short objectId, short procId, CallT /** * Handle remote object registry updates from the other end. + * + * @param procId the registry update procedure id + * @param args the registry update arguments */ protected void rmiUpdate( short procId, Object[] args ) { if( log.isLoggable(Level.FINEST) ) { @@ -312,6 +396,11 @@ protected void rmiUpdate( short procId, Object[] args ) { /** * Handle the actual remote object method calls. + * + * @param objectId the shared object id + * @param procId the procedure id + * @param args the invocation arguments + * @return the invocation result */ protected Object invokeLocal( short objectId, short procId, Object[] args ) { // Actually could use a regular concurrent map for this diff --git a/jme3-networking/src/main/java/com/jme3/network/service/rpc/RpcClientService.java b/jme3-networking/src/main/java/com/jme3/network/service/rpc/RpcClientService.java index c8e44e33cf..85cfefb5b6 100644 --- a/jme3-networking/src/main/java/com/jme3/network/service/rpc/RpcClientService.java +++ b/jme3-networking/src/main/java/com/jme3/network/service/rpc/RpcClientService.java @@ -64,6 +64,8 @@ public RpcClientService() { * Returns the underlying RPC connection for use by other * services that may require a more generic non-client/server * specific RPC object with which to interact. + * + * @return the underlying RPC connection */ public RpcConnection getRpcConnection() { return rpc; @@ -97,6 +99,12 @@ public void terminate( ClientServiceManager serviceManager ) { * Performs a synchronous call on the server against the specified * object using the specified procedure ID. Both inbound and outbound * communication is done on the specified channel. + * + * @param channel the channel to use + * @param objId the target object id + * @param procId the target procedure id + * @param args the invocation arguments + * @return the invocation result */ public Object callAndWait( byte channel, short objId, short procId, Object... args ) { return rpc.callAndWait(channel, objId, procId, args); @@ -107,6 +115,11 @@ public Object callAndWait( byte channel, short objId, short procId, Object... ar * object using the specified procedure ID. Communication is done * over the specified channel. No responses are received and none * are waited for. + * + * @param channel the channel to use + * @param objId the target object id + * @param procId the target procedure id + * @param args the invocation arguments */ public void callAsync( byte channel, short objId, short procId, Object... args ) { rpc.callAsync(channel, objId, procId, args); @@ -118,6 +131,9 @@ public void callAsync( byte channel, short objId, short procId, Object... args ) * Only one handler per object ID can be registered at any given time, * though the same handler can be registered for multiple object * IDs. + * + * @param objId the target object id + * @param handler the handler to register */ public void registerHandler( short objId, RpcHandler handler ) { rpc.registerHandler(objId, handler); @@ -126,6 +142,9 @@ public void registerHandler( short objId, RpcHandler handler ) { /** * Removes a previously registered handler for the specified * object ID. + * + * @param objId the target object id + * @param handler the handler to remove */ public void removeHandler( short objId, RpcHandler handler ) { rpc.removeHandler(objId, handler); diff --git a/jme3-networking/src/main/java/com/jme3/network/service/rpc/RpcConnection.java b/jme3-networking/src/main/java/com/jme3/network/service/rpc/RpcConnection.java index d8a71358df..48a0f6eb3e 100644 --- a/jme3-networking/src/main/java/com/jme3/network/service/rpc/RpcConnection.java +++ b/jme3-networking/src/main/java/com/jme3/network/service/rpc/RpcConnection.java @@ -82,6 +82,8 @@ public class RpcConnection { /** * Creates a new RpcConnection for the specified network connection. + * + * @param connection the backing message connection */ public RpcConnection( MessageConnection connection ) { this.connection = connection; @@ -102,6 +104,12 @@ public void close() { * Performs a remote procedure call with the specified arguments and waits * for the response. Both the outbound message and inbound response will * be sent on the specified channel. + * + * @param channel the channel to use + * @param objId the target object id + * @param procId the target procedure id + * @param args the invocation arguments + * @return the invocation result */ public Object callAndWait( byte channel, short objId, short procId, Object... args ) { @@ -134,6 +142,11 @@ public Object callAndWait( byte channel, short objId, short procId, Object... ar * Performs a remote procedure call with the specified arguments but does * not wait for a response. The outbound message is sent on the specified channel. * There is no inbound response message. + * + * @param channel the channel to use + * @param objId the target object id + * @param procId the target procedure id + * @param args the invocation arguments */ public void callAsync( byte channel, short objId, short procId, Object... args ) { @@ -150,6 +163,9 @@ public void callAsync( byte channel, short objId, short procId, Object... args ) * handler per object ID can be registered at any given time, * though the same handler can be registered for multiple object * IDs. + * + * @param objId the target object id + * @param handler the handler to register */ public void registerHandler( short objId, RpcHandler handler ) { handlers.put(objId, handler); @@ -158,6 +174,9 @@ public void registerHandler( short objId, RpcHandler handler ) { /** * Removes a previously registered handler for the specified * object ID. + * + * @param objId the target object id + * @param handler the handler to remove */ public void removeHandler( short objId, RpcHandler handler ) { RpcHandler removing = handlers.get(objId); @@ -168,6 +187,12 @@ public void removeHandler( short objId, RpcHandler handler ) { handlers.remove(objId); } + /** + * Sends an RPC response on the specified channel. + * + * @param channel the channel to use + * @param msg the response message + */ protected void send( byte channel, RpcResponseMessage msg ) { if( channel >= 0 ) { connection.send(channel, msg); @@ -179,6 +204,8 @@ protected void send( byte channel, RpcResponseMessage msg ) { /** * Called internally when an RpcCallMessage is received from * the remote connection. + * + * @param msg the received RPC call */ public void handleMessage( RpcCallMessage msg ) { @@ -206,6 +233,8 @@ public void handleMessage( RpcCallMessage msg ) { /** * Called internally when an RpcResponseMessage is received from * the remote connection. + * + * @param msg the received RPC response */ public void handleMessage( RpcResponseMessage msg ) { if( log.isLoggable(Level.FINEST) ) { diff --git a/jme3-networking/src/main/java/com/jme3/network/service/rpc/RpcHandler.java b/jme3-networking/src/main/java/com/jme3/network/service/rpc/RpcHandler.java index d7d99981d7..2d2a81e0f3 100644 --- a/jme3-networking/src/main/java/com/jme3/network/service/rpc/RpcHandler.java +++ b/jme3-networking/src/main/java/com/jme3/network/service/rpc/RpcHandler.java @@ -45,6 +45,12 @@ public interface RpcHandler { /** * Called when a remote procedure call request is received for a particular * object from the other end of the network connection. + * + * @param conn the RPC connection handling the call + * @param objectId the target object id + * @param procId the target procedure id + * @param args the invocation arguments + * @return the invocation result */ public Object call( RpcConnection conn, short objectId, short procId, Object... args ); } diff --git a/jme3-networking/src/main/java/com/jme3/network/service/rpc/RpcHostedService.java b/jme3-networking/src/main/java/com/jme3/network/service/rpc/RpcHostedService.java index 22b2e53e0c..3e4087399e 100644 --- a/jme3-networking/src/main/java/com/jme3/network/service/rpc/RpcHostedService.java +++ b/jme3-networking/src/main/java/com/jme3/network/service/rpc/RpcHostedService.java @@ -84,6 +84,8 @@ public RpcHostedService() { * with the Network server and will optionally 'host' * RPC services and each new network connection depending * on the specified 'autoHost' flag. + * + * @param autoHost true to automatically host RPC on new connections */ public RpcHostedService( boolean autoHost ) { super(autoHost); @@ -120,6 +122,9 @@ protected void onInitialize( HostedServiceManager serviceManager ) { * startHostingOnConnection() (or via autohosting). Returns null * if the connection currently doesn't have RPC hosting services * attached. + * + * @param hc the hosted connection + * @return the RPC connection, or null if not hosted */ public RpcConnection getRpcConnection( HostedConnection hc ) { return hc.getAttribute(ATTRIBUTE_NAME); diff --git a/jme3-networking/src/main/java/com/jme3/network/service/rpc/msg/RpcCallMessage.java b/jme3-networking/src/main/java/com/jme3/network/service/rpc/msg/RpcCallMessage.java index 11c5db591d..09db55a834 100644 --- a/jme3-networking/src/main/java/com/jme3/network/service/rpc/msg/RpcCallMessage.java +++ b/jme3-networking/src/main/java/com/jme3/network/service/rpc/msg/RpcCallMessage.java @@ -51,9 +51,21 @@ public class RpcCallMessage extends AbstractMessage { private short procId; private Object[] args; + /** + * Creates an empty RPC call message for serialization. + */ public RpcCallMessage() { } + /** + * Creates an RPC call message. + * + * @param msgId the RPC message id, or {@code -1} for async calls + * @param channel the channel used to send the invocation + * @param objId the remote object id + * @param procId the remote procedure id + * @param args the invocation arguments + */ public RpcCallMessage( long msgId, byte channel, short objId, short procId, Object... args ) { this.msgId = msgId; this.channel = channel; @@ -62,26 +74,56 @@ public RpcCallMessage( long msgId, byte channel, short objId, short procId, Obje this.args = args; } + /** + * Returns the RPC message id. + * + * @return the RPC message id + */ public long getMessageId() { return msgId; } + /** + * Returns the channel used for the invocation. + * + * @return the invocation channel + */ public byte getChannel() { return channel; } + /** + * Returns whether this call is asynchronous. + * + * @return true if the call does not expect a response + */ public boolean isAsync() { return msgId == -1; } + /** + * Returns the remote object id. + * + * @return the remote object id + */ public short getObjectId() { return objId; } + /** + * Returns the remote procedure id. + * + * @return the remote procedure id + */ public short getProcedureId() { return procId; } + /** + * Returns the invocation arguments. + * + * @return the invocation arguments + */ public Object[] getArguments() { return args; } diff --git a/jme3-networking/src/main/java/com/jme3/network/service/rpc/msg/RpcResponseMessage.java b/jme3-networking/src/main/java/com/jme3/network/service/rpc/msg/RpcResponseMessage.java index 8e15514e73..e370ad489c 100644 --- a/jme3-networking/src/main/java/com/jme3/network/service/rpc/msg/RpcResponseMessage.java +++ b/jme3-networking/src/main/java/com/jme3/network/service/rpc/msg/RpcResponseMessage.java @@ -53,14 +53,29 @@ public class RpcResponseMessage extends AbstractMessage { private String error; private Object exception; // if it was serializable + /** + * Creates an empty RPC response message for serialization. + */ public RpcResponseMessage() { } + /** + * Creates a successful RPC response message. + * + * @param msgId the response message id + * @param result the invocation result + */ public RpcResponseMessage( long msgId, Object result ) { this.msgId = msgId; this.result = result; } + /** + * Creates a failed RPC response message. + * + * @param msgId the response message id + * @param t the error raised while processing the invocation + */ public RpcResponseMessage( long msgId, Throwable t ) { this.msgId = msgId; @@ -78,6 +93,12 @@ public RpcResponseMessage( long msgId, Throwable t ) { } } + /** + * Returns whether the throwable chain can be serialized directly. + * + * @param error the throwable to inspect + * @return true if the throwable chain is serializable + */ public static boolean isSerializable( Throwable error ) { if( error == null ) { return false; @@ -90,18 +111,38 @@ public static boolean isSerializable( Throwable error ) { return true; } + /** + * Returns the RPC response message id. + * + * @return the response message id + */ public long getMessageId() { return msgId; } + /** + * Returns the invocation result. + * + * @return the invocation result, or {@code null} + */ public Object getResult() { return result; } + /** + * Returns the serialized error text, if any. + * + * @return the serialized error text, or {@code null} + */ public String getError() { return error; } + /** + * Returns the serialized throwable, if present. + * + * @return the serialized throwable, or {@code null} + */ public Throwable getThrowable() { return (Throwable)exception; } diff --git a/jme3-networking/src/main/java/com/jme3/network/service/serializer/ClientSerializerRegistrationsService.java b/jme3-networking/src/main/java/com/jme3/network/service/serializer/ClientSerializerRegistrationsService.java index ea4595947c..b9d0c9ab92 100644 --- a/jme3-networking/src/main/java/com/jme3/network/service/serializer/ClientSerializerRegistrationsService.java +++ b/jme3-networking/src/main/java/com/jme3/network/service/serializer/ClientSerializerRegistrationsService.java @@ -44,7 +44,7 @@ /** - * + * Receives serializer registration updates from the server and applies them on the client. * * @author Paul Speed */ @@ -53,6 +53,12 @@ public class ClientSerializerRegistrationsService extends AbstractClientService private static final Logger log = Logger.getLogger(SerializerRegistrationsMessage.class.getName()); + /** + * Creates the client-side serializer registration service. + */ + public ClientSerializerRegistrationsService() { + } + @Override protected void onInitialize( ClientServiceManager serviceManager ) { diff --git a/jme3-networking/src/main/java/com/jme3/network/service/serializer/ServerSerializerRegistrationsService.java b/jme3-networking/src/main/java/com/jme3/network/service/serializer/ServerSerializerRegistrationsService.java index 8af8395c38..398d1152f5 100644 --- a/jme3-networking/src/main/java/com/jme3/network/service/serializer/ServerSerializerRegistrationsService.java +++ b/jme3-networking/src/main/java/com/jme3/network/service/serializer/ServerSerializerRegistrationsService.java @@ -41,11 +41,16 @@ /** - * + * Prepares and sends serializer registration data to connecting clients. * * @author Paul Speed */ public class ServerSerializerRegistrationsService extends AbstractHostedService { + /** + * Creates the serializer registration service. + */ + public ServerSerializerRegistrationsService() { + } @Override protected void onInitialize( HostedServiceManager serviceManager ) { diff --git a/jme3-networking/src/main/java/com/jme3/network/util/AbstractMessageDelegator.java b/jme3-networking/src/main/java/com/jme3/network/util/AbstractMessageDelegator.java index 2eba38e444..23cedb5b80 100644 --- a/jme3-networking/src/main/java/com/jme3/network/util/AbstractMessageDelegator.java +++ b/jme3-networking/src/main/java/com/jme3/network/util/AbstractMessageDelegator.java @@ -52,6 +52,7 @@ * specified. Subclasses provide specific implementations for how to * find the actual delegate object. * + * @param the message connection type handled by this delegator * @author Paul Speed */ public abstract class AbstractMessageDelegator @@ -68,6 +69,9 @@ public abstract class AbstractMessageDelegator * messages to methods of the specified delegate type. If automap * is true then reflection is used to lookup probably message handling * methods. + * + * @param delegateType the delegate class that contains handler methods + * @param automap true to scan the delegate type for handler methods immediately */ protected AbstractMessageDelegator( Class delegateType, boolean automap ) { this.delegateType = delegateType; @@ -79,6 +83,8 @@ protected AbstractMessageDelegator( Class delegateType, boolean automap ) { /** * Returns the array of messages known to be handled by this message * delegator. + * + * @return the message types currently mapped to delegate methods */ public Class[] getMessageTypes() { if( messageTypes == null ) { @@ -93,6 +99,10 @@ public Class[] getMessageTypes() { * provide implementation specific filtering of methods. * This implementation checks for methods that take either the connection and message * type arguments (in that order) or just the message type. + * + * @param m the method to test + * @param messageType the expected message type, or null to accept any {@link Message} + * @return true if the method can handle the specified message type */ protected boolean isValidMethod( Method m, Class messageType ) { @@ -135,6 +145,9 @@ protected boolean isValidMethod( Method m, Class messageType ) { * getParameterTypes() array, thus supporting both * method(connection, messageType) and method(messageType) * calling forms. + * + * @param m the method to inspect + * @return the message type accepted by the method */ protected Class getMessageType( Method m ) { Class[] parms = m.getParameterTypes(); @@ -145,6 +158,10 @@ protected Class getMessageType( Method m ) { * Goes through all of the delegate type's methods to find * a method of the specified name that may take the specified * message type. + * + * @param name the method name to search for + * @param messageType the message type the delegate method should accept + * @return the matching method, or null if none is found */ protected Method findDelegate( String name, Class messageType ) { // We do an exhaustive search because it's easier to @@ -169,6 +186,9 @@ protected Method findDelegate( String name, Class messageType ) { * This is used by automapping to determine if a method * should be rejected purely on name. Default implementation * always returns true. + * + * @param name the method name to evaluate + * @return true if the name is eligible for automapping */ protected boolean allowName( String name ) { return true; @@ -188,6 +208,9 @@ protected final void automap() { /** * Specifically maps the specified methods names, autowiring * the parameters. + * + * @param methodNames the delegate method names to map + * @return this delegator for chaining */ public AbstractMessageDelegator map( String... methodNames ) { Set names = new HashSet<>( Arrays.asList(methodNames) ); @@ -205,6 +228,8 @@ public AbstractMessageDelegator map( String... methodNames ) { * isValidMethod() is called with a null message type argument. * All methods are made accessible thus supporting non-public * methods as well as public methods. + * + * @param constraints the allowed method names, or null to use {@link #allowName(String)} */ protected void map( Set constraints ) { @@ -241,6 +266,10 @@ protected void map( Set constraints ) { /** * Manually maps a specified method to the specified message type. + * + * @param messageType the message type to map + * @param methodName the delegate method name to invoke for that type + * @return this delegator for chaining */ public AbstractMessageDelegator map( Class messageType, String methodName ) { // Lookup the method @@ -261,6 +290,9 @@ public AbstractMessageDelegator map( Class messageType, String methodName ) { /** * Returns the mapped method for the specified message type. + * + * @param c the message type + * @return the mapped method, or null if none is registered */ protected Method getMethod( Class c ) { Method m = methods.get(c); @@ -270,6 +302,9 @@ protected Method getMethod( Class c ) { /** * Implemented by subclasses to provide the actual delegate object * against which the mapped message type methods will be called. + * + * @param source the source connection associated with the message + * @return the delegate object to invoke, or null to ignore the message */ protected abstract Object getSourceDelegate( S source ); diff --git a/jme3-networking/src/main/java/com/jme3/network/util/ObjectMessageDelegator.java b/jme3-networking/src/main/java/com/jme3/network/util/ObjectMessageDelegator.java index f0e45dd2e3..6d746d338f 100644 --- a/jme3-networking/src/main/java/com/jme3/network/util/ObjectMessageDelegator.java +++ b/jme3-networking/src/main/java/com/jme3/network/util/ObjectMessageDelegator.java @@ -40,6 +40,7 @@ * of a specified delegate object. These methods can be automapped or manually * specified. * + * @param the message connection type handled by this delegator * @author Paul Speed */ public class ObjectMessageDelegator extends AbstractMessageDelegator { @@ -58,6 +59,9 @@ public class ObjectMessageDelegator extends Abstrac * * Where S is the type of MessageConnection and SomeMessage is some * specific concrete Message subclass. + * + * @param delegate the object that will receive forwarded calls + * @param automap true to automatically map compatible methods on the delegate */ public ObjectMessageDelegator( Object delegate, boolean automap ) { super(delegate.getClass(), automap); diff --git a/jme3-networking/src/main/java/com/jme3/network/util/SessionDataDelegator.java b/jme3-networking/src/main/java/com/jme3/network/util/SessionDataDelegator.java index 26d809df83..69333d3c46 100644 --- a/jme3-networking/src/main/java/com/jme3/network/util/SessionDataDelegator.java +++ b/jme3-networking/src/main/java/com/jme3/network/util/SessionDataDelegator.java @@ -64,6 +64,10 @@ public class SessionDataDelegator extends AbstractMessageDelegator * Where S is the type of MessageConnection and SomeMessage is some * specific concrete Message subclass. + * + * @param delegateType the delegate class containing message handlers + * @param attributeName the session attribute that stores the delegate + * @param automap true to map methods automatically */ public SessionDataDelegator( Class delegateType, String attributeName, boolean automap ) { super(delegateType, automap); @@ -73,6 +77,8 @@ public SessionDataDelegator( Class delegateType, String attributeName, boolean a /** * Returns the attribute name that will be used to look up the * delegate object. + * + * @return the session attribute name used to locate delegates */ public String getAttributeName() { return attributeName; @@ -82,6 +88,8 @@ public String getAttributeName() { * Called internally when there is no session object * for the current attribute name attached to the passed source * HostConnection. Default implementation logs a warning. + * + * @param source the connection whose delegate lookup failed */ protected void miss( HostedConnection source ) { log.log(Level.WARNING, "Session data is null for:{0} on connection:{1}", new Object[]{attributeName, source});