run.halo.app.extension.index.Indexer Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of api Show documentation
API of halo project, connecting by other projects.
The newest version!
package run.halo.app.extension.index;

import java.util.Iterator;
import java.util.function.Function;
import org.springframework.lang.NonNull;
import run.halo.app.extension.Extension;

/**
 * The {@link Indexer} is owned by the {@link Extension} and is responsible for the lookup and
 * lifetimes of the indexes in a {@link Extension} collection. Every {@link Extension} has
 * exactly one instance of this class.
 * Callers are expected to have acquired the necessary locks while accessing this interface.
 * To inspect the contents of this {@link Indexer}, callers may obtain an iterator from
 * getIndexIterator().
 *
 * @author guqing
 * @since 2.12.0
 */
public interface Indexer {

    /**
     * Index the specified {@link Extension} by {@link IndexDescriptor}s.
     * First, the {@link Indexer} will index the {@link Extension} by the
     * {@link IndexDescriptor}s and record the index entries to {@code IndexerTransaction} and
     * commit the transaction, if any error occurs, the transaction will be rollback to keep the
     * {@link Indexer} consistent.
     *
     * @param extension the {@link Extension} to be indexed
     * @param  the type of the {@link Extension}
     */
     void indexRecord(E extension);

    /**
     * Update indexes for the specified {@link Extension} by {@link IndexDescriptor}s.
     * First, the {@link Indexer} will remove the index entries of the {@link Extension} by
     * the old {@link IndexDescriptor}s and reindex the {@link Extension} to generate change logs
     * to {@code IndexerTransaction} and commit the transaction, if any error occurs, the
     * transaction will be rollback to keep the {@link Indexer} consistent.
     *
     * @param extension the {@link Extension} to be updated
     * @param  the type of the {@link Extension}
     */
     void updateRecord(E extension);

    /**
     * Remove indexes (index entries) for the specified {@link Extension} already indexed by
     * {@link IndexDescriptor}s.
     *
     * @param extensionName the {@link Extension} to be removed
     */
    void unIndexRecord(String extensionName);

    /**
     * Find index by name.
     * The index name uniquely identifies an index.
     *
     * @param name index name
     * @return index descriptor if found, null otherwise
     */
    IndexDescriptor findIndexByName(String name);

    /**
     * Create an index entry for the specified {@link IndexDescriptor}.
     *
     * @param descriptor the {@link IndexDescriptor} to be recorded
     * @return the {@link IndexEntry} created
     */
    IndexEntry createIndexEntry(IndexDescriptor descriptor);

    /**
     * Remove all index entries that match the given {@link IndexDescriptor}.
     *
     * @param matchFn the {@link IndexDescriptor} to be matched
     */
    void removeIndexRecords(Function matchFn);

    /**
     * Get the {@link IndexEntry} by index name if found and ready.
     *
     * @param name an index name
     * @return the {@link IndexEntry} if found
     * @throws IllegalArgumentException if the index name is not found or the index is not ready
     */
    @NonNull
    IndexEntry getIndexEntry(String name);

    /**
     * Gets an iterator over all the ready {@link IndexEntry}s, in no particular order.
     *
     * @return an iterator over all the ready {@link IndexEntry}s
     * @see IndexDescriptor#isReady()
     */
    Iterator readyIndexesIterator();

    /**
     * Gets an iterator over all the {@link IndexEntry}s, in no particular order.
     *
     * @return an iterator over all the {@link IndexEntry}s
     * @see IndexDescriptor#isReady()
     */
    Iterator allIndexesIterator();

    void acquireReadLock();

    void releaseReadLock();
}