Cluster API proposal?

[Greg Wilkins]

This is my idea of how we could morph the currently proposed session APIs
into a cluster API.

I have created a spot for Cluster meta data - but I have not filled it out much.

The key difference is that the state Map is now indexed by session ID and 
context ID.
This allows the state for different contexts within the same session to be on 
different
nodes (this is a real requirement) and also means that locking is at context 
rather
than meta session level.  Note that some implementations may not fully support 
this and may just do sessionId+contextId behind the scenes and colocate all 
context
states for the same session (and move them as one).

I have also added an async aspect to the API for potentially long operations
such as moving state about the place - again this can be optionally supported.

Also I support the idea of multiple Nodes per server (really useful for testing
and heterogeneous clusters).



// The top level Cluster API - this was the Locator... but let's call a spade a 
spade.

interface Cluster
{
     // methods to get/set meta data about the cluster
     // these signatures here are just a guess... but you get the idea.
     int getMaxNodes();
     Set<Node> getKnownNodes();
     void setKnownNodes(Set<Node> nodes);
     Node getLocalNode();

     // Access sessions in cluster.  
     MetaSession getMetaSession(String clientID);
     Session createMetaSession(String sessionId);

}


// Node API
// was Server - but may have multiple Nodes per server
interface Node
{
    String getName();    
    String[] getAddresses(String protocol);    
    void setAddresses(String string, String[] strings);    
    boolean isLocalServer();
    boolean isActive();

    int getPort(String protocol);  // one way to handle the multi nodes per 
server
    int getPortOffset();           // or this one (add to standard port)
}


// Meta Session - was SessionLocation
interface MetaSession
{
    String getSessionId();
    void invalidate();

    void addEventListener(MetaSessionListener listener);
    void removeEventListener(MetaSessionListener listener);

    // State API has map per context ID , where a context
    // ID might be "web:/context" or "ejb:" or random
    boolean isStateLocal(String contextId);


    Map getState(String contextId);          // implies a move local!
    void getStateAsync(Object key, String contextId);  // async version 

    Map createState(String contextId);
    void releaseState(String contextId); // don't lock whole meta session!
    void invalidate(String contextId);

    // Locaton / Policy API.
    Node getNode(String contextId); 
    Node getExecutionNode(String contextId); 
    void getExecutionNodeAsync(Object key, String contextId);    


    // Don't know if these are too HTTP specific... but we need them 
    void setPassivationTimeout(long ms, String contextId);
    void setInvalidationTimeout(long ms, String contextId);
}


interface MetaSessionListener
{
    // callbacks to allow session manager to inspect contents for 
    // tier specific handling (eg servlet listeners etc.)
    void activateState(String sessionId, String contextId, Map state);
    void passivateState(String sessionId, String contextId, Map state);
    void invalidateState(String sessionId, String contextId, Map state);

    // callbacks for async operations
    void gotState(Object key, String sessionId, String contextId, Map state);
    void executionNode(Object key, String sessionId, String contextId, Node 
location);

}