Java tutorial
/** * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you under the Apache License, Version 2.0 (the * "License"); you may not use this file except in compliance * with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package com.twitter.distributedlog; import com.google.common.annotations.VisibleForTesting; import com.google.common.base.Preconditions; import org.apache.commons.codec.binary.Base64; import org.apache.commons.codec.binary.Hex; import java.nio.ByteBuffer; /** * DistributedLog Sequence Number (DLSN) is the system generated sequence number for log record. * * <p>DLSN is comprised with 3 components: * <ul> * <li>LogSegment Sequence Number: the sequence number of log segment that the record is written in * <li>Entry Id: the entry id of the entry that the record is batched in * <li>Slot Id: the slot id that the record is in the entry * </ul> * * @see LogRecordWithDLSN */ public class DLSN implements Comparable<DLSN> { public static final byte VERSION0 = (byte) 0; public static final byte VERSION1 = (byte) 1; // The initial DLSN that DL starts with public static final DLSN InitialDLSN = new DLSN(1, 0, 0); // The non-inclusive lower bound DLSN public static final DLSN NonInclusiveLowerBound = new DLSN(1, 0, -1); // Invalid DLSN public static final DLSN InvalidDLSN = new DLSN(0, -1, -1); static final byte CUR_VERSION = VERSION1; static final int VERSION0_LEN = Long.SIZE * 3 + Byte.SIZE; static final int VERSION1_LEN = Long.SIZE * 3 / Byte.SIZE + 1; private final long logSegmentSequenceNo; private final long entryId; private final long slotId; public DLSN(long logSegmentSequenceNo, long entryId, long slotId) { this.logSegmentSequenceNo = logSegmentSequenceNo; this.entryId = entryId; this.slotId = slotId; } /** * Return the sequence number of the log segment that the record is written to. * * @return sequence number of the log segment that the record is written to. */ public long getLogSegmentSequenceNo() { return logSegmentSequenceNo; } /** * use {@link #getLogSegmentSequenceNo()} instead */ @Deprecated long getLedgerSequenceNo() { return logSegmentSequenceNo; } /** * Return the entry id of the batch that the record is written to. * * @return entry id of the batch that the record is written to. */ public long getEntryId() { return entryId; } /** * Return the slot id in the batch that the record is written to. * * @return slot id in the batch that the record is written to. */ public long getSlotId() { return slotId; } @Override public int compareTo(DLSN that) { if (this.logSegmentSequenceNo != that.logSegmentSequenceNo) { return (this.logSegmentSequenceNo < that.logSegmentSequenceNo) ? -1 : 1; } else if (this.entryId != that.entryId) { return (this.entryId < that.entryId) ? -1 : 1; } else { return (this.slotId < that.slotId) ? -1 : (this.slotId == that.slotId) ? 0 : 1; } } /** * Serialize the DLSN into bytes with current version. * * @return the serialized bytes */ public byte[] serializeBytes() { return serializeBytes(CUR_VERSION); } /** * Serialize the DLSN into bytes with given <code>version</code>. * * @param version * version to serialize the DLSN * @return the serialized bytes */ public byte[] serializeBytes(byte version) { Preconditions.checkArgument(version <= CUR_VERSION && version >= VERSION0); byte[] data = new byte[CUR_VERSION == version ? VERSION1_LEN : VERSION0_LEN]; ByteBuffer bb = ByteBuffer.wrap(data); bb.put(version); bb.putLong(logSegmentSequenceNo); bb.putLong(entryId); bb.putLong(slotId); return data; } /** * Serialize the DLSN into base64 encoded string. * * @return serialized base64 string * @see #serializeBytes() */ public String serialize() { return serialize(CUR_VERSION); } /** * Serialize the DLSN into base64 encoded string with given <code>version</code>. * * @param version * version to serialize the DLSN * @return the serialized base64 string * @see #serializeBytes(byte) */ public String serialize(byte version) { return Base64.encodeBase64String(serializeBytes(version)); } /** * Deserialize the DLSN from base64 encoded string <code>dlsn</code>. * * @param dlsn * base64 encoded string * @return dlsn */ public static DLSN deserialize(String dlsn) { byte[] data = Base64.decodeBase64(dlsn); return deserializeBytes(data); } /** * Deserialize the DLSN from bytes array. * * @param data * serialized bytes * @return dlsn */ public static DLSN deserializeBytes(byte[] data) { ByteBuffer bb = ByteBuffer.wrap(data); byte version = bb.get(); if (VERSION0 == version) { if (VERSION0_LEN != data.length) { throw new IllegalArgumentException("Invalid version zero DLSN " + Hex.encodeHexString(data)); } } else if (VERSION1 == version) { if (VERSION1_LEN != data.length) { throw new IllegalArgumentException("Invalid version one DLSN " + Hex.encodeHexString(data)); } } else { throw new IllegalArgumentException( "Invalid DLSN : version = " + version + ", " + Hex.encodeHexString(data)); } return new DLSN(bb.getLong(), bb.getLong(), bb.getLong()); } // Keep original version0 logic for testing. @VisibleForTesting static DLSN deserialize0(String dlsn) { byte[] data = Base64.decodeBase64(dlsn); ByteBuffer bb = ByteBuffer.wrap(data); byte version = bb.get(); if (VERSION0 != version || VERSION0_LEN != data.length) { throw new IllegalArgumentException("Invalid DLSN " + dlsn); } return new DLSN(bb.getLong(), bb.getLong(), bb.getLong()); } @Override public String toString() { return "DLSN{" + "logSegmentSequenceNo=" + logSegmentSequenceNo + ", entryId=" + entryId + ", slotId=" + slotId + '}'; } @Override public boolean equals(Object o) { if (this == o) return true; if (!(o instanceof DLSN)) return false; DLSN dlsn = (DLSN) o; if (entryId != dlsn.entryId) return false; if (logSegmentSequenceNo != dlsn.logSegmentSequenceNo) return false; if (slotId != dlsn.slotId) return false; return true; } @Override public int hashCode() { int result = (int) (logSegmentSequenceNo ^ (logSegmentSequenceNo >>> 32)); result = 31 * result + (int) (entryId ^ (entryId >>> 32)); result = 31 * result + (int) (slotId ^ (slotId >>> 32)); return result; } /** * Positions to a DLSN greater than the current value - this may not * correspond to an actual LogRecord, its just used by the positioning logic * to position the reader * * @return the next DLSN */ public DLSN getNextDLSN() { return new DLSN(logSegmentSequenceNo, entryId, slotId + 1); } /** * Positions to a DLSN greater than the current value - this may not * correspond to an actual LogRecord, its just used by the positioning logic * to position the reader * * @return the next DLSN */ public DLSN positionOnTheNextLedger() { return new DLSN(logSegmentSequenceNo + 1, 0, 0); } }