Yuta HIGUCHI | 8f18219 | 2014-08-02 18:47:42 -0700 | [diff] [blame] | 1 | package net.onrc.onos.core.util.distributed.sharedlog; |
| 2 | |
| 3 | import javax.annotation.concurrent.GuardedBy; |
| 4 | import javax.annotation.concurrent.NotThreadSafe; |
| 5 | |
| 6 | import org.apache.commons.lang3.tuple.ImmutablePair; |
| 7 | |
| 8 | import com.google.common.annotations.Beta; |
| 9 | |
| 10 | import net.onrc.onos.core.util.distributed.sharedlog.internal.LogValue; |
| 11 | import net.onrc.onos.core.util.distributed.sharedlog.internal.SnapShotValue; |
| 12 | |
| 13 | // TODO Should this be abstract class instead, to hide apply/isApplicable? |
| 14 | // MEMO: Something SharedObject implementor defines |
| 15 | /** |
| 16 | * Shared object backed by shared log structure. |
| 17 | * |
| 18 | * Object state must be updated only by {@link #apply(SeqNum, LogValue)} |
| 19 | */ |
| 20 | @Beta |
| 21 | @NotThreadSafe // FIXME remove when we make these objects thread safe. |
| 22 | public interface SharedLogObject { |
| 23 | |
| 24 | /** |
| 25 | * ID of this Shared Object. |
| 26 | * |
| 27 | * @return SharedLogObjectID |
| 28 | */ |
| 29 | // @ThreadSafe // TODO find annotation for method or add javadoc |
| 30 | public SharedLogObjectID getObjectID(); |
| 31 | |
| 32 | /** |
| 33 | * Gets the current log sequence number this instance is on. |
| 34 | * |
| 35 | * @return Log version of this object. |
| 36 | */ |
| 37 | // @ThreadSafe |
| 38 | public SeqNum getSeqNum(); |
| 39 | |
| 40 | // FIXME Is there a good way to ensure this will be called only by Runtime |
| 41 | /** |
| 42 | * Apply changes to the shared object. |
| 43 | * <p/> |
| 44 | * Developer implementing shared object must implement this method to: |
| 45 | * <ul> |
| 46 | * <li>update local instance based on given logValue if ByteValue.</li> |
| 47 | * <li>update SeqNum to given seq.</li> |
| 48 | * </ul> |
| 49 | * <p/> |
| 50 | * Developer must also ensure that this method will never fail. |
| 51 | * Any potential error check should be checked beforehand on |
| 52 | * {@link #isApplicable(SeqNum, ByteValue)} call. |
| 53 | * <p/> |
| 54 | * Modification to this shared object instance should only happen |
| 55 | * inside this method. |
| 56 | * <p/> |
| 57 | * This method should only be called by the runtime. |
| 58 | * |
| 59 | * This method will be called as a side-effect of calling |
| 60 | * {@link net.onrc.onos.core.util.distributed.sharedlog.runtime |
| 61 | * .LogBasedRuntime#queryHelper(SharedLogObject) |
| 62 | * LogBasedRuntime#queryHelper(SharedLogObject)}. |
| 63 | * |
| 64 | * @param seq sequence number of the LogValue |
| 65 | * @param logValue {@link ByteValue} to apply or NoOp |
| 66 | */ |
| 67 | @GuardedBy("acquireWriteLock()") |
| 68 | void apply(final SeqNum seq, final LogValue logValue); |
| 69 | |
| 70 | /** |
| 71 | * Tests if given LogValue is applicable to this . |
| 72 | * <p/> |
| 73 | * This method will be called before {@link #apply(SeqNum, LogValue)} call. |
| 74 | * This method should be implemented to be side-effect free. |
| 75 | * |
| 76 | * @param seq sequence number of the LogValue |
| 77 | * @param logValue LogValue to test |
| 78 | * @return true if {@code data} is applicable |
| 79 | */ |
| 80 | @GuardedBy("acquireWriteLock()") |
| 81 | public boolean isApplicable(final SeqNum seq, final ByteValue logValue); |
| 82 | |
| 83 | |
| 84 | // TODO give me better name for SharedLogObject#reset |
| 85 | /** |
| 86 | * Resets the object to specified snapshot value. |
| 87 | * |
| 88 | * @param seq Log version of this snapshot |
| 89 | * @param ssValue snapshot {@link ByteValue} to apply or NoOp representing initial state. |
| 90 | */ |
| 91 | @GuardedBy("acquireWriteLock()") |
| 92 | void reset(final SeqNum seq, final SnapShotValue ssValue); |
| 93 | |
| 94 | /** |
| 95 | * Creates a snapshot value of current object. |
| 96 | * |
| 97 | * @return (current log version, snapshot value) |
| 98 | */ |
| 99 | @GuardedBy("acquireReadLock()") |
| 100 | ImmutablePair<SeqNum, ? extends SnapShotValue> createSnapshot(); |
| 101 | |
| 102 | /** |
| 103 | * Acquires read lock for this object. |
| 104 | * <p/> |
| 105 | * Note: Lock implementation must be reentrant. |
| 106 | */ |
| 107 | public void acquireReadLock(); |
| 108 | |
| 109 | /** |
| 110 | * Releases read lock for this object. |
| 111 | * <p/> |
| 112 | * Note: Lock implementation must be reentrant. |
| 113 | */ |
| 114 | public void releaseReadLock(); |
| 115 | |
| 116 | /** |
| 117 | * Acquires write lock for this object. |
| 118 | * <p/> |
| 119 | * Note: Lock implementation must be reentrant. |
| 120 | */ |
| 121 | public void acquireWriteLock(); |
| 122 | |
| 123 | /** |
| 124 | * Releases write lock for this object. |
| 125 | * <p/> |
| 126 | * Note: Lock implementation must be reentrant. |
| 127 | */ |
| 128 | public void releaseWriteLock(); |
| 129 | } |