View Javadoc

1   /*
2    * Copyright 2006 - 2012 Christina Bohk and Roland Ewald
3    *  
4    * Licensed under the Apache 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.apache.org/licenses/LICENSE-2.0
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 p3j.pppm.sets;
17  
18  import java.io.Serializable;
19  import java.util.HashMap;
20  import java.util.List;
21  import java.util.Map;
22  
23  import p3j.pppm.IStochasticOccurrence;
24  import p3j.pppm.parameters.ParameterAssignment;
25  import p3j.pppm.parameters.ParameterAssignmentSet;
26  import p3j.pppm.parameters.ParameterInstance;
27  
28  /**
29   * Represents a set in PPPM. A set is associated with a certain {@link SetType},
30   * which defines for which {@link ParameterInstance} objects this set may define
31   * eligible {@link ParameterAssignment} objects. A set has a certain probability
32   * of occurrence and will be randomly chosen from a list with all sets
33   * associated with the same {@link SetType}. If it is chosen, for each
34   * {@link ParameterInstance} that is defined by its {@link SetType} one
35   * {@link ParameterAssignment} from this {@link Set} will be chosen randomly
36   * (so, there are two levels of random choosing, one in the {@link SetType}, one
37   * in the {@link Set}). The eligible {@link ParameterAssignment} objects are
38   * stored in a {@link Map}, there is a {@link List} for each
39   * {@link ParameterInstance}.
40   * 
41   * See documentation of {@link SetType} for more information.
42   * 
43   * Created on August 7, 2006
44   * 
45   * @author Christina Bohk
46   * @author Roland Ewald
47   * 
48   */
49  public class Set implements Serializable, IStochasticOccurrence {
50  
51  	/** Serialization ID. */
52  	private static final long serialVersionUID = -4332835814925514014L;
53  
54  	/** ID of this set. */
55  	private int id;
56  
57  	/** Name of the set. */
58  	private String name = "";
59  
60  	/** Probability that this set will be chosen. */
61  	private double probability;
62  
63  	/** Description of the set. */
64  	private String description = "";
65  
66  	/**
67  	 * Mapping from {@link ParameterInstance} objects to lists of their eligible
68  	 * {@link ParameterAssignment} objects.
69  	 */
70  	private Map<ParameterInstance, ParameterAssignmentSet> setData = new HashMap<ParameterInstance, ParameterAssignmentSet>();
71  
72  	/**
73  	 * Default constructor.
74  	 * 
75  	 * @param definedParameters
76  	 *          set of parameter instances for which this set may define
77  	 *          assignments
78  	 * @param setName
79  	 *          name of the set
80  	 * @param desc
81  	 *          description of the set
82  	 * @param prob
83  	 *          probability of the set
84  	 */
85  	public Set(List<ParameterInstance> definedParameters, String setName,
86  	    String desc, double prob) {
87  		this.name = setName;
88  		this.description = desc;
89  		this.probability = prob;
90  
91  		for (ParameterInstance instance : definedParameters) {
92  			addParameterInstance(instance);
93  		}
94  	}
95  
96  	/**
97  	 * Constructor for bean compatibility.
98  	 */
99  	public Set() {
100 	}
101 
102 	/**
103 	 * Get eligible {@link ParameterAssignment} objects for given
104 	 * {@link ParameterInstance}.
105 	 * 
106 	 * @param paramInstance
107 	 *          the parameter instance
108 	 * @return list of parameter assignments
109 	 */
110 	public ParameterAssignmentSet getParameterAssignments(
111 	    ParameterInstance paramInstance) {
112 		return setData.get(paramInstance);
113 	}
114 
115 	/**
116 	 * Adds a parameter instance to the set. This adds an empty list of eligible
117 	 * {@link ParameterAssignment} objects to {@link Set#setData}. This is a
118 	 * management method for the associated {@link SetType}.
119 	 * 
120 	 * @param parameterInstance
121 	 *          the parameter instance to be added
122 	 */
123 	public final void addParameterInstance(ParameterInstance parameterInstance) {
124 		setData.put(parameterInstance, new ParameterAssignmentSet());
125 	}
126 
127 	/**
128 	 * Removes a parameter instance from the set. All associated
129 	 * {@link ParameterAssignment} objects will be removed from
130 	 * {@link Set#setData}. This is a management method for the associated
131 	 * {@link SetType}.
132 	 * 
133 	 * @param parameterInstance
134 	 *          the parameter instance to be removed
135 	 * @return assignments associated with removed parameter instance (null if not
136 	 *         existing)
137 	 */
138 	public ParameterAssignmentSet removeParameterInstance(
139 	    ParameterInstance parameterInstance) {
140 		return setData.remove(parameterInstance);
141 	}
142 
143 	/**
144 	 * Adds a new parameter assignment.
145 	 * 
146 	 * @param paramAssign
147 	 *          parameter assignment to be added
148 	 */
149 	public void addParameterAssignment(ParameterAssignment paramAssign) {
150 		ParameterAssignmentSet paramAssignments = setData.get(paramAssign
151 		    .getParamInstance());
152 		if (paramAssignments == null) {
153 			setProblemOccurred(paramAssign);
154 		} else {
155 			paramAssignments.add(paramAssign);
156 		}
157 	}
158 
159 	/**
160 	 * Removes a parameter assignment.
161 	 * 
162 	 * @param paramAssign
163 	 *          parameter assignment to be removed
164 	 */
165 	public void removeParameterAssignment(ParameterAssignment paramAssign) {
166 		ParameterAssignmentSet paramAssignments = setData.get(paramAssign
167 		    .getParamInstance());
168 		if (paramAssignments == null) {
169 			setProblemOccurred(paramAssign);
170 		} else {
171 			paramAssignments.remove(paramAssign);
172 		}
173 	}
174 
175 	/**
176 	 * Throws a {@link RuntimeException} reporting on problems while processing a
177 	 * {@link ParameterAssignment}. This method is called when the
178 	 * {@link ParameterInstance} associated with the {@link ParameterAssignment}
179 	 * is not managed by the {@link SetType} of this set.
180 	 * 
181 	 * @param assignment
182 	 *          the parameter assignment to be processed
183 	 */
184 	protected void setProblemOccurred(ParameterAssignment assignment) {
185 		throw new IllegalArgumentException(
186 		    "PPPM Set: Cannot process parameter assignment '"
187 		        + assignment.getName() + "'. Its instance '"
188 		        + assignment.getParamInstance()
189 		        + "' seems to be managed by another Settype !");
190 	}
191 
192 	/**
193 	 * Retrieve the number of eligible {@link ParameterAssignment} objects for a
194 	 * given {@link ParameterInstance}.
195 	 * 
196 	 * @param instance
197 	 *          the parameter instance
198 	 * @return number of assignments for given instance
199 	 */
200 	public int getNumberOfAssignments(ParameterInstance instance) {
201 		ParameterAssignmentSet assignments = setData.get(instance);
202 		return assignments != null ? assignments.size() : 0;
203 	}
204 
205 	/**
206 	 * Checks whether this set contains at least one assignment for every
207 	 * parameter instance.
208 	 * 
209 	 * @return true, if set is valid (i.e. above condition is satisfied)
210 	 */
211 	public boolean isValid() {
212 		for (ParameterAssignmentSet paramAssignmentSet : setData.values()) {
213 			if (paramAssignmentSet.size() == 0) {
214 				return false;
215 			}
216 		}
217 		return true;
218 	}
219 
220 	@Override
221 	public void setProbability(double probability) {
222 		if (probability < 0 || probability > 1) {
223 			throw new IllegalArgumentException("A probability value of "
224 			    + probability + " is not meaningful!");
225 		}
226 		this.probability = probability;
227 	}
228 
229 	@Override
230 	public String toString() {
231 		return name;
232 	}
233 
234 	// Getter/Setter for bean compatibility
235 
236 	public Map<ParameterInstance, ParameterAssignmentSet> getSetData() {
237 		return setData;
238 	}
239 
240 	public void setSetData(Map<ParameterInstance, ParameterAssignmentSet> setData) {
241 		this.setData = setData;
242 	}
243 
244 	public String getDescription() {
245 		return description;
246 	}
247 
248 	public void setDescription(String description) {
249 		this.description = description;
250 	}
251 
252 	public String getName() {
253 		return name;
254 	}
255 
256 	public void setName(String name) {
257 		this.name = name;
258 	}
259 
260 	@Override
261 	public double getProbability() {
262 		return this.probability;
263 	}
264 
265 	public int getID() {
266 		return id;
267 	}
268 
269 	public void setID(int uniqueID) {
270 		id = uniqueID;
271 	}
272 
273 }