001 /**
002 * Copyright 2005-2014 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.Collections;
019 import java.util.HashMap;
020 import java.util.Map;
021
022 import 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 */
042 public 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 }