001    /**
002     * Copyright 2005-2012 The Kuali Foundation
003     *
004     * Licensed under the Educational Community License, Version 2.0 (the "License");
005     * you may not use this file except in compliance with the License.
006     * You may obtain a copy of the License at
007     *
008     * http://www.opensource.org/licenses/ecl2.php
009     *
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS,
012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013     * See the License for the specific language governing permissions and
014     * limitations under the License.
015     */
016    package org.kuali.rice.krms.api.engine;
017    
018    import java.util.Map;
019    import java.util.Set;
020    
021    /**
022     * The ExecutionEnvironment manages contextual information which is made available to
023     * different components of the rules engine during execution.  Facts can be retrieved
024     * from and published to the environment.  It also provides a reference to the
025     * {@link EngineResults} or tracking engine activity and returning values back to
026     * the client of the rules engine.
027     * 
028     * @author Kuali Rice Team (rice.collab@kuali.org)
029     *
030     */
031    public interface ExecutionEnvironment {
032            
033            /**
034             * Returns the selection criteria that was used to initialize the environment.
035             * 
036             * @return the selection criteria for this environment
037             */
038            public SelectionCriteria getSelectionCriteria();
039            
040            /**
041             * Returns an immutable Map of facts available within this environment.
042             * 
043             * @return the facts in this environment
044             */
045            public Map<Term, Object> getFacts();
046    
047            /**
048             * Publishes a new fact
049             * 
050             * @param factName name of the fact to publish
051             * @param factValue value of the fact to publish
052             * // TODO: we don't support updating facts, refactor this method
053             * @return true if an existing fact was updated, false if this was a new fact
054             */
055            public boolean publishFact(Term factName, Object factValue);
056    
057        /**
058         * Add a {@link TermResolver}
059         * @param termResolver
060         */
061            public void addTermResolver(TermResolver<?> termResolver);
062    
063        /**
064         * Resolve
065         * @param term {@link Term}
066         * @param caller
067         * @return <T> T
068         * @throws {@link TermResolutionException}
069         */
070            public <T> T resolveTerm(Term term, Object caller) throws TermResolutionException;
071    
072        /**
073         * Return a set of Term for the given value
074         * @param caller
075         * @return Set<Term>
076         */
077            public Set<Term> getTermsForCaller(Object caller);
078    
079        /**
080         * Return the {@link ExecutionOptions}
081         * @return {@link ExecutionOptions}
082         */
083            public ExecutionOptions getExecutionOptions();
084    
085        /**
086         * Return the {@link EngineResults}
087         * @return {@link EngineResults}
088         */
089            public EngineResults getEngineResults();
090            
091    }