ehcache

net.sf.ehcache.distribution
Class RMICacheManagerPeerListener

java.lang.Object
  extended by net.sf.ehcache.distribution.RMICacheManagerPeerListener
All Implemented Interfaces:
CacheManagerPeerListener, CacheManagerEventListener

public class RMICacheManagerPeerListener
extends Object
implements CacheManagerPeerListener

A cache server which exposes available cache operations remotely through RMI.

It acts as a Decorator to a Cache. It holds an instance of cache, which is a local cache it talks to.

This class could specify a security manager with code like:

 if (System.getSecurityManager() == null) {
     System.setSecurityManager(new RMISecurityManager());
 }
 
Doing so would require the addition of grant statements in the java.policy file.

Per the JDK documentation: "If no security manager is specified no class loading, by RMI clients or servers, is allowed, aside from what can be found in the local CLASSPATH." The classpath of each instance of this class should have all required classes to enable distribution, so no remote classloading is required or desirable. Accordingly, no security manager is set and there are no special JVM configuration requirements.

This class opens a ServerSocket. The dispose method should be called for orderly closure of that socket. This class has a shutdown hook which calls dispose() as a convenience feature for developers.

Version:
$Id: RMICacheManagerPeerListener.java 5594 2012-05-07 16:04:31Z cdennis $
Author:
Greg Luck

Field Summary
protected  Map cachePeers
          The cache peers.
protected  Integer port
          The RMI listener port
protected  Status status
          status.
 
Constructor Summary
RMICacheManagerPeerListener(String hostName, Integer port, Integer remoteObjectPort, CacheManager cacheManager, Integer socketTimeoutMillis)
          Constructor with full arguments.
 
Method Summary
protected  void assignFreePort(boolean forced)
          Assigns a free port to be the listener port.
 void attemptResolutionOfUniqueResourceConflict()
          If a conflict is detected in unique resource use, this method signals the listener to attempt automatic resolution of the resource conflict.
protected  void bind(String peerName, RMICachePeer rmiCachePeer)
          Bind a cache peer
protected  String calculateHostAddress()
          Calculates the host address as the default NICs IP address
 void dispose()
          Stop the listener.
protected  void disposeRMICachePeer(RMICachePeer rmiCachePeer)
          A template method to dispose an individual RMICachePeer.
 List getBoundCachePeers()
          All of the caches which are listening for remote changes.
protected  int getFreePort()
          Gets a free server socket port.
 String getScheme()
          The replication scheme this listener interacts with.
 Status getStatus()
          Returns the listener status.
 String getUniqueResourceIdentifier()
          A listener will normally have a resource that only one instance can use at the same time, such as a port.
 void init()
          Call to start the listeners and do any other required initialisation.
protected  boolean isDistributed(Ehcache cache)
          Determine if the given cache is distributed.
protected  String[] listBoundRMICachePeers()
          Returns a list of bound objects.
protected  Remote lookupPeer(String name)
          Returns a reference to the remote object.
 void notifyCacheAdded(String cacheName)
          Called immediately after a cache has been added and activated.
 void notifyCacheRemoved(String cacheName)
          Called immediately after a cache has been disposed and removed.
protected  void populateListOfRemoteCachePeers()
          Should be called on init because this is one of the last things that should happen on CacheManager startup.
protected  void startRegistry()
          Start the rmiregistry.
protected  void stopRegistry()
          Stop the rmiregistry if it was started by this class.
protected  void unbind(RMICachePeer rmiCachePeer)
          Unbinds an RMICachePeer and unexports it.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

cachePeers

protected final Map cachePeers
The cache peers. The value is an RMICachePeer.


status

protected Status status
status.


port

protected Integer port
The RMI listener port

Constructor Detail

RMICacheManagerPeerListener

public RMICacheManagerPeerListener(String hostName,
                                   Integer port,
                                   Integer remoteObjectPort,
                                   CacheManager cacheManager,
                                   Integer socketTimeoutMillis)
                            throws UnknownHostException
Constructor with full arguments.

Parameters:
hostName - may be null, in which case the hostName will be looked up. Machines with multiple interfaces should specify this if they do not want it to be the default NIC.
port - a port in the range 1025 - 65536
remoteObjectPort - the port number on which the remote objects bound in the registry receive calls. This defaults to a free port if not specified.
cacheManager - the CacheManager this listener belongs to
socketTimeoutMillis - TCP/IP Socket timeout when waiting on response
Throws:
UnknownHostException
Method Detail

assignFreePort

protected void assignFreePort(boolean forced)
                       throws IllegalStateException
Assigns a free port to be the listener port.

Throws:
IllegalStateException - if the statis of the listener is not Status.STATUS_UNINITIALISED

calculateHostAddress

protected String calculateHostAddress()
                               throws UnknownHostException
Calculates the host address as the default NICs IP address

Throws:
UnknownHostException

getFreePort

protected int getFreePort()
                   throws IllegalArgumentException
Gets a free server socket port.

Returns:
a number in the range 1025 - 65536 that was free at the time this method was executed
Throws:
IllegalArgumentException

init

public void init()
          throws CacheException
Call to start the listeners and do any other required initialisation. init should also handle any work to do with the caches that are part of the initial configuration.

Specified by:
init in interface CacheManagerEventListener
Throws:
CacheException - - all exceptions are wrapped in CacheException

bind

protected void bind(String peerName,
                    RMICachePeer rmiCachePeer)
             throws Exception
Bind a cache peer

Parameters:
rmiCachePeer -
Throws:
Exception

listBoundRMICachePeers

protected String[] listBoundRMICachePeers()
                                   throws CacheException
Returns a list of bound objects.

This should match the list of cachePeers i.e. they should always be bound

Returns:
a list of String representations of RMICachePeer objects
Throws:
CacheException

lookupPeer

protected Remote lookupPeer(String name)
                     throws CacheException
Returns a reference to the remote object.

Parameters:
name - the name of the cache e.g. sampleCache1
Throws:
CacheException

populateListOfRemoteCachePeers

protected void populateListOfRemoteCachePeers()
                                       throws RemoteException
Should be called on init because this is one of the last things that should happen on CacheManager startup.

Throws:
RemoteException

isDistributed

protected boolean isDistributed(Ehcache cache)
Determine if the given cache is distributed.

Parameters:
cache - the cache to check
Returns:
true if a CacheReplicator is found in the listeners

startRegistry

protected void startRegistry()
                      throws RemoteException
Start the rmiregistry.

The alternative is to use the rmiregistry binary, in which case:

  1. rmiregistry running
  2. -Djava.rmi.server.codebase="file:///Users/gluck/work/ehcache/build/classes/ file:///Users/gluck/work/ehcache/lib/commons-logging-1.0.4.jar"

Throws:
RemoteException

stopRegistry

protected void stopRegistry()
                     throws RemoteException
Stop the rmiregistry if it was started by this class.

Throws:
RemoteException

dispose

public void dispose()
             throws CacheException
Stop the listener. It

Specified by:
dispose in interface CacheManagerEventListener
Throws:
CacheException - - all exceptions are wrapped in CacheException

disposeRMICachePeer

protected void disposeRMICachePeer(RMICachePeer rmiCachePeer)
                            throws Exception
A template method to dispose an individual RMICachePeer. This consists of:
  1. Unbinding the peer from the naming service
  2. Unexporting the peer
Override to specialise behaviour

Parameters:
rmiCachePeer - the cache peer to dispose of
Throws:
Exception - thrown if something goes wrong

unbind

protected void unbind(RMICachePeer rmiCachePeer)
               throws Exception
Unbinds an RMICachePeer and unexports it.

We unbind from the registry first before unexporting. Unbinding first removes the very small possibility of a client getting the object from the registry while we are trying to unexport it.

This method may take up to 4 seconds to complete, if we are having trouble unexporting the peer.

Parameters:
rmiCachePeer - the bound and exported cache peer
Throws:
Exception

getBoundCachePeers

public List getBoundCachePeers()
All of the caches which are listening for remote changes.

Specified by:
getBoundCachePeers in interface CacheManagerPeerListener
Returns:
a list of RMICachePeer objects. The list if not live

getStatus

public Status getStatus()
Returns the listener status.

Specified by:
getStatus in interface CacheManagerEventListener
Returns:
the status at the point in time the method is called

getUniqueResourceIdentifier

public String getUniqueResourceIdentifier()
A listener will normally have a resource that only one instance can use at the same time, such as a port. This identifier is used to tell if it is unique and will not conflict with an existing instance using the resource.

Specified by:
getUniqueResourceIdentifier in interface CacheManagerPeerListener
Returns:
a String identifier for the resource

attemptResolutionOfUniqueResourceConflict

public void attemptResolutionOfUniqueResourceConflict()
                                               throws IllegalStateException,
                                                      CacheException
If a conflict is detected in unique resource use, this method signals the listener to attempt automatic resolution of the resource conflict.

Specified by:
attemptResolutionOfUniqueResourceConflict in interface CacheManagerPeerListener
Throws:
IllegalStateException - if the statis of the listener is not Status.STATUS_UNINITIALISED
CacheException

getScheme

public String getScheme()
The replication scheme this listener interacts with. Each peer provider has a scheme name, which can be used by caches to specify for replication and bootstrap purposes.

Specified by:
getScheme in interface CacheManagerPeerListener
Returns:
the well-known scheme name, which is determined by the replication provider author.

notifyCacheAdded

public void notifyCacheAdded(String cacheName)
                      throws CacheException
Called immediately after a cache has been added and activated.

Note that the CacheManager calls this method from a synchronized method. Any attempt to call a synchronized method on CacheManager from this method will cause a deadlock.

Note that activation will also cause a CacheEventListener status change notification from Status.STATUS_UNINITIALISED to Status.STATUS_ALIVE. Care should be taken on processing that notification because:

The calling method will block until this method returns.

Repopulates the list of cache peers and rebinds the list. This method should be called if a cache is dynamically added

Specified by:
notifyCacheAdded in interface CacheManagerEventListener
Parameters:
cacheName - the name of the Cache the operation relates to
Throws:
CacheException
See Also:
CacheEventListener

notifyCacheRemoved

public void notifyCacheRemoved(String cacheName)
Called immediately after a cache has been disposed and removed. The calling method will block until this method returns.

Note that the CacheManager calls this method from a synchronized method. Any attempt to call a synchronized method on CacheManager from this method will cause a deadlock.

Note that a CacheEventListener status changed will also be triggered. Any attempt from that notification to access CacheManager will also result in a deadlock.

Specified by:
notifyCacheRemoved in interface CacheManagerEventListener
Parameters:
cacheName - the name of the Cache the operation relates to

ehcache

Copyright 2001-2014, Terracotta, Inc.