001package co.codewizards.cloudstore.core.ignore;
002
003import java.util.regex.Pattern;
004
005/**
006 * An {@code IgnoreRule} specifies when to ignore a file.
007 * <p>
008 * If a file matches an {@code IgnoreRule}, this file is not touched by CloudStore at all. It is neither
009 * synchronised to a remote location nor is it deleted or otherwise treated.
010 * <p>
011 * There are 2 ways to declare an ignore-rule:
012 * <p>
013 * One is using a simple (shell-like) pattern on the name like
014 * "*.bak", for example. There are only the wild-cards '*' and '?' supported having the usual meaning:
015 * <ul>
016 * <li>'*' matches 0 or more arbitrary characters.</li>
017 * <li>'?' matches exactly one arbitrary character.</li>
018 * </ul>
019 * The simple pattern is specified as {@link #getNamePattern() namePattern}.
020 * <p>
021 * The other one is using a regular expression. If the property {@link #getNameRegex() nameRegex} is specified,
022 * the {@code namePattern} is ignored.
023 *
024 * @author Marco หงุ่ยตระกูล-Schulze - marco at codewizards dot co
025 */
026public interface IgnoreRule {
027
028        String getIgnoreRuleId();
029
030        void setIgnoreRuleId(String ignoreRuleId);
031
032        /**
033         * Gets a shell-style name-pattern or <code>null</code>.
034         * <p>
035         * An ignore-rule may be specified using shell-patterns like "*.jpg" or "*.b?k".
036         * They are implicitly converted to regular expressions.
037         * <p>
038         * This <b>name</b>-pattern is checked against the file's name without path as returned by
039         * {@link java.io.File#getName() File.getName()} (e.g. "image_938732.jpg").
040         * <p>
041         * If both, a {@linkplain #getNameRegex() regular expression} and a shell-pattern are
042         * specified, the regular expression is used and this pattern ignored.
043         * @return a shell-style name-pattern or <code>null</code>.
044         * @see #getNameRegex()
045         */
046        String getNamePattern();
047
048        void setNamePattern(String namePattern);
049
050        /**
051         * Gets a regular expression or <code>null</code>.
052         * <p>
053         * This regular expression must match the entire file name (without path) - not only be contained in it.
054         * For example the regular expression "tree\.jpg" matches only the file "tree.jpg" and not the file
055         * "large_tree.jpg".
056         * <p>
057         * This <b>name</b>-regex is checked against the file's name without path as returned by
058         * {@link java.io.File#getName() File.getName()} (e.g. "image_938732.jpg").
059         * @return a regular expression or <code>null</code>.
060         * @see #getNamePattern()
061         */
062        String getNameRegex();
063
064        void setNameRegex(String nameRegex);
065
066        boolean isEnabled();
067
068        void setEnabled(boolean enabled);
069
070        boolean isCaseSensitive();
071
072        void setCaseSensitive(boolean caseSensitive);
073
074        /**
075         * Gets a regular-expression-{@link Pattern} compiled from {@link #getNameRegex() nameRegex}
076         * or {@link #getNamePattern() namePattern}. If {@code nameRegex} is specified, it overrules
077         * {@code namePattern}, i.e. {@code namePattern} is used only, if {@code nameRegex == null}.
078         * @return a regular-expression-{@link Pattern} compiled from {@link #getNameRegex() nameRegex}
079         * or {@link #getNamePattern() namePattern}. <code>null</code>, if both {@code nameRegex}
080         * and {@code namePattern} are <code>null</code>.
081         */
082        Pattern getNameRegexPattern();
083}