ParameterList.java
001 /*
002  *  ParameterList.java
003  *
004  *  Copyright (c) 1995-2012, The University of Sheffield. See the file
005  *  COPYRIGHT.txt in the software or at http://gate.ac.uk/gate/COPYRIGHT.txt
006  *
007  *  This file is part of GATE (see http://gate.ac.uk/), and is free
008  *  software, licenced under the GNU Library General Public License,
009  *  Version 2, June 1991 (in the distribution as file licence.html,
010  *  and also available at http://gate.ac.uk/gate/licence.html).
011  *
012  *  Hamish Cunningham, 15/Nov/2000
013  *
014  *  $Id: ParameterList.java 17586 2014-03-07 19:55:49Z markagreenwood $
015  */
016 
017 package gate.creole;
018 
019 import java.io.Serializable;
020 import java.util.*;
021 
022 import gate.Factory;
023 import gate.FeatureMap;
024 import gate.util.Out;
025 import gate.util.Strings;
026 
027 /** Models resource parameters lists as described in their
028   <TT>creole.xml</TT> metadata. Parameters are stored as lists
029   * of disjunctions (<TT>OR'd</TT> sets in the metadata).
030   */
031 public class ParameterList implements Serializable
032 {
033   private static final long serialVersionUID = -2690236156403182440L;
034 
035   /** Debug flag */
036   private static final boolean DEBUG = false;
037 
038   /** The runtime parameters */
039   protected List<List<Parameter>> runtimeParameters = 
040     new ArrayList<List<Parameter>>();
041 
042   /** Get the list of runtime parameters
043     * (as a list of parameter disjunctions).
044     */
045   public List<List<Parameter>> getRuntimeParameters() {
046     return runtimeParameters;
047   // getRuntimeParameters()
048 
049   /** The initialisation time parameters */
050   protected List<List<Parameter>> initimeParameters = 
051       new ArrayList<List<Parameter>>();
052 
053   /** Get the list of initialisation-time parameters
054     * (as a list of parameter disjunctions).
055     */
056   public List<List<Parameter>> getInitimeParameters() {
057     return initimeParameters;
058   // getInitimeParameters()
059 
060   /** Add a parameter disjunction.
061     * It is assumed that the parameters in a disjunction are all runtime
062     * or all init-time, never a mix of the two.
063     @exception NoSuchElementException disjunction has no more elements.
064     */
065   public boolean add(List<Parameter> disjunction) {
066     boolean status = false;
067     Iterator<Parameter> iter = disjunction.iterator();
068     Parameter param = iter.next();
069 
070     if(param.isRuntime()) {
071       status = runtimeParameters.add(disjunction);
072     else {
073       status = initimeParameters.add(disjunction);
074     }
075 
076     return status;
077   // add(param)
078 
079   /** Add all the members of a parameter list (as individual disjunctions) */
080   public boolean addAll(List<Parameter> c) {
081     boolean status = false;
082     Iterator<Parameter> iter = c.iterator();
083     while(iter.hasNext()) {
084       List<Parameter> disj = new ArrayList<Parameter>();
085       Parameter param = iter.next();
086       disj.add(param);
087       status = add(disj);
088     }
089 
090     return status;
091   // addAll(Collection)
092 
093   /** Get default runtime parameter value set.
094     * Calls <TT>getDefaults(List)</TT>.
095     @see #getDefaults(List)
096     */
097   public FeatureMap getRuntimeDefaults() throws ParameterException {
098     return getDefaults(runtimeParameters);
099   // getRuntimeDefaults()
100 
101   /** Get default initime parameter value set.
102     * Calls <TT>getDefaults(List)</TT>.
103     @see #getDefaults(List)
104     */
105   public FeatureMap getInitimeDefaults() throws ParameterException {
106     return getDefaults(initimeParameters);
107   // getInitimeDefaults()
108 
109   /** Get default parameter value set. Where more than one default
110     * is possible amongst disjunctive parameters, only the first will be set.
111     * To check if the default set is comprehensive,
112     * use <TT>isFullyDefaulted()</TT>.
113     @see #isFullyDefaulted()
114     */
115   public FeatureMap getDefaults(List<List<Parameter>> parametersthrows ParameterException {
116     FeatureMap defaults = Factory.newFeatureMap();
117 
118     // each element of the parameters list is a list of (disjunctive) params
119     Iterator<List<Parameter>> disjIter = parameters.iterator();
120 
121     // for each parameter disjunction in parameters
122     disjIterLoop:
123     while(disjIter.hasNext()) {
124       boolean optional = false// were any of this disj optional?
125 
126       // get an iterator for this disjunction of parameters
127       List<Parameter> paramDisj = disjIter.next();
128       Iterator<Parameter> paramsIter = paramDisj.iterator();
129 
130       // for each parameter in the disjunction
131       while(paramsIter.hasNext()) {
132         Parameter param = paramsIter.next();
133         if(DEBUGOut.prln("Examining " + param);
134         if(!optional)
135           optional = param.isOptional();
136 
137         // try and find a default value
138         Object defaultValue = param.calculateDefaultValue();
139 
140         // no default found
141         if(defaultValue == null) {
142           // if none of this disj were optional, and we're the last, then
143           // we've got at least one non-optional param unset
144           if(!optional && !paramsIter.hasNext()) {
145             fullyDefaulted = false;
146           }
147 
148         // valid default found - set it and continue with the next disj
149         else {
150           defaults.put(param.getName(), defaultValue);
151           continue disjIterLoop;
152         }
153       // paramsIter
154 
155     // disjIter
156 
157     return defaults;
158   // getDefaults()
159 
160 
161 // this stuff is for if we decide to do more thorough checking
162 // of parameterisation in Factory.createResource... but at present
163 // the gui checks pretty well so...
164 //
165 //  /** Analyse a parameter-value feature map and return a list
166 //    * of init time parameter disjunctions that are unset.
167 //    */
168 //  public List getUnsetInitimeParameters(FeatureMap paramValues) {
169 //    List unsetDisj = new ArrayList();
170 //
171 //    // for each init disj,
172 //    //   for each param,
173 //    //     if there's no value in paramValues
174 //    //       add this disj to rtnValue,
175 //    //       continue disjLoop
176 //  } // getUnsetInitimeParameters(paramValues)
177 //
178 //  /** Analyse a parameter-value feature map and return a list
179 //    * of runtime parameter disjunctions that are unset.
180 //    */
181 //  public List getUnsetRuntimeParameters(FeatureMap paramValues) {
182 //  } // getUnsetRuntimeParameters(paramValues)
183 //
184 //  public List getUnsetInitimeParameters(
185 //    FeatureMap paramValues, boolean includeOptional
186 //  ) {
187 //  } // getUnsetInitimeParameters(paramValues, includeOptional)
188 //
189 //  public List getUnsetRuntimeParameters(
190 //    FeatureMap paramValues, boolean includeOptional
191 //  ) {
192 //  } // getUnsetRuntimeParameters(paramValues, includeOptional)
193 //
194 
195   /** Status of the last run of <TT>getDefaults(List)</TT>. */
196   protected boolean fullyDefaulted = false;
197 
198   /** Get the status of the last run of <TT>getDefaults(List)</TT>.
199     * If the last run managed to find a default for all parameters
200     * that are part of a disjunction of which none are optional, then
201     * this status is true; else it is false.
202     @see #getDefaults(List)
203     */
204   public boolean isFullyDefaulted() { return fullyDefaulted; }
205 
206 
207   /** String representation */
208   @Override
209   public String toString() {
210     StringBuffer s = new StringBuffer(Strings.getNl() "  ParameterList:");
211 
212     Iterator<List<Parameter>> iter = getRuntimeParameters().iterator();
213     if(iter.hasNext()) s.append(Strings.getNl() "  runtime params=");
214     while(iter.hasNext()) {
215       s.append(Strings.getNl() "    ");
216       List<Parameter> paramDisj = iter.next();
217       Iterator<Parameter> iter2 = paramDisj.iterator();
218 
219       while(iter2.hasNext())
220         s.appenditer2.next() + Strings.getNl() "    " );
221     }
222 
223     iter = getInitimeParameters().iterator();
224     if(iter.hasNext()) s.append(Strings.getNl() "  initime params=");
225     while(iter.hasNext()) {
226       s.append(Strings.getNl() "    ");
227       List<Parameter> paramDisj = iter.next();
228       Iterator<Parameter> iter2 = paramDisj.iterator();
229 
230       while(iter2.hasNext())
231         s.appenditer2.next() + Strings.getNl() "    " );
232     }
233 
234     return s.toString();
235   // toString()
236 
237 // class ParameterList
238