2 * Copyright (C) 2014, United States Government, as represented by the
3 * Administrator of the National Aeronautics and Space Administration.
6 * The Java Pathfinder core (jpf-core) platform is licensed under the
7 * Apache License, Version 2.0 (the "License"); you may not use this file except
8 * in compliance with the License. You may obtain a copy of the License at
10 * http://www.apache.org/licenses/LICENSE-2.0.
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
18 package gov.nasa.jpf.vm;
20 import gov.nasa.jpf.util.ObjectList;
22 import java.util.Comparator;
25 * generic interface for configurable choice generators
27 public interface ChoiceGenerator<T> extends Cloneable {
29 //--- the basic ChoiceGenerator interface, mostly used by SystemState
33 Class<T> getChoiceType();
35 boolean hasMoreChoices();
38 * to be called before the first advance(). Can be used in implementors to
39 * initialize choices from context (similar to what listeners can do from
40 * choiceGeneratorSet() notifications)
45 * advance to the next choice. This is the only method that really
46 * advances our enumeration
50 void advance(int nChoices);
52 void select(int nChoice);
58 boolean isProcessed();
61 * this has to reset the CG to its initial state, which includes resetting
66 int getTotalNumberOfChoices();
68 int getProcessedNumberOfChoices();
71 // choice getters. Note that not all CGs need to support them since
72 // there is no requirement that CGs compute finite choice sets upon creation
76 T[] getProcessedChoices();
77 T[] getUnprocessedChoices();
79 ChoiceGenerator<?> getPreviousChoiceGenerator();
81 int getNumberOfParents();
84 * turn the order of choices random (if it isn't already). Only
85 * drawback of this generic method (which might be a decorator
86 * factory) is that our type layer (e.g. IntChoiceGenerator)
87 * has to guarantee type safety. But hey - this is the first case where
88 * we can use covariant return types!
91 * - this method may alter this ChoiceGenerator and return that or return
92 * a new "decorated" version.
93 * - random data can be read from the "Random random" field in this class.
95 ChoiceGenerator<T> randomize();
97 ChoiceGenerator<?> clone() throws CloneNotSupportedException;
99 ChoiceGenerator<?> deepClone() throws CloneNotSupportedException;
105 void setIdRef(int idRef);
107 void setId(String id);
109 boolean isSchedulingPoint();
111 //--- the getters and setters for the CG creation info
112 void setThreadInfo(ThreadInfo ti);
114 ThreadInfo getThreadInfo();
116 void setInsn(Instruction insn);
118 Instruction getInsn();
120 void setContext(ThreadInfo tiCreator);
122 void setStateId (int stateId);
126 String getSourceLocation();
128 boolean supportsReordering();
131 * reorder according to a user provided comparator
132 * @returns instance to reordered CG of same choice type,
133 * null if not supported by particular CG subclass
135 * Note: this should only be called before the first advance, since it
136 * can reset the CG enumeration status
138 ChoiceGenerator<T> reorder (Comparator<T> comparator);
140 void setPreviousChoiceGenerator(ChoiceGenerator<?> cg);
145 boolean isCascaded();
147 <T extends ChoiceGenerator<?>> T getPreviousChoiceGeneratorOfType(Class<T> cls);
150 * returns the prev CG if it was registered for the same insn
152 ChoiceGenerator<?> getCascadedParent();
155 * return array with all cascaded parents and this CG, in registration order
157 ChoiceGenerator<?>[] getCascade();
160 * return array with all parents and this CG, in registration order
162 ChoiceGenerator<?>[] getAll();
165 * return array with all CGs (including this one) of given 'cgType', in registration order
167 <C extends ChoiceGenerator<?>> C[] getAllOfType(Class<C> cgType);
170 //--- the generic attribute API
173 boolean hasAttr(Class<?> attrType);
176 * this returns all of them - use either if you know there will be only
177 * one attribute at a time, or check/process result with ObjectList
182 * this replaces all of them - use only if you know
183 * - there will be only one attribute at a time
184 * - you obtained the value you set by a previous getXAttr()
185 * - you constructed a multi value list with ObjectList.createList()
187 void setAttr(Object a);
189 void addAttr(Object a);
191 void removeAttr(Object a);
193 void replaceAttr(Object oldAttr, Object newAttr);
196 * this only returns the first attr of this type, there can be more
197 * if you don't use client private types or the provided type is too general
199 <A> A getAttr(Class<A> attrType);
201 <A> A getNextAttr(Class<A> attrType, Object prev);
203 ObjectList.Iterator attrIterator();
205 <A> ObjectList.TypedIterator<A> attrIterator(Class<A> attrType);