VersionControlIgnoresPlugin.java

package org.bndtools.versioncontrol.ignores.manager.api;

import java.io.File;
import java.util.List;

import org.bndtools.api.NamedPlugin;
import org.osgi.annotation.versioning.ConsumerType;

/**
 * <p>
 * The interface of a version control ignores plugin.
 * </p>
 * <p>
 * A version control ignores plugin can apply ignore globs (in Git format) to a directory that is under version control
 * of a certain version control system.
 * </p>
 * <p>
 * Bndtools internally always works with ignore globs in Git format. It is the responsibility of the plugin to interpret
 * those globs and translate them into the appropriate format.
 * </p>
 */
@ConsumerType
public interface VersionControlIgnoresPlugin {
    /**
     * @return generic plugin information
     */
    NamedPlugin getInformation();

    /**
     * @return true when the version control system can store empty directories, false otherwise
     */
    boolean canStoreEmptyDirectories();

    /**
     * @param repositoryProviderId
     *            the Eclipse plugin id that provides version control for a project
     * @return true when this plugin provides can apply version control ignore globs for the specified
     *         repositoryProviderId
     */
    boolean matchesRepositoryProviderId(String repositoryProviderId);

    /**
     * Apply version control ignore globs to a directory.
     * 
     * @param dstDir
     *            the destination directory
     * @param ignores
     *            a list of ignore globs (in Git format). Can be empty, which specifically is the case when the
     *            destination directory contains no files and when {@link #canStoreEmptyDirectories()} returned false.
     * @throws Exception
     *             upon error(s)
     */
    void addIgnores(File dstDir, List<String> ignores) throws Exception;
}