src/main/java/net/onrc/onos/core/util/distributed/sharedlog/SharedLogObject.java

package net.onrc.onos.core.util.distributed.sharedlog;

import javax.annotation.concurrent.GuardedBy;
import javax.annotation.concurrent.NotThreadSafe;

import org.apache.commons.lang3.tuple.ImmutablePair;

import com.google.common.annotations.Beta;

import net.onrc.onos.core.util.distributed.sharedlog.internal.LogValue;
import net.onrc.onos.core.util.distributed.sharedlog.internal.SnapShotValue;

// TODO Should this be abstract class instead, to hide apply/isApplicable?
// MEMO: Something SharedObject implementor defines
/**
 * Shared object backed by shared log structure.
 *
 * Object state must be updated only by {@link #apply(SeqNum, LogValue)}
 */
@Beta
@NotThreadSafe // FIXME remove when we make these objects thread safe.
public interface SharedLogObject {

    /**
     * ID of this Shared Object.
     *
     * @return SharedLogObjectID
     */
//    @ThreadSafe // TODO find annotation for method or add javadoc
    public SharedLogObjectID getObjectID();

    /**
     * Gets the current log sequence number this instance is on.
     *
     * @return Log version of this object.
     */
//    @ThreadSafe
    public SeqNum getSeqNum();

    // FIXME Is there a good way to ensure this will be called only by Runtime
    /**
     * Apply changes to the shared object.
     * <p/>
     * Developer implementing shared object must implement this method to:
     * <ul>
     *  <li>update local instance based on given logValue if ByteValue.</li>
     *  <li>update SeqNum to given seq.</li>
     * </ul>
     * <p/>
     * Developer must also ensure that this method will never fail.
     * Any potential error check should be checked beforehand on
     * {@link #isApplicable(SeqNum, ByteValue)} call.
     * <p/>
     * Modification to this shared object instance should only happen
     * inside this method.
     * <p/>
     * This method should only be called by the runtime.
     *
     * This method will be called as a side-effect of calling
     * {@link net.onrc.onos.core.util.distributed.sharedlog.runtime
     *          .LogBasedRuntime#queryHelper(SharedLogObject)
     *        LogBasedRuntime#queryHelper(SharedLogObject)}.
     *
     * @param seq sequence number of the LogValue
     * @param logValue {@link ByteValue} to apply or NoOp
     */
    @GuardedBy("acquireWriteLock()")
    void apply(final SeqNum seq, final LogValue logValue);

    /**
     * Tests if given LogValue is applicable to this instance.
     * <p/>
     * This method will be called before {@link #apply(SeqNum, LogValue)} call.
     * This method should be implemented to be side-effect free.
     *
     * @param seq sequence number of the LogValue
     * @param logValue LogValue to test
     * @return true if {@code data} is applicable
     */
    @GuardedBy("acquireWriteLock()")
    public boolean isApplicable(final SeqNum seq, final ByteValue logValue);


    // TODO give me better name for SharedLogObject#reset
    /**
     * Resets the object to specified snapshot value.
     *
     * @param seq Log version of this snapshot
     * @param ssValue snapshot {@link ByteValue} to apply or NoOp representing initial state.
     */
    @GuardedBy("acquireWriteLock()")
    void reset(final SeqNum seq, final SnapShotValue ssValue);

    /**
     * Creates a snapshot value of current object.
     *
     * @return (current log version, snapshot value)
     */
    @GuardedBy("acquireReadLock()")
    ImmutablePair<SeqNum, ? extends SnapShotValue> createSnapshot();

    /**
     * Acquires read lock for this object.
     * <p/>
     * Note: Lock implementation must be reentrant.
     */
    public void acquireReadLock();

    /**
     * Releases read lock for this object.
     * <p/>
     * Note: Lock implementation must be reentrant.
     */
    public void releaseReadLock();

    /**
     * Acquires write lock for this object.
     * <p/>
     * Note: Lock implementation must be reentrant.
     */
    public void acquireWriteLock();

    /**
     * Releases write lock for this object.
     * <p/>
     * Note: Lock implementation must be reentrant.
     */
    public void releaseWriteLock();
}