com.lemoulinstudio.jnag.rds.JnagSession Maven / Gradle / Ivy
The newest version!
package com.lemoulinstudio.jnag.rds;
import com.lemoulinstudio.jnag.common.BindToLocalId;
import com.lemoulinstudio.jnag.common.BindToSharedId;
import com.lemoulinstudio.jnag.common.Local;
import com.lemoulinstudio.jnag.common.MessageListener;
import com.lemoulinstudio.jnag.common.Remote;
import com.lemoulinstudio.jnag.common.Singleton;
import com.sun.sgs.app.ManagedReference;
import java.nio.ByteBuffer;
/**
* The class which represents a peer in a p2p communication in the Jnag system.
*
* @author Vincent Cantin
*/
public interface JnagSession {
/**
* Decodes an encoded message and interprets it via its corresponding function
* on its targeted object.
*
* @param binaryMessage The message to be decoded and interpreted.
*/
public void decodeAndExecute(ByteBuffer binaryMessage);
/**
* Sets the object which will be notified of the encoded binary messages to be sent.
*
* @param messageListener The object which will get notified of each
* new binary messages to be sent.
*/
public void setMessageListener(MessageListener messageListener);
/**
* Sets the caller object.
*
* This object will represent the source of the message each time a message
* is being processed by the {@link #decodeAndExecute(java.nio.ByteBuffer)} method.
*
* The caller object is supposed to identify the host this session is communicating with.
*
* @param callerObjectRef A managed reference to the caller object.
*/
public void setCallerObject(ManagedReference callerObjectRef);
/**
* Returns the caller object of this Jnag session.
*
* @return The caller object of this Jnag session.
*/
public ManagedReference getCallerObject();
/**
* Binds a local singleton object. Singletons are identified by their type, not by an Id.
*
* @param The type of the local interface. Normally, an interface
* generated by the Jnag annotation processor.
*
* @param localObjectRef A reference to the local object that you want to expose to the remote host.
*
* @param localInterface The class object which represents
* the local interface which is the super type of the dereferenced local object.
*
* @see #unbindSingleton(com.sun.sgs.app.ManagedReference)
*
*/
public void bindSingleton(ManagedReference localObjectRef, Class localInterface);
/**
* Binds a local object to a new shared Id.
*
* The Id is chosen incrementally, so it is important to pay attention to
* the order of the calls.
*
* @param The type of the local interface. Normally, an interface
* generated by the Jnag annotation processor.
*
* @param localObjectRef A reference to the local object that you want to expose to the remote host.
*
* @param localInterface The class object which represents
* the local interface which is the super type of the dereferenced local object.
*
* @see #unbindFromSharedId(com.sun.sgs.app.ManagedReference)
*
*/
public void bindToSharedId(ManagedReference localObjectRef, Class localInterface);
/**
* Binds a local object to a new local Id.
*
* The Id is chosen incrementally, so it is important to pay attention to
* the order of the calls.
*
* @param The type of the local interface. Normally, an interface
* generated by the Jnag annotation processor.
*
* @param localObjectRef A reference to the local object that you want to expose to the remote host.
*
* @param localInterface The class object which represents
* the local interface which is the super type of the dereferenced local object.
*
* @see #unbindFromLocalId(com.sun.sgs.app.ManagedReference)
*/
public void bindToLocalId(ManagedReference localObjectRef, Class localInterface);
/**
* Unbinds a local object and releases its associated Id.
*
* After calling this function, the local object is no longer exposed to the remote host.
*
* @param localObjectRef A reference to the local object to be unbound.
*/
public void unbindSingleton(ManagedReference localObjectRef);
/**
* Unbinds a local object and releases its associated Id.
*
* After calling this function, the local object is no longer exposed to the remote host.
*
* @param localObjectRef A reference to the local object to be unbound.
*/
public void unbindFromSharedId(ManagedReference localObjectRef);
/**
* Unbinds a local object and releases its associated Id.
*
* After calling this function, the local object is no longer exposed to the remote host.
*
* @param localObjectRef A reference to the local object to be unbound.
*/
public void unbindFromLocalId(ManagedReference localObjectRef);
/**
* Creates a proxy and binds it to a new Id.
*
* @param The type of the remote interface. Normally, an interface
* generated by the Jnag annotation processor.
*
* @param remoteInterface The class object of a remote interface which is
* the super type of the remote object we want a proxy from.
*
* @return A reference to a proxy to a remote object.
*/
public ManagedReference createSingletonProxy(Class remoteInterface);
/**
* Creates a proxy and binds it to a new Id.
*
* @param The type of the remote interface. Normally, an interface
* generated by the Jnag annotation processor.
*
* The Id is chosen incrementally, so it is important to pay attention to
* the order of the calls.
*
* It is a good practice to only use this function at the establishment
* of the communication between the 2 hosts, in a minimalist way, and to
* get the additional proxies via the messages from the remote host.
*
* @param remoteInterface The class object of a remote interface which is
* the super type of the remote object we want a proxy from.
*
* @return A reference to a proxy to a remote object.
*/
public ManagedReference createProxy(Class remoteInterface);
/**
* Releases a proxy and its associated Id.
*
* @param The type of the proxy.
*
* @param proxyRef A reference to the proxy.
*/
public void releaseSingletonProxy(ManagedReference proxyRef);
/**
* Releases a proxy and its associated Id.
*
* @param The type of the proxy.
*
* @param proxyRef A reference to the proxy.
*/
public void releaseSharedIdProxy(ManagedReference proxyRef);
/**
* Releases a proxy and its associated Id.
*
* @param The type of the proxy.
*
* @param proxyRef A reference to the proxy.
*/
public void releaseLocalIdProxy(ManagedReference proxyRef);
}