001/**
002 * Copyright 2005-2016 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 */
016package org.kuali.rice.krms.api.engine;
017
018import java.util.Collections;
019import java.util.HashMap;
020import java.util.Map;
021
022import org.apache.commons.lang.StringUtils;
023
024/**
025 * The ExecutionOptions contain a set of options that can be passed to the KRMS
026 * engine to control certain aspects related to it's execution.  It supports
027 * two different types of options:
028 * 
029 * <ol>
030 *   <li>flags - a map of pre-defined boolean {@link ExecutionFlag} instances which can be either true or false</li>
031 *   <li>options - a general-purpose map of Strings which can be used to define optinos that have non-boolen values</li>
032 * </ol>
033 * 
034 * <p>The options map can be used to pass user-defined or provider-specific options.  The ExecutionOptions are made
035 * available as part of the {@link ExecutionEnvironment} during engine execution.
036 * 
037 * <p>Instances of ExecutionOptions are not safe for use by multiple threads.
038 * 
039 * @author Kuali Rice Team (rice.collab@kuali.org)
040 *
041 */
042public final class ExecutionOptions {
043
044        private final Map<ExecutionFlag, Boolean> flags;
045        private final Map<String, String> options;
046        
047        /**
048         * Construct an empty set of execution options.
049         */
050        public ExecutionOptions() {
051                flags = new HashMap<ExecutionFlag, Boolean>();
052                options = new HashMap<String, String>();
053        }
054        
055        /**
056         * Constructs a new set of execution options, initialized with all options
057         * and flags copied from the given set of execution options.
058         * 
059         * @param executionOptions the execution options from which to copy into the newly created instance.
060         * If the given execution options are null, then this constructor is equivalent to {@link ExecutionOptions#ExecutionOptions()}
061         */
062        public ExecutionOptions(ExecutionOptions executionOptions) {
063                this();
064                if (executionOptions != null) {
065                        this.flags.putAll(executionOptions.getFlags());
066                        this.options.putAll(executionOptions.getOptions());
067                }
068        }
069        
070        /**
071         * Sets the value for the given flag to the given boolean value.
072         * 
073         * @param flag the flag to set
074         * @param value the flag value to set
075         * @return a reference to this object
076         * 
077         * @throws IllegalArgumentException if the given flag is null
078         */
079        public ExecutionOptions setFlag(ExecutionFlag flag, boolean value) {
080                if (flag == null) {
081                        throw new IllegalArgumentException("flag was null");
082                }
083                flags.put(flag, value);
084                return this;
085        }
086        
087        /**
088         * Sets the value for the given option name to the given value.
089         * 
090         * @param optionName the name of the option to set
091         * @param value the value of the option to set
092         * @return a reference to this object
093         * 
094         * @throws IllegalArgumentException if the given optionName is blank
095         */
096        public ExecutionOptions setOption(String optionName, String value) {
097                if (StringUtils.isBlank(optionName)) {
098                        throw new IllegalArgumentException("optionName was blank");
099                }
100                options.put(optionName, value);
101                return this;
102        }
103        
104        /**
105         * Removes the specified flag (if it has been set) from the set of execution options.
106         * If the flag is not currently set, this method will do nothing.
107         * 
108         * @param flag the flag to remove
109         * @return a reference to this object
110         * 
111         * @throws IllegalArgumentException if the given flag is null
112         */
113        public ExecutionOptions removeFlag(ExecutionFlag flag) {
114                if (flag == null) {
115                        throw new IllegalArgumentException("flag was null");
116                }
117                flags.remove(flag);
118                return this;
119        }
120        
121        /**
122         * Removes the option with the specified name (if it has been set) from the set
123         * of execution options.  If the option is not currently set, this method will
124         * do nothing.
125         * 
126         * @param optionName the name of the option to remove
127         * @return a reference to this object
128         * 
129         * @throws IllegalArgumentException if the given optionName is blank
130         */
131        public ExecutionOptions removeOption(String optionName) {
132                if (StringUtils.isBlank(optionName)) {
133                        throw new IllegalArgumentException("optionName was blank");
134                }
135                options.remove(optionName);
136                return this;
137        }
138        
139        /**
140         * Returns the value the given flag.  If the specified flag has not been set
141         * on this object, then {@link ExecutionFlag#getDefaultValue()} will be returned.
142         * 
143         * @param flag the flag to check
144         * @return the value of the flag, or the flag's default value if the flag value
145         * is not currently set on this object
146         * 
147         * @throws IllegalArgumentException if the given flag is null
148         */
149        public boolean getFlag(ExecutionFlag flag) {
150                if (flag == null) {
151                        throw new IllegalArgumentException("flag is null");
152                }
153                if (isFlagSet(flag)) {
154                        return flags.get(flag).booleanValue();
155                }
156                return flag.getDefaultValue();
157        }
158        
159        /**
160         * Returns the value for the option with the given name, or null
161         * if the option is not set.
162         * 
163         * @param optionName the name of the option for which to retrieve the value
164         * @return the value of the option, or null if the option is not set
165         * 
166         * @throws IllegalArgumentException if the given optionName is blank
167         */
168        public String getOption(String optionName) {
169                if (StringUtils.isBlank(optionName)) {
170                        throw new IllegalArgumentException("optionName is blank");
171                }
172                return options.get(optionName);
173        }
174        
175        /**
176         * Checks whether or not the given flag is set.
177         * 
178         * @param flag the flag to check
179         * @return true if the flag is set, false if not
180         * 
181         * @throws IllegalArgumentException if the given flag is null
182         */
183        public boolean isFlagSet(ExecutionFlag flag) {
184                if (flag == null) {
185                        throw new IllegalArgumentException("flag is null");
186                }
187                return flags.containsKey(flag);
188        }
189        
190        /**
191         * Checks whether or not the option with the given name has been set.
192         * 
193         * @param optionName the name of the option to check
194         * @return true if the option is set, false if not
195         * 
196         * @throws IllegalArgumentException if the given optionName is blank
197         */
198        public boolean isOptionSet(String optionName) {
199                if (StringUtils.isBlank(optionName)) {
200                        throw new IllegalArgumentException("optionName is blank");
201                }
202                return options.containsKey(optionName);
203        }
204
205        /**
206         * Returns an immutable map of the flags that have been set on this object.
207         * 
208         * @return the flags that have been set, this map be empty but will never be null
209         */
210        public Map<ExecutionFlag, Boolean> getFlags() {
211                return Collections.unmodifiableMap(new HashMap<ExecutionFlag, Boolean>(flags));
212        }
213
214        /**
215         * Returns an immutable map of the options that have been set on this object.
216         * 
217         * @return the options that have been set, this map be empty but will never be null
218         */     
219        public Map<String, String> getOptions() {
220                return Collections.unmodifiableMap(new HashMap<String, String>(options));
221        }
222        
223}