001package org.apache.maven.enforcer.rule.api;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  You may obtain a copy of the License at
011 *
012 *  http://www.apache.org/licenses/LICENSE-2.0
013 *
014 * Unless required by applicable law or agreed to in writing,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022import javax.annotation.Nonnull;
023import javax.annotation.Nullable;
024
025/**
026 * Interface to be implemented by any rules executed by the enforcer.
027 *
028 * @author <a href="mailto:brianf@apache.org">Brian Fox</a>
029 * @version $Id: EnforcerRule.java 1663790 2015-03-03 21:07:38Z khmarbaise $
030 */
031public interface EnforcerRule
032{
033
034    /**
035     * This is the interface into the rule. This method should throw an exception
036     * containing a reason message if the rule fails the check. The plugin will
037     * then decide based on the fail flag if it should stop or just log the
038     * message as a warning.
039     *
040     * @param helper The helper provides access to the log, MavenSession and has
041     * helpers to get common components. It is also able to lookup components
042     * by class name.
043     *
044     * @throws EnforcerRuleException the enforcer rule exception
045     */
046    void execute( @Nonnull EnforcerRuleHelper helper )
047        throws EnforcerRuleException;
048
049    /**
050     * This method tells the enforcer if the rule results may be cached. If the result is true,
051     * the results will be remembered for future executions in the same build (ie children). Subsequent
052     * iterations of the rule will be queried to see if they are also cacheable. This will allow the rule to be
053     * uncached further down the tree if needed.
054     *
055     * @return <code>true</code> if rule is cacheable
056     */
057    boolean isCacheable();
058
059    /**
060     * Checks if cached result is valid.
061     *
062     * @param cachedRule the last cached instance of the rule. This is to be used by the rule to
063     * potentially determine if the results are still valid (ie if the configuration has been overridden)
064     *
065     * @return <code>true</code> if the stored results are valid for the same id.
066     */
067    boolean isResultValid( @Nonnull EnforcerRule cachedRule );
068
069    /**
070     * If the rule is to be cached, this id is used as part of the key. This can allow rules to take parameters
071     * that allow multiple results of the same rule to be cached.
072     *
073     * @return id to be used by the enforcer to determine uniqueness of cache results. The ids only need to be unique
074     * within a given rule implementation as the full key will be [classname]-[id]
075     */
076    @Nullable
077    String getCacheId();
078
079}