saker.build Documentation TaskDoc JavaDoc
public interface RMIWrapper
Class for specializing the serialization of an object over the RMI connection.

The purpose of this class is to fine grain the transfer of some objects over the RMI connection. Implementations of this class must have a public default constructor, and must have at least one constructor which take a single argument of the type which is being the subject of transferring.
E.g. If a method is called with a String parameter, it can have a constructor with String, CharSequence, or other assignable classes as a single parameter. The object to be transferred must be assignable to at least one of the constructor parameter types.

Serialization:
1. An instance of the RMIWrapper implementation is constructer using an appropriate constructor.
2. The class of the wrapper implementation is serialized over the RMI connection.
3. writeWrapped(RMIObjectOutput) is called to serialize the object which was passed in the constructor.

Deserialization:
1. The wrapper class is read from the stream by the RMI runtime.
2. The wrapper is instantiated using the public default constructor.
3. readWrapped(RMIObjectInput) is called to read the serialized data.
4. resolveWrapped() is called to retrieve the actual object to pass to the request.

Instances of this interface should only be used to configure the transfer of object and should not be used in the RMI runtime directly. I.e. do not pass instances of RMIWrapper as arguments, return values, etc... for method calls. Any passed objects will be unwrapped using getWrappedObject() regardless of use-case.

Methods
public Object
Gets the wrapped object which should be serialized during RMI transfer.
public void
Reads the wrapped object from the RMI object input stream.
public Object
Resolves the wrapped object during deserialization.
public void
Writes the wrapped object to the RMI object output stream.
public abstract Object getWrappedObject()
Gets the wrapped object which should be serialized during RMI transfer.

If resolveWrapped() returned this then this method will be called when the wrapper instance is serialized to an other endpoint. It is preferred to return a remote proxy to the previously wrapped object to pass back to the original endpoint when reverse request is made. Returning this from this method will result in the serialization of this wrapper through RMI.

If resolveWrapped() did not return this then this method can freely return null or throw exceptions (e.g. UnsupportedOperationException) because it will never be called.

The object to serialize instead of this.
Reads the wrapped object from the RMI object input stream.
inThe input stream to read from.
IOExceptionIn case of I/O error.
ClassNotFoundExceptionIf a class for a serialized object cannot be found.
public abstract Object resolveWrapped()
Resolves the wrapped object during deserialization.

The result of this method will be returned to the caller, or used during the RMI request.

The result of the object transfer.
public abstract void writeWrapped(RMIObjectOutput out) throws IOException
Writes the wrapped object to the RMI object output stream.

Important aspect of writing objects using wrappers is that in this method if any of the object writing method is called, then the non customizable aspects of the serializable will not be applied to the object that is being wrapped.

E.g. If an RMIWrapper is defined for an object type T, then calling RMIObjectOutput.writeRemoteObject(Object) will not cause the subject object with the type T to be written using an RMIWrapper again, but it will be actually written as a remote object.

outThe output stream to write to.
IOExceptionIn case of I/O error.