Oracle Fusion Middleware
Java API Reference for Oracle WebLogic Server
12c (12.1.2)

Part Number E27170-01

Package weblogic.cluster.migration

Migratable Services

See:
          Description

Interface Summary
Migratable Every migratable service must implement the Migratable interface.
 

Exception Summary
MigrationException This exception is thrown when a problem occurs during the migration of a migratable target.
 

Package weblogic.cluster.migration Description

Migratable Services

A migratable service is a stateful service capable of migrating from one server to another in a cluster.  The cluster ensures that each migratable service is only active on one server at time.  It also ensures that migration is transparent to the remote clients of the service.  A service can be migrated either manually by administrative command or automatically by the cluster fail-over machinery. 

A typical migratable service is one that requires a single point of control in a cluster and is capable of recovering its state from a shared persistent store.  Take for example a write-through cache of persistent data.  Such a service maintains a consistent cache of persistent data by writing each update directly to the store and invalidating any effected cache lines.  Reads can avoid the store if the data is cached.  It relies on the guarantee that all reads and writes go through a single instance of the service to ensure that a consistent view of the data is maintained.  If there were two instances in the cluster, an update through one cache would not be reflected in a read from the other.  

Implementing a Migratable Service

A migratable service must provide a class that implements the Migratable interface.  In addition the class must implement an interface describing its service methods.  If the service is remotely accessible, this service interface must be a Remote interface.  An instance of the Migratable class will be installed on each server in the cluster that may host the service.  One of these instances will be chosen (manually or by the cluster) to be the active instance.  This instance will be activated and all others will remain inactive.  When migration occurs the currently active instance is deactivated and a new instance is activated.  If the migration is due to failure of the active instance, the cluster will ensure that the failed instance is dead (or has timed out) and only then activate the new instance.

It is not always possible to distinguish a server that is dead from one that is unreachable.  If a server is truly dead, the cluster can safely migrate any service hosted by the dead server to a live one.  If a server is unreachable, but still alive, migration to a new server may result in two active instances of the service in the cluster.  The service may still be active on the unreachable server.  The migration framework addresses this problem with the use of leases.

When a migratable service instance is activated, it is given a lease.  This lease indicates the amount of time that this instance can assume ownership of the service.  This lease is renewed periodically so that a service that is not migrated will remain active.  If the server loses contact with the cluster, any leases that it holds not be renewed  and will eventually expire.  When a lease expires, the instance will be deactivated (even if no other server can reach this server).  This lease management is hidden from the migratable service provider, however it does place one constraint on the provider implementation.  The provider must ensure that each service method will complete within a fixed time (5 seconds by default).  This is necessary so that the framework can disallow any call to a migratable instance that may complete after its lease expires. 

If a migratable service implements a Remote interface, it will be represented by a migration-aware stub on remote clients.  This stub is aware of the multiple instances of the service in the cluster and will ensure that calls are directed to the active instance.  If a migration occurs between calls, the stub will detect the move, track down the new instance, and direct the call to the new instance.  This recovery is transparent to the caller.  If a call occurs after an instance has been deactivated but before a new instance has been activated, the stub will throw an exception.  This exception indicates to the caller that the service is temporarily unavailable.  It also provides a hint about when migration might complete. 

Deploying a Migratable Service

A migratable service cannot be deployed to a standard target.  It must instead be deployed to a MigratableTarget.  A MigratableTarget is virtual target that may migrate from one server to another.  Services that are deployed to such a target will migrate along with the target.  A migratable target specifies a list of servers ordered by preference.  The first server in the list is the preferred host.  If that server is running, that target will always be hosted by that server.  The second server in the list is the second most preferred server.  If the first server is not available, the target will migrate to the second server, and so on.  A MigratableTarget may be either manually or automatically migratable.

Manual mode
A manual MigratableTarget may be migrated from one server to another manually through the admin server.  Any migratable service deployed to this target will migrate when the target is migrated.  The target specifies a list of servers in order of preference.  This provides a hint to the cluster about where the administrator is likely to migrate a target if a failure occurs.  When a service is deployed to this target it is activated on the first server in the target list.  If that server is not reachable, the service will not be activated until the administrator explicitly moves the target to the next server in the list.  Following the list order in manual migration is helpful but not required.  It makes it possible for a stub to more quickly find the new host.
Automatic mode
An automatic MigratableTarget may be migrated automatically by the cluster.  (It may also be migrated manually as described above.  Any migratable service deployed to this target will be migrated when the target it migrated.  The target definition specifies a list of servers in order of preference.  When the cluster migrates the target it will migrate to the first server in the list that is currently available.  Automatic migration occurs when the cluster detects that the current host of the target has failed.  Note that there is no automatic fail-back.  That is, if  the most preferred host becomes available after a target has migrated to a less preferred host, the system will not automatically migrate the target back to the most preferred host. 

Code Example

The following code illustrates the implementation of a simple migratable service.
public interface MigratableVariable extends Remote
{
  void set(Object value) throws RemoteException;
  Object get() throws RemoteException;
} 
public class MigratableVariableImpl implements MigratableVariable, Migratable
{
  private Object value = null; // cached value

  public synchronized void set(Object value)
  {
    writeToStore(value);
    this.value = value;
  }

  public Object get()
  { 
    return value; 
  }

  public void migratableActivate() throws MigrationException
  {
    value = readFromStore(); 
    try {
      (new InitialContext()).bind("variable", this);
    } catch (NamingException e) {
      throw new MigrationException("", e);
    }
  }

  public void migratableDeactivate() throws MigrationException
  {
    try {
      (new InitialContext()).unbind("variable");
    } catch (NamingException e) {
      throw new MigrationException("", e);
    }
  }

  public static void main(String[] args)
  {
    String[] list = { "server1, "server2", "server3" };
    MigratableTarget target = new MigratableTarget(list);
    Migratable instance = new MigratableVariableImpl();
    MigrationManager.singleton().register(instance, target);
  } 
}


Copyright 1996, 2013, Oracle and/or its affiliates. All rights reserved. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

Oracle Fusion Middleware
Java API Reference for Oracle WebLogic Server
12c (12.1.2)

Part Number E27170-01