1   /*
2    *  ParameterList.java
3    *
4    *  Copyright (c) 1998-2001, The University of Sheffield.
5    *
6    *  This file is part of GATE (see http://gate.ac.uk/), and is free
7    *  software, licenced under the GNU Library General Public License,
8    *  Version 2, June 1991 (in the distribution as file licence.html,
9    *  and also available at http://gate.ac.uk/gate/licence.html).
10   *
11   *  Hamish Cunningham, 15/Nov/2000
12   *
13   *  $Id: ParameterList.java,v 1.4 2001/04/05 16:12:19 hamish Exp $
14   */
15  
16  package gate.creole;
17  
18  import java.util.*;
19  import java.io.*;
20  import gate.*;
21  import gate.util.*;
22  
23  /** Models resource parameters lists as described in their
24    * <TT>creole.xml</TT> metadata. Parameters are stored as lists
25    * of disjunctions (<TT>OR'd</TT> sets in the metadata).
26    */
27  public class ParameterList implements Serializable
28  {
29    /** Debug flag */
30    private static final boolean DEBUG = false;
31  
32    /** The runtime parameters */
33    protected List runtimeParameters = new ArrayList();
34  
35    /** Get the list of runtime parameters
36      * (as a list of parameter disjunctions).
37      */
38    public List getRuntimeParameters() {
39      return runtimeParameters;
40    } // getRuntimeParameters()
41  
42    /** The initialisation time parameters */
43    protected List initimeParameters = new ArrayList();
44  
45    /** Get the list of initialisation-time parameters
46      * (as a list of parameter disjunctions).
47      */
48    public List getInitimeParameters() {
49      return initimeParameters;
50    } // getInitimeParameters()
51  
52    /** Add a parameter disjunction.
53      * It is assumed that the parameters in a disjunction are all runtime
54      * or all init-time, never a mix of the two.
55      * @exception NoSuchElementException disjunction has no more elements.
56      */
57    public boolean add(List disjunction) {
58      boolean status = false;
59      Iterator iter = disjunction.iterator();
60      Parameter param = (Parameter) iter.next();
61  
62      if(param.isRuntime()) {
63        status = runtimeParameters.add(disjunction);
64      } else {
65        status = initimeParameters.add(disjunction);
66      }
67  
68      return status;
69    } // add(param)
70  
71    /** Add all the members of a parameter list (as individual disjunctions) */
72    public boolean addAll(List c) {
73      boolean status = false;
74      Iterator iter = c.iterator();
75      while(iter.hasNext()) {
76        List disj = new ArrayList();
77        Parameter param = (Parameter) iter.next();
78        disj.add(param);
79        status = add(disj);
80      }
81  
82      return status;
83    } // addAll(Collection)
84  
85    /** Get default runtime parameter value set.
86      * Calls <TT>getDefaults(List)</TT>.
87      * @see #getDefaults(List)
88      */
89    public FeatureMap getRuntimeDefaults() throws ParameterException {
90      return getDefaults(runtimeParameters);
91    } // getRuntimeDefaults()
92  
93    /** Get default initime parameter value set.
94      * Calls <TT>getDefaults(List)</TT>.
95      * @see #getDefaults(List)
96      */
97    public FeatureMap getInitimeDefaults() throws ParameterException {
98      return getDefaults(initimeParameters);
99    } // getInitimeDefaults()
100 
101   /** Get default parameter value set. Where more than one default
102     * is possible amongst disjunctive parameters, only the first will be set.
103     * To check if the default set is comprehensive,
104     * use <TT>isFullyDefaulted()</TT>.
105     * @see #isFullyDefaulted()
106     */
107   public FeatureMap getDefaults(List parameters) throws ParameterException {
108     FeatureMap defaults = Factory.newFeatureMap();
109 
110     // each element of the parameters list is a list of (disjunctive) params
111     Iterator disjIter = parameters.iterator();
112 
113     // for each parameter disjunction in parameters
114     disjIterLoop:
115     while(disjIter.hasNext()) {
116       boolean optional = false; // were any of this disj optional?
117 
118       // get an iterator for this disjunction of parameters
119       List paramDisj = (List) disjIter.next();
120       Iterator paramsIter = paramDisj.iterator();
121 
122       // for each parameter in the disjunction
123       while(paramsIter.hasNext()) {
124         Parameter param = (Parameter) paramsIter.next();
125         if(DEBUG) Out.prln("Examining " + param);
126         if(!optional)
127           optional = param.isOptional();
128 
129         // try and find a default value
130         Object defaultValue = param.calculateDefaultValue();
131 
132         // no default found
133         if(defaultValue == null) {
134           // if none of this disj were optional, and we're the last, then
135           // we've got at least one non-optional param unset
136           if(!optional && !paramsIter.hasNext()) {
137             fullyDefaulted = false;
138           }
139 
140         // valid default found - set it and continue with the next disj
141         } else {
142           defaults.put(param.getName(), defaultValue);
143           continue disjIterLoop;
144         }
145       } // paramsIter
146 
147     } // disjIter
148 
149     return defaults;
150   } // getDefaults()
151 
152 
153 // this stuff is for if we decide to do more thorough checking
154 // of parameterisation in Factory.createResource... but at present
155 // the gui checks pretty well so...
156 //
157 //  /** Analyse a parameter-value feature map and return a list
158 //    * of init time parameter disjunctions that are unset.
159 //    */
160 //  public List getUnsetInitimeParameters(FeatureMap paramValues) {
161 //    List unsetDisj = new ArrayList();
162 //
163 //    // for each init disj,
164 //    //   for each param,
165 //    //     if there's no value in paramValues
166 //    //       add this disj to rtnValue,
167 //    //       continue disjLoop
168 //  } // getUnsetInitimeParameters(paramValues)
169 //
170 //  /** Analyse a parameter-value feature map and return a list
171 //    * of runtime parameter disjunctions that are unset.
172 //    */
173 //  public List getUnsetRuntimeParameters(FeatureMap paramValues) {
174 //  } // getUnsetRuntimeParameters(paramValues)
175 //
176 //  public List getUnsetInitimeParameters(
177 //    FeatureMap paramValues, boolean includeOptional
178 //  ) {
179 //  } // getUnsetInitimeParameters(paramValues, includeOptional)
180 //
181 //  public List getUnsetRuntimeParameters(
182 //    FeatureMap paramValues, boolean includeOptional
183 //  ) {
184 //  } // getUnsetRuntimeParameters(paramValues, includeOptional)
185 //
186 
187   /** Status of the last run of <TT>getDefaults(List)</TT>. */
188   protected boolean fullyDefaulted = false;
189 
190   /** Get the status of the last run of <TT>getDefaults(List)</TT>.
191     * If the last run managed to find a default for all parameters
192     * that are part of a disjunction of which none are optional, then
193     * this status is true; else it is false.
194     * @see #getDefaults(List)
195     */
196   public boolean isFullyDefaulted() { return fullyDefaulted; }
197 
198 
199   /** String representation */
200   public String toString() {
201     StringBuffer s = new StringBuffer(Strings.getNl() + "  ParameterList:");
202 
203     Iterator iter = getRuntimeParameters().iterator();
204     if(iter.hasNext()) s.append(Strings.getNl() + "  runtime params=");
205     while(iter.hasNext()) {
206       s.append(Strings.getNl() + "    ");
207       List paramDisj = (List) iter.next();
208       Iterator iter2 = paramDisj.iterator();
209 
210       while(iter2.hasNext())
211         s.append( (Parameter) iter2.next() + Strings.getNl() + "    " );
212     }
213 
214     iter = getInitimeParameters().iterator();
215     if(iter.hasNext()) s.append(Strings.getNl() + "  initime params=");
216     while(iter.hasNext()) {
217       s.append(Strings.getNl() + "    ");
218       List paramDisj = (List) iter.next();
219       Iterator iter2 = paramDisj.iterator();
220 
221       while(iter2.hasNext())
222         s.append( (Parameter) iter2.next() + Strings.getNl() + "    " );
223     }
224 
225     return s.toString();
226   } // toString()
227 
228 } // class ParameterList
229 
230 
231