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
022/**
023 * Interface to be implemented by any rules executed by the enforcer.
024 *
025 * @author <a href="mailto:brianf@apache.org">Brian Fox</a>
026 * @version $Id: EnforcerRule.java 987781 2010-08-21 16:23:40Z dennisl $
027 */
028public interface EnforcerRule
029{
030
031    /**
032     * This is the interface into the rule. This method should throw an exception
033     * containing a reason message if the rule fails the check. The plugin will
034     * then decide based on the fail flag if it should stop or just log the
035     * message as a warning.
036     *
037     * @param helper The helper provides access to the log, MavenSession and has
038     * helpers to get common components. It is also able to lookup components
039     * by class name.
040     *
041     * @throws EnforcerRuleException the enforcer rule exception
042     */
043    void execute( EnforcerRuleHelper helper )
044        throws EnforcerRuleException;
045
046    /**
047     * This method tells the enforcer if the rule results may be cached. If the result is true,
048     * the results will be remembered for future executions in the same build (ie children). Subsequent
049     * iterations of the rule will be queried to see if they are also cacheable. This will allow the rule to be
050     * uncached further down the tree if needed.
051     *
052     * @return <code>true</code> if rule is cacheable
053     */
054    boolean isCacheable();
055
056    /**
057     * Checks if cached result is valid.
058     *
059     * @param cachedRule the last cached instance of the rule. This is to be used by the rule to
060     * potentially determine if the results are still valid (ie if the configuration has been overridden)
061     *
062     * @return <code>true</code> if the stored results are valid for the same id.
063     */
064    boolean isResultValid( EnforcerRule cachedRule );
065
066    /**
067     * If the rule is to be cached, this id is used as part of the key. This can allow rules to take parameters
068     * that allow multiple results of the same rule to be cached.
069     *
070     * @return id to be used by the enforcer to determine uniqueness of cache results. The ids only need to be unique
071     * within a given rule implementation as the full key will be [classname]-[id]
072     */
073    String getCacheId();
074
075}