View Javadoc

1   // WARNING: This file was automatically generated. Do not edit it directly,
2   //          or you will lose your changes.
3   
4   /*
5    * Licensed to the Apache Software Foundation (ASF) under one
6    * or more contributor license agreements.  See the NOTICE file
7    * distributed with this work for additional information
8    * regarding copyright ownership.  The ASF licenses this file
9    * to you under the Apache License, Version 2.0 (the
10   * "License"); you may not use this file except in compliance
11   * with the License.  You may obtain a copy of the License at
12   *
13   *   http://www.apache.org/licenses/LICENSE-2.0
14   *
15   * Unless required by applicable law or agreed to in writing,
16   * software distributed under the License is distributed on an
17   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
18   * KIND, either express or implied.  See the License for the
19   * specific language governing permissions and limitations
20   * under the License.
21  */
22  package org.apache.myfaces.trinidad.component;
23  
24  import javax.faces.component.ActionSource;
25  import javax.faces.context.FacesContext;
26  import javax.faces.el.MethodBinding;
27  import javax.faces.event.AbortProcessingException;
28  import javax.faces.event.ActionEvent;
29  import javax.faces.event.ActionListener;
30  import javax.faces.event.FacesEvent;
31  import javax.faces.event.PhaseId;
32  import org.apache.myfaces.trinidad.bean.FacesBean;
33  import org.apache.myfaces.trinidad.bean.PropertyKey;
34  import org.apache.myfaces.trinidad.util.ComponentUtils;
35  
36  /**
37   *
38   * UIXSingleStep is a base abstraction for components
39   *           that implement ActionSource and 
40   *           navigate back and forth through a sequence of known steps.
41   *           <section name="Events and Listeners">
42   *             UIXSingleStep implements javax.faces.component.ActionSource, which
43   *             means it is a source of javax.faces.event.ActionEvents.
44   *             <p>
45   *             The ActionEvent is delivered during the Apply Request Values phase 
46   *             when navigating back, and during the 
47   *             Invoke Application phase when navigating forward.
48   *             </p>
49   *             <p>
50   *             The nextAction/previousAction attributes are of type MethodBinding
51   *             and must (if non-null) point to an action method. The nextAction
52   *             method will be called when navigating forward, and the previousAction
53   *             method will be called when navigating back with a singleStep
54   *             component.
55   *             </p>
56   *             <p>
57   *             JSF has a default javax.faces.event.ActionListener that passes the
58   *             nextAction or previousAction outcome to the NavigationHandler.
59   *             </p>              
60   *             <p>
61   *             The nextActionListener/previousActionListener attributes are of 
62   *             type MethodBinding and must (in non-null) point to a method 
63   *             accepting an ActionEvent, with a return type of void.
64   *             When navigating to the previous step, then the previousActionListener
65   *             method is called. When navigating to the next step, the nextActionListener
66   *             method is called.
67   *             </p>       
68   *           </section>
69   *
70   * <h4>Events:</h4>
71   * <table border="1" width="100%" cellpadding="3" summary="">
72   * <tr bgcolor="#CCCCFF" class="TableHeadingColor">
73   * <th align="left">Type</th>
74   * <th align="left">Phases</th>
75   * <th align="left">Description</th>
76   * </tr>
77   * <tr class="TableRowColor">
78   * <td valign="top"><code>javax.faces.event.ActionEvent</code></td>
79   * <td valign="top" nowrap>Invoke<br>Application<br>Apply<br>Request<br>Values</td>
80   * <td valign="top">Event delivered when the "action" of the component has been
81  invoked;  for example, by clicking on a button.  The action may result
82  in page navigation.</td>
83   * </tr>
84   * <tr class="TableRowColor">
85   * <td valign="top"><code>org.apache.myfaces.trinidad.event.AttributeChangeEvent</code></td>
86   * <td valign="top" nowrap>Invoke<br>Application<br>Apply<br>Request<br>Values</td>
87   * <td valign="top">Event delivered to describe an attribute change.  Attribute change events are not delivered for any programmatic change to a property.  They are only delivered when a renderer changes a property without the application's specific request.  An example of an attribute change event might include the width of a column that supported client-side resizing.</td>
88   * </tr>
89   * </table>
90   */
91  public class UIXSingleStep extends UIXComponentBase
92                             implements ActionSource
93  {
94    static public final FacesBean.Type TYPE = new FacesBean.Type(
95      UIXComponentBase.TYPE);
96    static public final PropertyKey SELECTED_STEP_KEY =
97      TYPE.registerKey("selectedStep", Integer.class, Integer.valueOf(1));
98    static public final PropertyKey MAX_STEP_KEY =
99      TYPE.registerKey("maxStep", Integer.class, Integer.valueOf(-1));
100   static public final PropertyKey PREVIOUS_ACTION_LISTENER_KEY =
101     TYPE.registerKey("previousActionListener", MethodBinding.class, PropertyKey.CAP_NOT_BOUND | PropertyKey.CAP_STATE_HOLDER);
102   static public final PropertyKey NEXT_ACTION_LISTENER_KEY =
103     TYPE.registerKey("nextActionListener", MethodBinding.class, PropertyKey.CAP_NOT_BOUND | PropertyKey.CAP_STATE_HOLDER);
104   static public final PropertyKey NEXT_ACTION_KEY =
105     TYPE.registerKey("nextAction", MethodBinding.class, PropertyKey.CAP_NOT_BOUND | PropertyKey.CAP_STATE_HOLDER);
106   static public final PropertyKey PREVIOUS_ACTION_KEY =
107     TYPE.registerKey("previousAction", MethodBinding.class, PropertyKey.CAP_NOT_BOUND | PropertyKey.CAP_STATE_HOLDER);
108 
109   static public final String COMPONENT_FAMILY =
110     "org.apache.myfaces.trinidad.SingleStep";
111   static public final String COMPONENT_TYPE =
112     "org.apache.myfaces.trinidad.SingleStep";
113 
114   /**
115    * Construct an instance of the UIXSingleStep.
116    */
117   public UIXSingleStep()
118   {
119     super("org.apache.myfaces.trinidad.ButtonBar");
120   }
121   
122   @Override
123   public void queueEvent(FacesEvent e)
124   {
125     if (e.getSource() == this)
126     {
127       if (getActionType() == PREVIOUS_ACTION_TYPE)
128         e.setPhaseId(PhaseId.APPLY_REQUEST_VALUES);
129       else
130         e.setPhaseId(PhaseId.INVOKE_APPLICATION);
131     }
132 
133     super.queueEvent(e);
134   }
135 
136   // TODO Store as transient PropertyKey
137   public Object getActionType()
138   {
139     return _actionType;
140   }
141 
142 
143   public void setActionType(Object actionType)
144   {
145     _actionType = actionType;
146   }
147 
148 
149   // TODO if I have default listeners, then should
150   // remove (then restore) default Listeners before saving state -
151   // this note copied from form.submitButtonBase.saveState....
152   @Override
153   public Object saveState(FacesContext context)
154   {
155     return super.saveState(context);
156   }
157 
158   @Override
159   public void broadcast(FacesEvent event) throws AbortProcessingException
160   {
161     // Perform standard superclass processing
162     super.broadcast(event);
163 
164 
165     FacesContext context = getFacesContext();
166 
167     // Notify the specified listener method (if any)
168     if (event instanceof ActionEvent)
169     {
170       if (getActionType() == PREVIOUS_ACTION_TYPE)
171       {
172         broadcastToMethodBinding(event, getPreviousActionListener());
173       }
174       else
175       {
176         broadcastToMethodBinding(event, getNextActionListener());
177       }
178 
179       ActionListener defaultActionListener =
180                              context.getApplication().getActionListener();
181 
182       if (defaultActionListener != null)
183         defaultActionListener.processAction((ActionEvent) event);
184     }
185   }
186 
187   public MethodBinding getAction()
188   {
189     if ( getActionType() == PREVIOUS_ACTION_TYPE)
190       return getPreviousAction();
191 
192     return getNextAction();
193   }
194 
195   // TODO  Either make this throw an exception, or make it
196   //  execute on both back and next.
197   public void setAction(MethodBinding action)
198   {
199     if ( getActionType() == PREVIOUS_ACTION_TYPE)
200       setPreviousAction(action);
201     else
202       setNextAction(action);
203   }
204 
205   public MethodBinding getActionListener()
206   {
207     if ( getActionType() == PREVIOUS_ACTION_TYPE)
208       return getPreviousActionListener();
209 
210     return getNextActionListener();
211   }
212 
213   // TODO  Either make this throw an exception, or make it
214   //  execute on both back and next.
215   public void setActionListener(MethodBinding listener)
216   {
217     if ( getActionType() == PREVIOUS_ACTION_TYPE)
218       setPreviousActionListener(listener);
219     else
220       setNextActionListener(listener);
221   }
222 
223   /**
224    * returns true if the actionType is PREVIOUS_ACTION_TYPE
225    */
226   public boolean isImmediate()
227   {
228     return  (getActionType() == PREVIOUS_ACTION_TYPE);
229   }
230   /**
231    * no-op.
232    * For UIXSingleStep components, even though it implements ActionSource,
233    * we do no have an immediate attribute.
234    * By default, if actionType is PREVIOUS_ACTION_TYPE,
235    * we set the phase to PhaseId.APPLY_REQUEST_VALUES, else we set the
236    * phase to PhaseId.INVOKE_APPLICATION.
237    */
238   public void setImmediate(boolean immediate)
239   {
240     // do nothing
241   }
242 
243   private Object _actionType = NEXT_ACTION_TYPE;
244 
245   public static final Object NEXT_ACTION_TYPE = new Object();
246   public static final Object PREVIOUS_ACTION_TYPE = new Object();
247   // Someday we might add a cancel button?
248   // public static final Object CANCEL_ACTION_TYPE = new Object();
249 
250 
251 
252   /**
253    * Gets the current step. The valid range is 1 to maxStep.
254    *               It defaults to 1.
255    *
256    * @return  the new selectedStep value
257    */
258   final public int getSelectedStep()
259   {
260     return ComponentUtils.resolveInteger(getProperty(SELECTED_STEP_KEY), 1);
261   }
262 
263   /**
264    * Sets the current step. The valid range is 1 to maxStep.
265    *               It defaults to 1.
266    * 
267    * @param selectedStep  the new selectedStep value
268    */
269   final public void setSelectedStep(int selectedStep)
270   {
271     setProperty(SELECTED_STEP_KEY, Integer.valueOf(selectedStep));
272   }
273 
274   /**
275    * Sets the current step. The valid range is 1 to maxStep.
276    *               It defaults to 1.
277    * 
278    * @param selectedStep  the new selectedStep value
279    */
280   final public void setSelectedStep(long selectedStep)
281   {
282     setProperty(SELECTED_STEP_KEY, Long.valueOf(selectedStep));
283   }
284 
285   /**
286    * Gets the last possible step. If this value is not known, 
287    *               it should be set to
288    *               MAX_VALUE_UNKNOWN (-1),
289    *               which is also the default value. If maxStep is
290    *               MAX_VALUE_UNKNOWN, then no text is rendered between the Back/Next
291    *               buttons. When maxStep is 2 and selectedStep
292    *               is 1, then only a Continue button is rendered.
293    *
294    * @return  the new maxStep value
295    */
296   final public int getMaxStep()
297   {
298     return ComponentUtils.resolveInteger(getProperty(MAX_STEP_KEY), -1);
299   }
300 
301   /**
302    * Sets the last possible step. If this value is not known, 
303    *               it should be set to
304    *               MAX_VALUE_UNKNOWN (-1),
305    *               which is also the default value. If maxStep is
306    *               MAX_VALUE_UNKNOWN, then no text is rendered between the Back/Next
307    *               buttons. When maxStep is 2 and selectedStep
308    *               is 1, then only a Continue button is rendered.
309    * 
310    * @param maxStep  the new maxStep value
311    */
312   final public void setMaxStep(int maxStep)
313   {
314     setProperty(MAX_STEP_KEY, Integer.valueOf(maxStep));
315   }
316 
317   /**
318    * Sets the last possible step. If this value is not known, 
319    *               it should be set to
320    *               MAX_VALUE_UNKNOWN (-1),
321    *               which is also the default value. If maxStep is
322    *               MAX_VALUE_UNKNOWN, then no text is rendered between the Back/Next
323    *               buttons. When maxStep is 2 and selectedStep
324    *               is 1, then only a Continue button is rendered.
325    * 
326    * @param maxStep  the new maxStep value
327    */
328   final public void setMaxStep(long maxStep)
329   {
330     setProperty(MAX_STEP_KEY, Long.valueOf(maxStep));
331   }
332 
333   /**
334    * Gets a method reference to an action listener 
335    *              that will be called when the singleStep component navigates
336    *              to the previous step.
337    *
338    * @return  the new previousActionListener value
339    */
340   final public MethodBinding getPreviousActionListener()
341   {
342     return (MethodBinding)getProperty(PREVIOUS_ACTION_LISTENER_KEY);
343   }
344 
345   /**
346    * Sets a method reference to an action listener 
347    *              that will be called when the singleStep component navigates
348    *              to the previous step.
349    * 
350    * @param previousActionListener  the new previousActionListener value
351    */
352   final public void setPreviousActionListener(MethodBinding previousActionListener)
353   {
354     setProperty(PREVIOUS_ACTION_LISTENER_KEY, (previousActionListener));
355   }
356 
357   /**
358    * Gets a method reference to an action listener  
359    *              that will be called when the singleStep component navigates
360    *              to the next step.
361    *
362    * @return  the new nextActionListener value
363    */
364   final public MethodBinding getNextActionListener()
365   {
366     return (MethodBinding)getProperty(NEXT_ACTION_LISTENER_KEY);
367   }
368 
369   /**
370    * Sets a method reference to an action listener  
371    *              that will be called when the singleStep component navigates
372    *              to the next step.
373    * 
374    * @param nextActionListener  the new nextActionListener value
375    */
376   final public void setNextActionListener(MethodBinding nextActionListener)
377   {
378     setProperty(NEXT_ACTION_LISTENER_KEY, (nextActionListener));
379   }
380 
381   /**
382    * Gets a reference to an action method  
383    *              that will be called when the singleStep component navigates
384    *              to the next step, or the static outcome of the action.
385    *
386    * @return  the new nextAction value
387    */
388   final public MethodBinding getNextAction()
389   {
390     return (MethodBinding)getProperty(NEXT_ACTION_KEY);
391   }
392 
393   /**
394    * Sets a reference to an action method  
395    *              that will be called when the singleStep component navigates
396    *              to the next step, or the static outcome of the action.
397    * 
398    * @param nextAction  the new nextAction value
399    */
400   final public void setNextAction(MethodBinding nextAction)
401   {
402     setProperty(NEXT_ACTION_KEY, (nextAction));
403   }
404 
405   /**
406    * Gets a reference to an action method  
407    *              that will be called when the singleStep component navigates
408    *              to the previous step, or the static outcome of the action.
409    *
410    * @return  the new previousAction value
411    */
412   final public MethodBinding getPreviousAction()
413   {
414     return (MethodBinding)getProperty(PREVIOUS_ACTION_KEY);
415   }
416 
417   /**
418    * Sets a reference to an action method  
419    *              that will be called when the singleStep component navigates
420    *              to the previous step, or the static outcome of the action.
421    * 
422    * @param previousAction  the new previousAction value
423    */
424   final public void setPreviousAction(MethodBinding previousAction)
425   {
426     setProperty(PREVIOUS_ACTION_KEY, (previousAction));
427   }
428 
429   /**
430    * Adds a action listener.
431    *
432    * @param listener  the action listener to add
433    */
434   final public void addActionListener(
435     ActionListener listener)
436   {
437     addFacesListener(listener);
438   }
439 
440   /**
441    * Removes a action listener.
442    *
443    * @param listener  the action listener to remove
444    */
445   final public void removeActionListener(
446     ActionListener listener)
447   {
448     removeFacesListener(listener);
449   }
450 
451   /**
452    * Returns an array of attached action listeners.
453    *
454    * @return  an array of attached action listeners.
455    */
456   final public ActionListener[] getActionListeners()
457   {
458     return (ActionListener[])getFacesListeners(ActionListener.class);
459   }
460 
461   @Override
462   public String getFamily()
463   {
464     return COMPONENT_FAMILY;
465   }
466 
467   @Override
468   protected FacesBean.Type getBeanType()
469   {
470     return TYPE;
471   }
472 
473   /**
474    * Construct an instance of the UIXSingleStep.
475    */
476   protected UIXSingleStep(
477     String rendererType
478     )
479   {
480     super(rendererType);
481   }
482 
483   static
484   {
485     TYPE.lockAndRegister("org.apache.myfaces.trinidad.SingleStep","org.apache.myfaces.trinidad.ButtonBar");
486   }
487 }