001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.catalina.tribes.tipis;
018:
019: import java.io.IOException;
020: import java.io.Serializable;
021:
022: /**
023: *
024: * For smarter replication, an object can implement this interface to replicate diffs<br>
025: * The replication logic will call the methods in the following order:<br>
026: * <code>
027: * 1. if ( entry.isDirty() ) <br>
028: * try {
029: * 2. entry.lock();<br>
030: * 3. byte[] diff = entry.getDiff();<br>
031: * 4. entry.reset();<br>
032: * } finally {<br>
033: * 5. entry.unlock();<br>
034: * }<br>
035: * }<br>
036: * </code>
037: * <br>
038: * <br>
039: * When the data is deserialized the logic is called in the following order<br>
040: * <code>
041: * 1. ReplicatedMapEntry entry = (ReplicatedMapEntry)objectIn.readObject();<br>
042: * 2. if ( isBackup(entry)||isPrimary(entry) ) entry.setOwner(owner); <br>
043: * </code>
044: * <br>
045: *
046: *
047: * @author Filip Hanik
048: * @version 1.0
049: */
050: public interface ReplicatedMapEntry extends Serializable {
051:
052: /**
053: * Has the object changed since last replication
054: * and is not in a locked state
055: * @return boolean
056: */
057: public boolean isDirty();
058:
059: /**
060: * If this returns true, the map will extract the diff using getDiff()
061: * Otherwise it will serialize the entire object.
062: * @return boolean
063: */
064: public boolean isDiffable();
065:
066: /**
067: * Returns a diff and sets the dirty map to false
068: * @return byte[]
069: * @throws IOException
070: */
071: public byte[] getDiff() throws IOException;
072:
073: /**
074: * Applies a diff to an existing object.
075: * @param diff byte[]
076: * @param offset int
077: * @param length int
078: * @throws IOException
079: */
080: public void applyDiff(byte[] diff, int offset, int length)
081: throws IOException, ClassNotFoundException;
082:
083: /**
084: * Resets the current diff state and resets the dirty flag
085: */
086: public void resetDiff();
087:
088: /**
089: * Lock during serialization
090: */
091: public void lock();
092:
093: /**
094: * Unlock after serialization
095: */
096: public void unlock();
097:
098: /**
099: * This method is called after the object has been
100: * created on a remote map. On this method,
101: * the object can initialize itself for any data that wasn't
102: *
103: * @param owner Object
104: */
105: public void setOwner(Object owner);
106:
107: /**
108: * For accuracy checking, a serialized attribute can contain a version number
109: * This number increases as modifications are made to the data.
110: * The replicated map can use this to ensure accuracy on a periodic basis
111: * @return long - the version number or -1 if the data is not versioned
112: */
113: public long getVersion();
114:
115: /**
116: * Forces a certain version to a replicated map entry<br>
117: * @param version long
118: */
119: public void setVersion(long version);
120:
121: }
|