Source code
package org.apache.kafka.streams.processor.internals;
import org.apache.kafka.common.TopicPartition;
import org.apache.kafka.streams.processor.TaskId;
import java.util.Map;
import java.util.Set;
/**
* See {@link StoreChangelogReader}.
*/
public interface ChangelogReader extends ChangelogRegister {
/**
* Restore all registered state stores by reading from their changelogs
*
* @return the total number of records restored in this call
*/
long restore(final Map<TaskId, Task> tasks);
/**
* Transit to restore active changelogs mode
*/
void enforceRestoreActive();
/**
* Transit to update standby changelogs mode
*/
void transitToUpdateStandby();
/**
* @return true if the reader is in restoring active changelog mode;
* false if the reader is in updating standby changelog mode
*/
boolean isRestoringActive();
/**
* @return the changelog partitions that have been completed restoring
*/
Set<TopicPartition> completedChangelogs();
/**
* @return the logical changelog partitions end-offsets
*/
Map<TopicPartition, Long> logicalChangelogEndOffsets();
/**
* Returns whether all changelog partitions were completely read.
*
* Since changelog partitions for standby tasks are never completely read, this method will always return
* {@code false} if the changelog reader registered changelog partitions for standby tasks.
*
* @return {@code true} if all changelog partitions were completely read and no standby changelog partitions are read,
* {@code false} otherwise
*/
boolean allChangelogsCompleted();
/**
* Clear all partitions
*/
void clear();
/**
* @return whether the changelog reader has just been cleared or is uninitialized
*/
boolean isEmpty();
}
Run 1
This interface is highly readable. It follows a logical structure, grouping related methods (restore/completion, state transitions, status checks) cleanly. There is no nesting; the code is entirely flat. Each method's intent is clearly expressed through descriptive names and Javadoc comments, including nuanced behavior like standby changelogs never being fully read. The code is concise—no method implementations clutter the interface, and comments are informative without being verbose. Action granularity is excellent: each method declaration occupies one line within a clear signature. Reading flow is natural, starting with the primary restoration method, then mode transitions, status queries, and cleanup. The only minor deduction is the slight redundancy in some Javadoc, but it does not hinder readability. Overall, this is an exemplary public API interface in terms of clarity and maintainability.
Run 2
This interface is highly readable. It has a clear, logical structure with a single package declaration followed by imports, then a well-documented interface. Method ordering appears intentional, grouping query methods together. There is no nesting, and each method declaration is concise, occupying exactly one line with a clear single action. Javadoc comments are consistently present and describe intent precisely, including nuanced behaviors (e.g., standby task implications). The code is not unnecessarily long; it is idiomatic Java interface design. Reading flow is natural and easy to scan. Minor deduction: a few methods (e.g., logicalChangelogEndOffsets) could benefit from slightly more elaboration in Javadoc, but overall clarity is excellent.
Run 3
This code is highly readable. It is a well-structured interface definition with clear, logical organization: imports, interface declaration, and methods grouped sensibly. Nesting is minimal—just the package and interface blocks. The intent of each method is clearly documented with Javadoc, explaining parameters, return values, and edge cases (e.g., the standby behavior in allChangelogsCompleted). Code length is concise; each method signature is short and no unnecessary code exists. Action granularity is appropriate since each method declaration is self-contained. The reading flow is natural, with methods ordered from primary operations (restore, mode transitions) to queries (state checks, getters) and finally lifecycle actions (clear, isEmpty). The only minor deduction is the lack of a class-level Javadoc description, but the @see reference and method-level docs compensate for this.
Run 1
Code Structure: A well-organized interface groups related changelog operations, with documentation for every method. Nesting: Completely flat apart from the interface scope, making it easy to scan. Clarity of intent: Descriptive method names, explicit types, and Javadoc communicate purpose; however, 'transit' is awkward wording, 'logical end-offsets' lacks explanation, and restore's tasks parameter is undocumented. Code length: Concise declarations with mostly useful documentation, although the completion-method explanation is slightly repetitive. Action granularity: Each declaration occupies its own line, with no combined operations. Reading flow: Methods progress naturally from restoration and mode switching to status queries and cleanup. Missing spacing between the package and imports, plus inconsistent comment phrasing, slightly reduce polish.
Run 2
Code Structure: A well-organized interface groups restoration, mode switching, status queries, and cleanup logically. Nesting: Flat declarations with no nested control flow make scanning easy. Clarity of intent: Descriptive method names, explicit types, and Javadoc explain responsibilities and return values; slightly awkward wording such as 'Transit to' and 'logical changelog partitions end-offsets' reduces precision. Code length: Concise signatures and mostly useful documentation avoid unnecessary bulk. Action granularity: Each declaration occupies its own line and represents a single operation or query. Reading flow: Consistent formatting and documentation provide a natural progression, though separating the package declaration and import groups with blank lines would improve visual organization.
Run 3
Code Structure: A focused interface with logically grouped restoration, status, and cleanup methods. Nesting: Flat declarations with no nested control flow. Clarity of intent: Descriptive method names and Javadoc explain responsibilities and return values; minor awkward wording such as 'Transit to' slightly reduces clarity. Code length: Concise for its contract, with useful documentation rather than unnecessary implementation detail. Action granularity: Each method declaration occupies its own line and represents a distinct operation. Reading flow: Consistent formatting and documentation make the interface easy to scan, although separating package and import sections with blank lines would improve presentation.