rule.java

rule engine drools-2.0-beta-18

package org.drools.rule;

/*
 * $Id: Rule.java,v 1.51 2004/11/28 20:01:12 mproctor Exp $
 *
 * Copyright 2001-2003 (C) The Werken Company. All Rights Reserved.
 *
 * Redistribution and use of this software and associated documentation
 * ("Software"), with or without modification, are permitted provided that the
 * following conditions are met:
 *
 * 1. Redistributions of source code must retain copyright statements and
 * notices. Redistributions must also contain a copy of this document.
 *
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 * this list of conditions and the following disclaimer in the documentation
 * and/or other materials provided with the distribution.
 *
 * 3. The name "drools" must not be used to endorse or promote products derived
 * from this Software without prior written permission of The Werken Company.
 * For written permission, please contact [e-mail].
 *
 * 4. Products derived from this Software may not be called "drools" nor may
 * "drools" appear in their names without prior written permission of The Werken
 * Company. "drools" is a trademark of The Werken Company.
 *
 * 5. Due credit should be given to The Werken Company. (http://werken.com/)
 *
 * THIS SOFTWARE IS PROVIDED BY THE WERKEN COMPANY AND CONTRIBUTORS ``AS IS''
 * AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE WERKEN COMPANY OR ITS CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *
 */

import org.drools.spi.Condition;
import org.drools.spi.Consequence;
import org.drools.spi.Duration;
import org.drools.spi.ObjectType;

import java.io.Serializable;
import java.util.ArrayList;
import java.util.Collections;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.Set;

/**
 * A set of <code>Condition</code> s and a <code>Consequence</code>.
 *
 * The <code>Conditions</code> describe the circumstances that represent a
 * match for this rule. The <code>Consequence</code> gets fired when the
 * <code>Conditions</code> match.
 *
 * @see Condition
 * @see Consequence
 *
 * @author <a href="mailto:[e-mail]">bob mcwhirter </a>
 * @author <a href="mailto:[e-mail]">Simon Harris </a>
 */
public class Rule
    implements
    Serializable
{
    // ------------------------------------------------------------
    // Instance members
    // ------------------------------------------------------------
    
    private RuleSet ruleSet;

    /** Name of the rule. */
    private final String name;

    /** Documentation. */
    private String documentation;

    /** Salience value. */
    private int salience;

    /** Formal parameter declarations. */
    private final List parameterDeclarations = new ArrayList( );

    /** Conditions. */
    private final List conditions = new ArrayList( );

    /** Consequence. */
    private Consequence consequence;

    /** Truthness duration. */
    private Duration duration;

    /** Load order in RuleSet */
    private long loadOrder;

    /** is the consequence of the rule currently being executed? */
    private boolean noLoop;

    private Set imports;
    
    private Map applicationData;

    // ------------------------------------------------------------
    // Constructors
    // ------------------------------------------------------------

    /**
     * Construct.
     *
     * @param name
     *            The name of this rule.
     */
    public Rule(String name, RuleSet ruleSet)
    {
        this.name = name;
        this.ruleSet = ruleSet;
        this.imports = Collections.EMPTY_SET;
    }    
    
    /**
     * Construct.
     *
     * @param name
     *            The name of this rule.
     */
    public Rule(String name)
    {
        this(name, null);
    }

    /**
     * Set the documentation.
     *
     * @param documentation
     *            The documentation.
     */
    public void setDocumentation(String documentation)
    {
        this.documentation = documentation;
    }

    /**
     * Retrieve the documentation.
     *
     * @return The documentation or <code>null</code> if none.
     */
    public String getDocumentation()
    {
        return this.documentation;
    }

    /**
     * Set the truthness duration.
     *
     * <p>
     * This is merely a convenience method for calling
     * {@link #setDuration(Duration)}with a <code>FixedDuration</code>.
     * </p>
     *
     * @see #setDuration(Duration)
     * @see FixedDuration
     *
     * @param seconds
     *            The number of seconds the rule must hold true in order to
     *            fire.
     */
    public void setDuration(long seconds)
    {
        this.duration = new FixedDuration( seconds );
    }

    /**
     * Set the truthness duration object.
     *
     * @param duration
     *            The truth duration object.
     */
    public void setDuration(Duration duration)
    {
        this.duration = duration;
    }

    /**
     * Retrieve the truthness duration object.
     *
     * @return The truthness duration object.
     */
    public Duration getDuration()
    {
        return this.duration;
    }

    /**
     * Determine if this rule is internally consistent and valid.
     *
     * @return <code>true</code> if this rule is valid, else
     *         <code>false</code>.
     */
    public boolean isValid()
    {
        return !( getParameterDeclarations( ).isEmpty( ) || getConditions( ).isEmpty( ) ) && getConsequence( ) != null;
    }

    /**
     * Check the validity of this rule, and throw exceptions if it fails
     * validity tests.
     *
     * <p>
     * Possibly exceptions include:
     * </p>
     *
     * <pre>
     * NoParameterDeclarationException
     * </pre>
     *
     * <p>
     * A <code>Rule</code> must include at least one parameter declaration and
     * one condition.
     * </p>
     *
     * @throws InvalidRuleException
     *             if this rule is in any way invalid.
     */
    public void checkValidity() throws InvalidRuleException
    {
        if ( getParameterDeclarations( ).isEmpty( ) )
        {
            throw new NoParameterDeclarationException( this );
        }
        if ( getConsequence( ) == null )
        {
            throw new NoConsequenceException( this );
        }
    }

    public RuleSet getRule()
    {
        return this.ruleSet;
    }
    
    /**
     * Retrieve the name of this rule.
     *
     * @return The name of this rule.
     */
    public String getName()
    {
        return this.name;
    }

    /**
     * Retrieve the <code>Rule</code> salience.
     *
     * @return The salience.
     */
    public int getSalience()
    {
        return this.salience;
    }

    /**
     * Set the <code>Rule<code> salience.
     *
     *  @param salience The salience.
     */
    public void setSalience(int salience)
    {
        this.salience = salience;
    }

    public boolean getNoLoop()
    {
        return this.noLoop;
    }

    public void setNoLoop(boolean noLoop)
    {
        this.noLoop = noLoop;
    }

    /**
     * Add a <i>root fact object </i> parameter <code>Declaration</code> for
     * this <code>Rule</code>.
     *
     * @param identifier The identifier.
     * @param objectType The type.
     * @return The declaration.
     */
    public Declaration addParameterDeclaration(String identifier,
                                               ObjectType objectType) throws InvalidRuleException
    {
        if ( getParameterDeclaration( identifier ) != null )
        {
            throw new InvalidRuleException( this );
        }

        Declaration declaration = new Declaration( identifier,
                                                   objectType,
                                                   this.parameterDeclarations.size( ) );

        this.parameterDeclarations.add( declaration );

        return declaration;
    }

    /**
     * Retrieve a parameter <code>Declaration</code> by identifier.
     *
     * @param identifier The identifier.
     *
     * @return The declaration or <code>null</code> if no declaration matches
     *         the <code>identifier</code>.
     */
    public Declaration getParameterDeclaration(String identifier)
    {
        Declaration eachDecl;

        Iterator declIter = this.parameterDeclarations.iterator( );
        while ( declIter.hasNext() )
        {
            eachDecl = ( Declaration ) declIter.next();

            if ( eachDecl.getIdentifier().equals( identifier ) )
            {
                return eachDecl;
            }
        }

        return null;
    }

    /**
     * Retrieve the set of all <i>root fact object </i> parameter
     * <code>Declarations</code>.
     *
     * @return The Set of <code>Declarations</code> in order which specify the <i>root fact objects</i>.
     */
    public List getParameterDeclarations()
    {
        return Collections.unmodifiableList( this.parameterDeclarations );
    }

    /**
     * Add a <code>Condition</code> to this rule.
     *
     * @param condition
     *            The <code>Condition</code> to add.
     */
    public void addCondition(Condition condition)
    {
        this.conditions.add( condition );
    }

    /**
     * Retrieve the <code>List</code> of <code>Conditions</code> for this
     * rule.
     *
     * @return The <code>List</code> of <code>Conditions</code>.
     */
    public List getConditions()
    {
        return Collections.unmodifiableList( this.conditions );
    }

    public int getConditionSize()
    {
        return this.conditions.size( );
    }

    /**
     * Set the <code>Consequence</code> that is associated with the successful
     * match of this rule.
     *
     * @param consequence
     *            The <code>Consequence</code> to attach to this
     *            <code>Rule</code>.
     */
    public void setConsequence(Consequence consequence)
    {
        this.consequence = consequence;
    }

    /**
     * Retrieve the <code>Consequence</code> associated with this
     * <code>Rule</code>.
     *
     * @return The <code>Consequence</code>.
     */
    public Consequence getConsequence()
    {
        return this.consequence;
    }

    public long getLoadOrder()
    {
        return loadOrder;
    }

    void setLoadOrder(long loadOrder)
    {
        this.loadOrder = loadOrder;
    }

    public void setImports(Set imports)
    {
        this.imports = imports;
    }

    public Set getImports()
    {
        return this.imports;
    }

    public void setApplicationData(Map applicationData)
    {
        this.applicationData = applicationData;
    }

    public Map getApplicationData()
    {
        return this.applicationData;
    }    

    public String dump(String indent)
    {
        StringBuffer buffer = new StringBuffer( );
        buffer.append( indent ).append( "Rule\n" );
        buffer.append( indent ).append( "----\n" );
        buffer.append( indent ).append( "name: " );
        buffer.append( this.name );
        buffer.append( "\n" );
        buffer.append( indent ).append( "salience: " );
        buffer.append( this.salience );
        buffer.append( "\n" );
        buffer.append( indent ).append( "load order: " );
        buffer.append( this.loadOrder );
        buffer.append( "\n" );
        buffer.append( indent ).append( "duration: " );
        buffer.append( this.duration );
        buffer.append( "\n" );

        for ( Iterator i = this.parameterDeclarations.iterator( ); i.hasNext( ); )
        {
            buffer.append( indent ).append( i.next( ) );
        }

        for ( Iterator i = this.conditions.iterator( ); i.hasNext( ); )
        {
            buffer.append( indent ).append( "condition:\n" ).append( indent ).append( i.next( ) ).append( '\n' );
        }

        buffer.append( indent ).append( "consequence:\n" );
        buffer.append( indent ).append( this.consequence );
        buffer.append( "\n" );
        return buffer.toString( );
    }
}