001//
002// Name
003//  $RCSfile: NodeNotifier.java,v $
004// 
005// Copyright
006//  Confidential Property of Kabira Technologies, Inc.
007//  Copyright 2011 by Kabira Technologies, Inc.
008//  All rights reserved.
009//
010// History
011//  $Revision: 1.1.2.3 $ $Date: 2011/06/10 18:00:16 $
012//
013package com.kabira.platform.highavailability;
014
015import com.kabira.platform.annotation.Managed;
016import com.kabira.platform.disteng.DENodeNotifier;
017
018/**
019 * The NodeNotifier class. This managed class is extended by applications
020 * to get notifications when remote nodes become active or unavailable.
021 * Creating an instance of this class enables the <b>active</b> and
022 * <b>unavailable</b> callbacks for the local node. These callbacks are
023 * called whenever the local node detects that a remote node becomes
024 * active or unavailable. Each node which needs notifications must create
025 * an instance of this class.
026 * <p>
027 * When an instance of this class is created, the <b>active</b> callback is
028 * called for each active remote node already discovered by the local node.
029 * <p>
030 * The execution order for these callbacks is serialized by the runtime.
031 * If a node becomes unavailable while the <b>active</b> callback is
032 * executed, the execution of the <b>unavailable</b> callback is deferred
033 * until after the <b>active</b> callback finishes execution.
034 * <p>
035 * When nodes become active or unavailable, the callback is executed in a
036 * system defined transaction. Applications should create and delete
037 * instances of this class in a separate transaction that does not make
038 * any other calls to methods in the highavailability package. Doing this
039 * will reduce the potential for transaction deadlocks when the callbacks
040 * are executed.
041 */
042@Managed
043public abstract class NodeNotifier extends DENodeNotifier
044{
045    /**
046     * Called when a node becomes active.
047     *
048     * @param remoteNode The name of remote node. 
049     * <p>
050     * This operation is called whenever a remote node becomes active.
051     * <p>
052     * Remote work can be executed on the new remote node when this
053     * callback is executed.
054     */
055    protected abstract void active(final String remoteNode);
056
057    /**
058     * Called when a node becomes unavailable.
059     *
060     * @param remoteNode The name of remote node. 
061     * <p>
062     * This operation is called whenever a remote node becomes unavailable.
063     * <p>
064     * Remote work should not be attempted on the unavailable remote node
065     * when this callback is executed.
066     */
067    protected abstract void unavailable(final String remoteNode);
068}