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 */
018 package org.apache.hadoop.hdfs.server.namenode;
019
020 import java.io.Closeable;
021 import java.io.IOException;
022
023 import org.apache.hadoop.classification.InterfaceAudience;
024 import org.apache.hadoop.classification.InterfaceStability;
025 import org.apache.hadoop.hdfs.server.common.Storage;
026 import org.apache.hadoop.hdfs.server.common.Storage.FormatConfirmable;
027 import org.apache.hadoop.hdfs.server.common.StorageInfo;
028 import org.apache.hadoop.hdfs.server.protocol.NamespaceInfo;
029
030 /**
031 * A JournalManager is responsible for managing a single place of storing
032 * edit logs. It may correspond to multiple files, a backup node, etc.
033 * Even when the actual underlying storage is rolled, or failed and restored,
034 * each conceptual place of storage corresponds to exactly one instance of
035 * this class, which is created when the EditLog is first opened.
036 */
037 @InterfaceAudience.Private
038 @InterfaceStability.Evolving
039 public interface JournalManager extends Closeable, LogsPurgeable,
040 FormatConfirmable {
041
042 /**
043 * Format the underlying storage, removing any previously
044 * stored data.
045 */
046 void format(NamespaceInfo ns) throws IOException;
047
048 /**
049 * Begin writing to a new segment of the log stream, which starts at
050 * the given transaction ID.
051 */
052 EditLogOutputStream startLogSegment(long txId, int layoutVersion)
053 throws IOException;
054
055 /**
056 * Mark the log segment that spans from firstTxId to lastTxId
057 * as finalized and complete.
058 */
059 void finalizeLogSegment(long firstTxId, long lastTxId) throws IOException;
060
061 /**
062 * Set the amount of memory that this stream should use to buffer edits
063 */
064 void setOutputBufferCapacity(int size);
065
066 /**
067 * Recover segments which have not been finalized.
068 */
069 void recoverUnfinalizedSegments() throws IOException;
070
071 /**
072 * Perform any steps that must succeed across all JournalManagers involved in
073 * an upgrade before proceeding onto the actual upgrade stage. If a call to
074 * any JM's doPreUpgrade method fails, then doUpgrade will not be called for
075 * any JM.
076 */
077 void doPreUpgrade() throws IOException;
078
079 /**
080 * Perform the actual upgrade of the JM. After this is completed, the NN can
081 * begin to use the new upgraded metadata. This metadata may later be either
082 * finalized or rolled back to the previous state.
083 *
084 * @param storage info about the new upgraded versions.
085 */
086 void doUpgrade(Storage storage) throws IOException;
087
088 /**
089 * Finalize the upgrade. JMs should purge any state that they had been keeping
090 * around during the upgrade process. After this is completed, rollback is no
091 * longer allowed.
092 */
093 void doFinalize() throws IOException;
094
095 /**
096 * Return true if this JM can roll back to the previous storage state, false
097 * otherwise. The NN will refuse to run the rollback operation unless at least
098 * one JM or fsimage storage directory can roll back.
099 *
100 * @param storage the storage info for the current state
101 * @param prevStorage the storage info for the previous (unupgraded) state
102 * @param targetLayoutVersion the layout version we intend to roll back to
103 * @return true if this JM can roll back, false otherwise.
104 */
105 boolean canRollBack(StorageInfo storage, StorageInfo prevStorage,
106 int targetLayoutVersion) throws IOException;
107
108 /**
109 * Perform the rollback to the previous FS state. JMs which do not need to
110 * roll back their state should just return without error.
111 */
112 void doRollback() throws IOException;
113
114 /**
115 * @return the CTime of the journal manager.
116 */
117 long getJournalCTime() throws IOException;
118
119 /**
120 * Discard the segments whose first txid is >= the given txid.
121 * @param startTxId The given txid should be right at the segment boundary,
122 * i.e., it should be the first txid of some segment, if segment corresponding
123 * to the txid exists.
124 */
125 void discardSegments(long startTxId) throws IOException;
126
127 /**
128 * Close the journal manager, freeing any resources it may hold.
129 */
130 @Override
131 void close() throws IOException;
132
133 /**
134 * Indicate that a journal is cannot be used to load a certain range of
135 * edits.
136 * This exception occurs in the case of a gap in the transactions, or a
137 * corrupt edit file.
138 */
139 public static class CorruptionException extends IOException {
140 static final long serialVersionUID = -4687802717006172702L;
141
142 public CorruptionException(String reason) {
143 super(reason);
144 }
145 }
146
147 }