001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.hadoop.hbase.wal;
019
020import java.io.Closeable;
021import java.io.IOException;
022import java.util.List;
023import java.util.Map;
024import java.util.Set;
025import org.apache.hadoop.hbase.HConstants;
026import org.apache.hadoop.hbase.client.RegionInfo;
027import org.apache.hadoop.hbase.regionserver.wal.FailedLogCloseException;
028import org.apache.hadoop.hbase.regionserver.wal.WALActionsListener;
029import org.apache.hadoop.hbase.regionserver.wal.WALCoprocessorHost;
030import org.apache.hadoop.hbase.replication.regionserver.WALFileLengthProvider;
031import org.apache.yetus.audience.InterfaceAudience;
032import org.apache.yetus.audience.InterfaceStability;
033
034/**
035 * A Write Ahead Log (WAL) provides service for reading, writing waledits. This interface provides
036 * APIs for WAL users (such as RegionServer) to use the WAL (do append, sync, etc).
037 *
038 * Note that some internals, such as log rolling and performance evaluation tools, will use
039 * WAL.equals to determine if they have already seen a given WAL.
040 */
041@InterfaceAudience.Private
042@InterfaceStability.Evolving
043public interface WAL extends Closeable, WALFileLengthProvider {
044
045  /**
046   * Registers WALActionsListener
047   */
048  void registerWALActionsListener(final WALActionsListener listener);
049
050  /**
051   * Unregisters WALActionsListener
052   */
053  boolean unregisterWALActionsListener(final WALActionsListener listener);
054
055  /**
056   * Roll the log writer. That is, start writing log messages to a new file.
057   *
058   * <p/>
059   * The implementation is synchronized in order to make sure there's one rollWriter
060   * running at any given time.
061   *
062   * @return If lots of logs, flush the stores of returned regions so next time through we
063   *         can clean logs. Returns null if nothing to flush. Names are actual
064   *         region names as returned by {@link RegionInfo#getEncodedName()}
065   */
066  Map<byte[], List<byte[]>> rollWriter() throws FailedLogCloseException, IOException;
067
068  /**
069   * Roll the log writer. That is, start writing log messages to a new file.
070   *
071   * <p/>
072   * The implementation is synchronized in order to make sure there's one rollWriter
073   * running at any given time.
074   *
075   * @param force
076   *          If true, force creation of a new writer even if no entries have
077   *          been written to the current writer
078   * @return If lots of logs, flush the stores of returned regions so next time through we
079   *         can clean logs. Returns null if nothing to flush. Names are actual
080   *         region names as returned by {@link RegionInfo#getEncodedName()}
081   */
082  Map<byte[], List<byte[]>> rollWriter(boolean force) throws IOException;
083
084  /**
085   * Stop accepting new writes. If we have unsynced writes still in buffer, sync them.
086   * Extant edits are left in place in backing storage to be replayed later.
087   */
088  void shutdown() throws IOException;
089
090  /**
091   * Caller no longer needs any edits from this WAL. Implementers are free to reclaim
092   * underlying resources after this call; i.e. filesystem based WALs can archive or
093   * delete files.
094   */
095  @Override
096  void close() throws IOException;
097
098  /**
099   * Append a set of data edits to the WAL. 'Data' here means that the content in the edits will
100   * also have transitioned through the memstore.
101   * <p/>
102   * The WAL is not flushed/sync'd after this transaction completes BUT on return this edit must
103   * have its region edit/sequence id assigned else it messes up our unification of mvcc and
104   * sequenceid. On return <code>key</code> will have the region edit/sequence id filled in.
105   * @param info the regioninfo associated with append
106   * @param key Modified by this call; we add to it this edits region edit/sequence id.
107   * @param edits Edits to append. MAY CONTAIN NO EDITS for case where we want to get an edit
108   *          sequence id that is after all currently appended edits.
109   * @return Returns a 'transaction id' and <code>key</code> will have the region edit/sequence id
110   *         in it.
111   * @see #appendMarker(RegionInfo, WALKeyImpl, WALEdit)
112   */
113  long appendData(RegionInfo info, WALKeyImpl key, WALEdit edits) throws IOException;
114
115  /**
116   * Append an operational 'meta' event marker edit to the WAL. A marker meta edit could
117   * be a FlushDescriptor, a compaction marker, or a region event marker; e.g. region open
118   * or region close. The difference between a 'marker' append and a 'data' append as in
119   * {@link #appendData(RegionInfo, WALKeyImpl, WALEdit)}is that a marker will not have
120   * transitioned through the memstore.
121   * <p/>
122   * The WAL is not flushed/sync'd after this transaction completes BUT on return this edit must
123   * have its region edit/sequence id assigned else it messes up our unification of mvcc and
124   * sequenceid. On return <code>key</code> will have the region edit/sequence id filled in.
125   * @param info the regioninfo associated with append
126   * @param key Modified by this call; we add to it this edits region edit/sequence id.
127   * @param edits Edits to append. MAY CONTAIN NO EDITS for case where we want to get an edit
128   *          sequence id that is after all currently appended edits.
129   * @return Returns a 'transaction id' and <code>key</code> will have the region edit/sequence id
130   *         in it.
131   * @see #appendData(RegionInfo, WALKeyImpl, WALEdit)
132   */
133  long appendMarker(RegionInfo info, WALKeyImpl key, WALEdit edits) throws IOException;
134
135  /**
136   * updates the seuence number of a specific store.
137   * depending on the flag: replaces current seq number if the given seq id is bigger,
138   * or even if it is lower than existing one
139   */
140  void updateStore(byte[] encodedRegionName, byte[] familyName, Long sequenceid,
141      boolean onlyIfGreater);
142
143  /**
144   * Sync what we have in the WAL.
145   */
146  void sync() throws IOException;
147
148  /**
149   * Sync the WAL if the txId was not already sync'd.
150   * @param txid Transaction id to sync to.
151   */
152  void sync(long txid) throws IOException;
153
154  /**
155   * @param forceSync Flag to force sync rather than flushing to the buffer. Example - Hadoop hflush
156   *          vs hsync.
157   */
158  default void sync(boolean forceSync) throws IOException {
159    sync();
160  }
161
162  /**
163   * @param txid Transaction id to sync to.
164   * @param forceSync Flag to force sync rather than flushing to the buffer. Example - Hadoop hflush
165   *          vs hsync.
166   */
167  default void sync(long txid, boolean forceSync) throws IOException {
168    sync(txid);
169  }
170
171  /**
172   * WAL keeps track of the sequence numbers that are as yet not flushed im memstores
173   * in order to be able to do accounting to figure which WALs can be let go. This method tells WAL
174   * that some region is about to flush. The flush can be the whole region or for a column family
175   * of the region only.
176   *
177   * <p>Currently, it is expected that the update lock is held for the region; i.e. no
178   * concurrent appends while we set up cache flush.
179   * @param families Families to flush. May be a subset of all families in the region.
180   * @return Returns {@link HConstants#NO_SEQNUM} if we are flushing the whole region OR if
181   * we are flushing a subset of all families but there are no edits in those families not
182   * being flushed; in other words, this is effectively same as a flush of all of the region
183   * though we were passed a subset of regions. Otherwise, it returns the sequence id of the
184   * oldest/lowest outstanding edit.
185   * @see #completeCacheFlush(byte[], long)
186   * @see #abortCacheFlush(byte[])
187   */
188  Long startCacheFlush(final byte[] encodedRegionName, Set<byte[]> families);
189
190  Long startCacheFlush(final byte[] encodedRegionName, Map<byte[], Long> familyToSeq);
191
192  /**
193   * Complete the cache flush.
194   * @param encodedRegionName Encoded region name.
195   * @param maxFlushedSeqId The maxFlushedSeqId for this flush. There is no edit in memory that is
196   *          less that this sequence id.
197   * @see #startCacheFlush(byte[], Set)
198   * @see #abortCacheFlush(byte[])
199   */
200  void completeCacheFlush(final byte[] encodedRegionName, long maxFlushedSeqId);
201
202  /**
203   * Abort a cache flush. Call if the flush fails. Note that the only recovery
204   * for an aborted flush currently is a restart of the regionserver so the
205   * snapshot content dropped by the failure gets restored to the memstore.
206   * @param encodedRegionName Encoded region name.
207   */
208  void abortCacheFlush(byte[] encodedRegionName);
209
210  /**
211   * @return Coprocessor host.
212   */
213  WALCoprocessorHost getCoprocessorHost();
214
215  /**
216   * Gets the earliest unflushed sequence id in the memstore for the region.
217   * @param encodedRegionName The region to get the number for.
218   * @return The earliest/lowest/oldest sequence id if present, HConstants.NO_SEQNUM if absent.
219   * @deprecated Since version 1.2.0. Removing because not used and exposes subtle internal
220   * workings. Use {@link #getEarliestMemStoreSeqNum(byte[], byte[])}
221   */
222  @Deprecated
223  long getEarliestMemStoreSeqNum(byte[] encodedRegionName);
224
225  /**
226   * Gets the earliest unflushed sequence id in the memstore for the store.
227   * @param encodedRegionName The region to get the number for.
228   * @param familyName The family to get the number for.
229   * @return The earliest/lowest/oldest sequence id if present, HConstants.NO_SEQNUM if absent.
230   */
231  long getEarliestMemStoreSeqNum(byte[] encodedRegionName, byte[] familyName);
232
233  /**
234   * Human readable identifying information about the state of this WAL.
235   * Implementors are encouraged to include information appropriate for debugging.
236   * Consumers are advised not to rely on the details of the returned String; it does
237   * not have a defined structure.
238   */
239  @Override
240  String toString();
241
242  /**
243   * When outside clients need to consume persisted WALs, they rely on a provided
244   * Reader.
245   */
246  interface Reader extends Closeable {
247    Entry next() throws IOException;
248    Entry next(Entry reuse) throws IOException;
249    void seek(long pos) throws IOException;
250    long getPosition() throws IOException;
251    void reset() throws IOException;
252  }
253
254  /**
255   * Utility class that lets us keep track of the edit with it's key.
256   */
257  class Entry {
258    private final WALEdit edit;
259    private final WALKeyImpl key;
260
261    public Entry() {
262      this(new WALKeyImpl(), new WALEdit());
263    }
264
265    /**
266     * Constructor for both params
267     *
268     * @param edit log's edit
269     * @param key log's key
270     */
271    public Entry(WALKeyImpl key, WALEdit edit) {
272      this.key = key;
273      this.edit = edit;
274    }
275
276    /**
277     * Gets the edit
278     *
279     * @return edit
280     */
281    public WALEdit getEdit() {
282      return edit;
283    }
284
285    /**
286     * Gets the key
287     *
288     * @return key
289     */
290    public WALKeyImpl getKey() {
291      return key;
292    }
293
294    @Override
295    public String toString() {
296      return this.key + "=" + this.edit;
297    }
298  }
299}