dorkbox/Network
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

JavaDoc polish

Browse Source
This commit is contained in:
nathan 2018-01-14 00:20:54 +01:00
parent 0395f62ac0
commit e708d56062
3 changed files with 72 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
src/dorkbox/network/connection/EndPointBase.java
View File

@ -115,7 +115,7 @@ class EndPointBase<C extends Connection> extends EndPoint {
/** /**
* @param type this is either "Client" or "Server", depending on who is creating this endpoint. * @param type this is either "Client" or "Server", depending on who is creating this endpoint.
* @param config these are the specific connection options * @param config these are the specific connection options
* *
* @throws InitializationException * @throws InitializationException

78
src/dorkbox/network/serialization/RmiSerializationManager.java
View File

@ -26,58 +26,53 @@ public
interface RmiSerializationManager extends SerializationManager { interface RmiSerializationManager extends SerializationManager {
/** /**
* Registers the class using the lowest, next available integer ID and the * Registers the class using the lowest, next available integer ID and the {@link Kryo#getDefaultSerializer(Class) default serializer}.
* {@link Kryo#getDefaultSerializer(Class) default serializer}. If the class * If the class is already registered, the existing entry is updated with the new serializer.
* is already registered, the existing entry is updated with the new * <p>
* serializer. Registering a primitive also affects the corresponding * Registering a primitive also affects the corresponding primitive wrapper.
* primitive wrapper. * <p>
* <p/> * Because the ID assigned is affected by the IDs registered before it, the order classes are registered is important when using this
* Because the ID assigned is affected by the IDs registered before it, the * method. The order must be the same at deserialization as it was for serialization.
* order classes are registered is important when using this method. The
* order must be the same at deserialization as it was for serialization.
*/ */
@Override @Override
RmiSerializationManager register(Class<?> clazz); RmiSerializationManager register(Class<?> clazz);
/** /**
* Registers the class using the specified ID. If the ID is * Registers the class using the specified ID. If the ID is already in use by the same type, the old entry is overwritten. If the ID
* already in use by the same type, the old entry is overwritten. If the ID
* is already in use by a different type, a {@link KryoException} is thrown. * is already in use by a different type, a {@link KryoException} is thrown.
* <p>
* Registering a primitive also affects the corresponding primitive wrapper. * Registering a primitive also affects the corresponding primitive wrapper.
* <p/> * <p>
* IDs must be the same at deserialization as they were for serialization. * IDs must be the same at deserialization as they were for serialization.
* *
* @param id Must be >= 0. Smaller IDs are serialized more efficiently. IDs * @param id Must be >= 0. Smaller IDs are serialized more efficiently. IDs 0-8 are used by default for primitive types and String, but
* 0-8 are used by default for primitive types and String, but * these IDs can be repurposed.
* these IDs can be repurposed.
*/ */
@Override @Override
RmiSerializationManager register(Class<?> clazz, int id); RmiSerializationManager register(Class<?> clazz, int id);
/** /**
* Registers the class using the lowest, next available integer ID and the * Registers the class using the lowest, next available integer ID and the specified serializer. If the class is already registered,
* specified serializer. If the class is already registered, the existing * the existing entry is updated with the new serializer.
* entry is updated with the new serializer. Registering a primitive also * <p>
* affects the corresponding primitive wrapper. * Registering a primitive also affects the corresponding primitive wrapper.
* <p/> * <p>
* Because the ID assigned is affected by the IDs registered before it, the * Because the ID assigned is affected by the IDs registered before it, the order classes are registered is important when using this
* order classes are registered is important when using this method. The * method. The order must be the same at deserialization as it was for serialization.
* order must be the same at deserialization as it was for serialization.
*/ */
@Override @Override
RmiSerializationManager register(Class<?> clazz, Serializer<?> serializer); RmiSerializationManager register(Class<?> clazz, Serializer<?> serializer);
/** /**
* Registers the class using the specified ID and serializer. If the ID is * Registers the class using the specified ID and serializer. If the ID is already in use by the same type, the old entry is
* already in use by the same type, the old entry is overwritten. If the ID * overwritten. If the ID is already in use by a different type, a {@link KryoException} is thrown.
* is already in use by a different type, a {@link KryoException} is thrown. * <p>
* Registering a primitive also affects the corresponding primitive wrapper. * Registering a primitive also affects the corresponding primitive wrapper.
* <p/> * <p>
* IDs must be the same at deserialization as they were for serialization. * IDs must be the same at deserialization as they were for serialization.
* *
* @param id Must be >= 0. Smaller IDs are serialized more efficiently. IDs * @param id Must be >= 0. Smaller IDs are serialized more efficiently. IDs 0-8 are used by default for primitive types and String, but
* 0-8 are used by default for primitive types and String, but * these IDs can be repurposed.
* these IDs can be repurposed.
*/ */
@Override @Override
RmiSerializationManager register(Class<?> clazz, Serializer<?> serializer, int id); RmiSerializationManager register(Class<?> clazz, Serializer<?> serializer, int id);
@ -133,20 +128,27 @@ interface RmiSerializationManager extends SerializationManager {
/** /**
* Enable remote method invocation (RMI) for this connection. There is additional overhead to using RMI. * Enable remote method invocation (RMI) for this connection. There is additional overhead to using RMI.
* <p/> * <p>
* Specifically, It costs at least 2 bytes more to use remote method invocation than just sending the parameters. If the method has a * Specifically, It costs at least 2 bytes more to use remote method invocation than just sending the parameters. If the method has a
* return value which is not {@link dorkbox.network.rmi.RemoteObject#setAsync(boolean) ignored}, an extra byte is written. If the * return value which is not {@link dorkbox.network.rmi.RemoteObject#setAsync(boolean) ignored}, an extra byte is written.
* type of a parameter is not final (primitives are final) then an extra byte is written for that parameter. * <p>
* If the type of a parameter is not final (primitives are final) then an extra byte is written for that parameter.
*/ */
RmiSerializationManager registerRmiInterface(Class<?> ifaceClass); RmiSerializationManager registerRmiInterface(Class<?> ifaceClass);
/** /**
* Objects that we want to use RMI with, must be accessed via an interface. This method configures the serialization of an * Enable remote method invocation (RMI) for this connection. There is additional overhead to using RMI.
* implementation to be serialized via the defined interface, as a RemoteObject (ie: proxy object). If the implementation class is * <p>
* ALREADY registered, then it's registration will be overwritten by this one * Specifically, It costs at least 2 bytes more to use remote method invocation than just sending the parameters. If the method has a
* return value which is not {@link dorkbox.network.rmi.RemoteObject#setAsync(boolean) ignored}, an extra byte is written.
* <p>
* If the type of a parameter is not final (primitives are final) then an extra byte is written for that parameter.
* <p>
* This method overrides the interface -> implementation. This is so incoming proxy objects will get auto-changed into their correct
* implementation type, so this side of the connection knows what to do with the proxy object.
* <p>
* *
* @param ifaceClass The interface used to access the remote object * @throws IllegalArgumentException if the iface/impl have previously been overridden
* @param implClass The implementation class of the interface
*/ */
<Iface, Impl extends Iface> RmiSerializationManager registerRmiImplementation(Class<Iface> ifaceClass, Class<Impl> implClass); <Iface, Impl extends Iface> RmiSerializationManager registerRmiImplementation(Class<Iface> ifaceClass, Class<Impl> implClass);
} }

51
src/dorkbox/network/serialization/SerializationManager.java
View File

@ -270,7 +270,7 @@ class SerializationManager implements CryptoSerializationManager, RmiSerializati
// the server will ONLY send this object to the client // the server will ONLY send this object to the client
RemoteIfaceClass remoteIfaceClass = (RemoteIfaceClass) clazz; RemoteIfaceClass remoteIfaceClass = (RemoteIfaceClass) clazz;
// registers the interface, so that when it is read, it becomes a "magic" proxy object // registers the interface, so that when it is READ, it becomes a "magic" proxy object
kryo.register(remoteIfaceClass.ifaceClass, remoteObjectSerializer); kryo.register(remoteIfaceClass.ifaceClass, remoteObjectSerializer);
} }
else if (clazz instanceof RemoteImplClass) { else if (clazz instanceof RemoteImplClass) {
@ -281,7 +281,7 @@ class SerializationManager implements CryptoSerializationManager, RmiSerializati
// the server will ONLY send this object to the client // the server will ONLY send this object to the client
RemoteImplClass remoteImplClass = (RemoteImplClass) clazz; RemoteImplClass remoteImplClass = (RemoteImplClass) clazz;
// registers the implementation, so that when it is written, it becomes a "magic" proxy object // registers the implementation, so that when it is WRITTEN, it becomes a "magic" proxy object
int id = kryo.register(remoteImplClass.implClass, remoteObjectSerializer).getId(); int id = kryo.register(remoteImplClass.implClass, remoteObjectSerializer).getId();
// sets up the RMI, so when we receive the iface class from the client, we know what impl to use // sets up the RMI, so when we receive the iface class from the client, we know what impl to use
@ -303,8 +303,9 @@ class SerializationManager implements CryptoSerializationManager, RmiSerializati
/** /**
* Registers the class using the lowest, next available integer ID and the {@link Kryo#getDefaultSerializer(Class) default serializer}. * Registers the class using the lowest, next available integer ID and the {@link Kryo#getDefaultSerializer(Class) default serializer}.
* If the class is already registered, the existing entry is updated with the new serializer. Registering a primitive also affects the * If the class is already registered, the existing entry is updated with the new serializer.
* corresponding primitive wrapper. * <p>
* Registering a primitive also affects the corresponding primitive wrapper.
* <p> * <p>
* Because the ID assigned is affected by the IDs registered before it, the order classes are registered is important when using this * Because the ID assigned is affected by the IDs registered before it, the order classes are registered is important when using this
* method. The order must be the same at deserialization as it was for serialization. * method. The order must be the same at deserialization as it was for serialization.
@ -325,15 +326,14 @@ class SerializationManager implements CryptoSerializationManager, RmiSerializati
} }
/** /**
* Registers the class using the specified ID. If the ID is * Registers the class using the specified ID. If the ID is already in use by the same type, the old entry is overwritten. If the ID
* already in use by the same type, the old entry is overwritten. If the ID
* is already in use by a different type, a {@link KryoException} is thrown. * is already in use by a different type, a {@link KryoException} is thrown.
* <p>
* Registering a primitive also affects the corresponding primitive wrapper. * Registering a primitive also affects the corresponding primitive wrapper.
* <p/> * <p>
* IDs must be the same at deserialization as they were for serialization. * IDs must be the same at deserialization as they were for serialization.
* *
* @param id Must be >= 0. Smaller IDs are serialized more efficiently. IDs * @param id Must be >= 0. Smaller IDs are serialized more efficiently. IDs 0-8 are used by default for primitive types and String, but
* 0-8 are used by default for primitive types and String, but
* these IDs can be repurposed. * these IDs can be repurposed.
*/ */
@Override @Override
@ -353,8 +353,10 @@ class SerializationManager implements CryptoSerializationManager, RmiSerializati
} }
/** /**
* Registers the class using the lowest, next available integer ID and the specified serializer. If the class is already registered, the * Registers the class using the lowest, next available integer ID and the specified serializer. If the class is already registered,
* existing entry is updated with the new serializer. Registering a primitive also affects the corresponding primitive wrapper. * the existing entry is updated with the new serializer.
* <p>
* Registering a primitive also affects the corresponding primitive wrapper.
* <p> * <p>
* Because the ID assigned is affected by the IDs registered before it, the order classes are registered is important when using this * Because the ID assigned is affected by the IDs registered before it, the order classes are registered is important when using this
* method. The order must be the same at deserialization as it was for serialization. * method. The order must be the same at deserialization as it was for serialization.
@ -377,13 +379,14 @@ class SerializationManager implements CryptoSerializationManager, RmiSerializati
/** /**
* Registers the class using the specified ID and serializer. If the ID is already in use by the same type, the old entry is * Registers the class using the specified ID and serializer. If the ID is already in use by the same type, the old entry is
* overwritten. If the ID is already in use by a different type, a {@link KryoException} is thrown. Registering a primitive also affects * overwritten. If the ID is already in use by a different type, a {@link KryoException} is thrown.
* the corresponding primitive wrapper. * <p>
* Registering a primitive also affects the corresponding primitive wrapper.
* <p> * <p>
* IDs must be the same at deserialization as they were for serialization. * IDs must be the same at deserialization as they were for serialization.
* *
* @param id Must be >= 0. Smaller IDs are serialized more efficiently. IDs 0-8 are used by default for primitive types and * @param id Must be >= 0. Smaller IDs are serialized more efficiently. IDs 0-8 are used by default for primitive types and String, but
* String, but these IDs can be repurposed. * these IDs can be repurposed.
*/ */
@Override @Override
public synchronized public synchronized
@ -403,10 +406,11 @@ class SerializationManager implements CryptoSerializationManager, RmiSerializati
/** /**
* Enable remote method invocation (RMI) for this connection. There is additional overhead to using RMI. * Enable remote method invocation (RMI) for this connection. There is additional overhead to using RMI.
* <p/> * <p>
* Specifically, It costs at least 2 bytes more to use remote method invocation than just sending the parameters. If the method has a * Specifically, It costs at least 2 bytes more to use remote method invocation than just sending the parameters. If the method has a
* return value which is not {@link dorkbox.network.rmi.RemoteObject#setAsync(boolean) ignored}, an extra byte is written. If the * return value which is not {@link dorkbox.network.rmi.RemoteObject#setAsync(boolean) ignored}, an extra byte is written.
* type of a parameter is not final (primitives are final) then an extra byte is written for that parameter. * <p>
* If the type of a parameter is not final (primitives are final) then an extra byte is written for that parameter.
*/ */
@Override @Override
public synchronized public synchronized
@ -426,10 +430,16 @@ class SerializationManager implements CryptoSerializationManager, RmiSerializati
} }
/** /**
* Enable remote method invocation (RMI) for this connection. There is additional overhead to using RMI.
* <p>
* Specifically, It costs at least 2 bytes more to use remote method invocation than just sending the parameters. If the method has a
* return value which is not {@link dorkbox.network.rmi.RemoteObject#setAsync(boolean) ignored}, an extra byte is written.
* <p>
* If the type of a parameter is not final (primitives are final) then an extra byte is written for that parameter.
* <p>
* This method overrides the interface -> implementation. This is so incoming proxy objects will get auto-changed into their correct * This method overrides the interface -> implementation. This is so incoming proxy objects will get auto-changed into their correct
* implementation type, so this side of the connection knows what to do with the proxy object. * implementation type, so this side of the connection knows what to do with the proxy object.
* <p> * <p>
* NOTE: You must have ALREADY registered the implementation class. This method just enables the proxy magic.
* *
* @throws IllegalArgumentException if the iface/impl have previously been overridden * @throws IllegalArgumentException if the iface/impl have previously been overridden
*/ */
@ -482,7 +492,8 @@ class SerializationManager implements CryptoSerializationManager, RmiSerializati
} }
/** /**
* Called when initialization is complete. This is to prevent (and recognize) out-of-order class/serializer registration. * Called when initialization is complete. This is to prevent (and recognize) out-of-order class/serializer registration. If an ID
* is already in use by a different type, a {@link KryoException} is thrown.
*/ */
@Override @Override
public synchronized public synchronized