1 /**
2 * Copyright 2005-2011 The Kuali Foundation
3 *
4 * Licensed under the Educational Community License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.opensource.org/licenses/ecl2.php
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.kuali.rice.krms.api.engine;
17
18 import java.util.Collections;
19 import java.util.HashMap;
20 import java.util.Map;
21
22 import org.apache.commons.lang.StringUtils;
23
24 /**
25 * The ExecutionOptions contain a set of options that can be passed to the KRMS
26 * engine to control certain aspects related to it's execution. It supports
27 * two different types of options:
28 *
29 * <ol>
30 * <li>flags - a map of pre-defined boolean {@link ExecutionFlag} instances which can be either true or false</li>
31 * <li>options - a general-purpose map of Strings which can be used to define optinos that have non-boolen values</li>
32 * </ol>
33 *
34 * <p>The options map can be used to pass user-defined or provider-specific options. The ExecutionOptions are made
35 * available as part of the {@link ExecutionEnvironment} during engine execution.
36 *
37 * <p>Instances of ExecutionOptions are not safe for use by multiple threads.
38 *
39 * @author Kuali Rice Team (rice.collab@kuali.org)
40 *
41 */
42 public final class ExecutionOptions {
43
44 private final Map<ExecutionFlag, Boolean> flags;
45 private final Map<String, String> options;
46
47 /**
48 * Construct an empty set of execution options.
49 */
50 public ExecutionOptions() {
51 flags = new HashMap<ExecutionFlag, Boolean>();
52 options = new HashMap<String, String>();
53 }
54
55 /**
56 * Constructs a new set of execution options, initialized with all options
57 * and flags copied from the given set of execution options.
58 *
59 * @param executionOptions the execution options from which to copy into the newly created instance.
60 * If the given execution options are null, then this constructor is equivalent to {@link ExecutionOptions#ExecutionOptions()}
61 */
62 public ExecutionOptions(ExecutionOptions executionOptions) {
63 this();
64 if (executionOptions != null) {
65 this.flags.putAll(executionOptions.getFlags());
66 this.options.putAll(executionOptions.getOptions());
67 }
68 }
69
70 /**
71 * Sets the value for the given flag to the given boolean value.
72 *
73 * @param flag the flag to set
74 * @param value the flag value to set
75 * @return a reference to this object
76 *
77 * @throws IllegalArgumentException if the given flag is null
78 */
79 public ExecutionOptions setFlag(ExecutionFlag flag, boolean value) {
80 if (flag == null) {
81 throw new IllegalArgumentException("flag was null");
82 }
83 flags.put(flag, value);
84 return this;
85 }
86
87 /**
88 * Sets the value for the given option name to the given value.
89 *
90 * @param optionName the name of the option to set
91 * @param value the value of the option to set
92 * @return a reference to this object
93 *
94 * @throws IllegalArgumentException if the given optionName is blank
95 */
96 public ExecutionOptions setOption(String optionName, String value) {
97 if (StringUtils.isBlank(optionName)) {
98 throw new IllegalArgumentException("optionName was blank");
99 }
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 }