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.el.MethodExpression;
25  import javax.faces.component.ActionSource;
26  import javax.faces.component.ActionSource2;
27  import javax.faces.context.FacesContext;
28  import javax.faces.el.MethodBinding;
29  import javax.faces.event.AbortProcessingException;
30  import javax.faces.event.ActionEvent;
31  import javax.faces.event.ActionListener;
32  import javax.faces.event.FacesEvent;
33  import javax.faces.event.PhaseId;
34  import org.apache.myfaces.trinidad.bean.FacesBean;
35  import org.apache.myfaces.trinidad.bean.PropertyKey;
36  import org.apache.myfaces.trinidad.context.RequestContext;
37  import org.apache.myfaces.trinidad.event.LaunchEvent;
38  import org.apache.myfaces.trinidad.event.LaunchListener;
39  import org.apache.myfaces.trinidad.event.ReturnEvent;
40  import org.apache.myfaces.trinidad.event.ReturnListener;
41  import org.apache.myfaces.trinidad.util.ComponentUtils;
42  
43  /**
44   *
45   * <h4>Events:</h4>
46   * <table border="1" width="100%" cellpadding="3" summary="">
47   * <tr bgcolor="#CCCCFF" class="TableHeadingColor">
48   * <th align="left">Type</th>
49   * <th align="left">Phases</th>
50   * <th align="left">Description</th>
51   * </tr>
52   * <tr class="TableRowColor">
53   * <td valign="top"><code>javax.faces.event.ActionEvent</code></td>
54   * <td valign="top" nowrap>Invoke<br>Application<br>Apply<br>Request<br>Values</td>
55   * <td valign="top">Event delivered when the "action" of the component has been
56  invoked;  for example, by clicking on a button.  The action may result
57  in page navigation.</td>
58   * </tr>
59   * <tr class="TableRowColor">
60   * <td valign="top"><code>org.apache.myfaces.trinidad.event.ReturnEvent</code></td>
61   * <td valign="top" nowrap>Apply<br>Request<br>Values</td>
62   * <td valign="top">Event delivered when the dialog has completed successfully.</td>
63   * </tr>
64   * <tr class="TableRowColor">
65   * <td valign="top"><code>org.apache.myfaces.trinidad.event.LaunchEvent</code></td>
66   * <td valign="top" nowrap>Invoke<br>Application<br>Apply<br>Request<br>Values</td>
67   * <td valign="top">Event delivered to prompt the command to launch a dialog.</td>
68   * </tr>
69   * <tr class="TableRowColor">
70   * <td valign="top"><code>org.apache.myfaces.trinidad.event.AttributeChangeEvent</code></td>
71   * <td valign="top" nowrap>Invoke<br>Application<br>Apply<br>Request<br>Values</td>
72   * <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>
73   * </tr>
74   * </table>
75   */
76  public class UIXCommand extends UIXComponentBase
77                          implements ActionSource2,
78                                     DialogSource,
79                                     ActionSource
80  {
81    static public final FacesBean.Type TYPE = new FacesBean.Type(
82      UIXComponentBase.TYPE);
83    static public final PropertyKey ACTION_EXPRESSION_KEY =
84      TYPE.registerKey("actionExpression", MethodExpression.class, PropertyKey.CAP_STATE_HOLDER);
85    static public final PropertyKey ACTION_LISTENER_KEY =
86      TYPE.registerKey("actionListener", MethodBinding.class, PropertyKey.CAP_NOT_BOUND | PropertyKey.CAP_STATE_HOLDER);
87    static public final PropertyKey RETURN_LISTENER_KEY =
88      TYPE.registerKey("returnListener", MethodExpression.class);
89    static public final PropertyKey LAUNCH_LISTENER_KEY =
90      TYPE.registerKey("launchListener", MethodExpression.class);
91    static public final PropertyKey IMMEDIATE_KEY =
92      TYPE.registerKey("immediate", Boolean.class, Boolean.FALSE);
93  
94    static public final String COMPONENT_FAMILY =
95      "org.apache.myfaces.trinidad.Command";
96    static public final String COMPONENT_TYPE =
97      "org.apache.myfaces.trinidad.Command";
98  
99    /**
100    * Construct an instance of the UIXCommand.
101    */
102   public UIXCommand()
103   {
104     super("org.apache.myfaces.trinidad.Button");
105   }
106   
107   @Deprecated
108   public void setLaunchListener(MethodBinding binding)
109   {
110     setLaunchListener(adaptMethodBinding(binding));
111   }
112 
113   @Deprecated
114   public void setReturnListener(MethodBinding binding)
115   {
116     setReturnListener(adaptMethodBinding(binding));
117   }
118 
119 
120   public MethodBinding getAction()
121   {
122     MethodExpression me = getActionExpression();
123     if (me == null)
124       return null;
125 
126     if (me instanceof MethodBindingMethodExpression)
127       return ((MethodBindingMethodExpression) me).getMethodBinding();
128 
129     return new MethodExpressionMethodBinding(me);
130   }
131 
132   public void setAction(MethodBinding binding)
133   {
134     if (binding instanceof MethodExpressionMethodBinding)
135       setActionExpression(((MethodExpressionMethodBinding) binding).getMethodExpression());
136     else
137       setActionExpression(new MethodBindingMethodExpression(binding));
138   }
139 
140   /**
141    * <p>Intercept <code>queueEvent</code> and mark the phaseId for the
142    * event to be <code>PhaseId.APPLY_REQUEST_VALUES</code> if the
143    * <code>immediate</code> flag is true,
144    * <code>PhaseId.INVOKE_APPLICATION</code> otherwise.</p>
145    */
146   @Override
147   public void queueEvent(FacesEvent e)
148   {
149     if (this == e.getComponent() && ((e instanceof ActionEvent) || (e instanceof ReturnEvent)))
150     {
151       if (isImmediate())
152       {
153         e.setPhaseId(PhaseId.ANY_PHASE);
154       }
155       else
156       {
157         e.setPhaseId(PhaseId.INVOKE_APPLICATION);
158       }
159     }
160 
161     super.queueEvent(e);
162   }
163 
164   @Override
165   public void broadcast(FacesEvent event) throws AbortProcessingException
166   {
167     // Perform special processing for ActionEvents:  tell
168     // the RequestContext to remember this command instance
169     // so that the NavigationHandler can locate us to queue
170     // a LaunchEvent.
171     if (event instanceof ActionEvent)
172     {
173       RequestContext afContext = RequestContext.getCurrentInstance();
174       afContext.getDialogService().setCurrentLaunchSource(this);
175 
176       try
177       {
178         // Perform standard superclass processing
179         super.broadcast(event);
180 
181         // Notify the specified action listener method (if any),
182         // and the default action listener
183         broadcastToMethodBinding(event, getActionListener());
184 
185         FacesContext context = getFacesContext();
186         ActionListener defaultActionListener =
187           context.getApplication().getActionListener();
188         if (defaultActionListener != null)
189         {
190           defaultActionListener.processAction((ActionEvent) event);
191         }
192       }
193       finally
194       {
195         afContext.getDialogService().setCurrentLaunchSource(null);
196       }
197     }
198     else
199     {
200       // Perform standard superclass processing
201       super.broadcast(event);
202 
203       if (event instanceof LaunchEvent)
204       {
205         broadcastToMethodExpression(event, getLaunchListener());
206         boolean useWindow = 
207           Boolean.TRUE.equals(getAttributes().get("useWindow"));
208 
209         ((LaunchEvent) event).launchDialog(useWindow);
210       }
211       else if (event instanceof ReturnEvent)
212       {
213         broadcastToMethodExpression(event, getReturnListener());
214         // =-=AEW: always jump to render response???  Seems the safest
215         // option, because we don't want to immediately update a model
216         // or really perform any validation.
217         getFacesContext().renderResponse();
218       }
219     }
220   }
221 
222   /**
223    * Gets a reference to an action method sent by the command component,
224    *               or the static outcome of an action. If the action starts with "dialog:",
225    *               useWindow attribute must be set to true.
226    *
227    * @return  the new actionExpression value
228    */
229   final public MethodExpression getActionExpression()
230   {
231     return (MethodExpression)getProperty(ACTION_EXPRESSION_KEY);
232   }
233 
234   /**
235    * Sets a reference to an action method sent by the command component,
236    *               or the static outcome of an action. If the action starts with "dialog:",
237    *               useWindow attribute must be set to true.
238    * 
239    * @param actionExpression  the new actionExpression value
240    */
241   final public void setActionExpression(MethodExpression actionExpression)
242   {
243     setProperty(ACTION_EXPRESSION_KEY, (actionExpression));
244   }
245 
246   /**
247    * Gets a method reference to an action listener
248    *
249    * @return  the new actionListener value
250    */
251   final public MethodBinding getActionListener()
252   {
253     return (MethodBinding)getProperty(ACTION_LISTENER_KEY);
254   }
255 
256   /**
257    * Sets a method reference to an action listener
258    * 
259    * @param actionListener  the new actionListener value
260    */
261   final public void setActionListener(MethodBinding actionListener)
262   {
263     setProperty(ACTION_LISTENER_KEY, (actionListener));
264   }
265 
266   /**
267    * Gets a method reference to a return listener.This method
268    *       is used to process dialog returnEvents which are generated as a result of either
269    *       calling org.apache.myfaces.trinidad.context.RequestContext.returnFromDialog
270    *       directly or declaratively through the use of a returnActionListener tag.
271    *
272    * @return  the new returnListener value
273    */
274   final public MethodExpression getReturnListener()
275   {
276     return (MethodExpression)getProperty(RETURN_LISTENER_KEY);
277   }
278 
279   /**
280    * Sets a method reference to a return listener.This method
281    *       is used to process dialog returnEvents which are generated as a result of either
282    *       calling org.apache.myfaces.trinidad.context.RequestContext.returnFromDialog
283    *       directly or declaratively through the use of a returnActionListener tag.
284    * 
285    * @param returnListener  the new returnListener value
286    */
287   final public void setReturnListener(MethodExpression returnListener)
288   {
289     setProperty(RETURN_LISTENER_KEY, (returnListener));
290   }
291 
292   /**
293    * Gets a method reference to a launch listener
294    *
295    * @return  the new launchListener value
296    */
297   final public MethodExpression getLaunchListener()
298   {
299     return (MethodExpression)getProperty(LAUNCH_LISTENER_KEY);
300   }
301 
302   /**
303    * Sets a method reference to a launch listener
304    * 
305    * @param launchListener  the new launchListener value
306    */
307   final public void setLaunchListener(MethodExpression launchListener)
308   {
309     setProperty(LAUNCH_LISTENER_KEY, (launchListener));
310   }
311 
312   /**
313    * Gets whether data validation - client-side or
314    *             server-side -
315    *           will be skipped when
316    *           events are generated by this component.
317    * 
318    *           When immediate is true, the command's action and
319    *           ActionListeners, including the default ActionListener
320    *           provided by the JavaServer Faces implementation,
321    *           will be executed during Apply Request Values phase
322    *           of the request processing lifecycle, rather than
323    *           waiting until the Invoke Application phase.  Because
324    *           validation runs during Process Validators (after
325    *           Apply Request Values, but before Invoke Application),
326    *           setting immediate to true will skip validation.
327    *
328    * @return  the new immediate value
329    */
330   final public boolean isImmediate()
331   {
332     return ComponentUtils.resolveBoolean(getProperty(IMMEDIATE_KEY), false);
333   }
334 
335   /**
336    * Sets whether data validation - client-side or
337    *             server-side -
338    *           will be skipped when
339    *           events are generated by this component.
340    * 
341    *           When immediate is true, the command's action and
342    *           ActionListeners, including the default ActionListener
343    *           provided by the JavaServer Faces implementation,
344    *           will be executed during Apply Request Values phase
345    *           of the request processing lifecycle, rather than
346    *           waiting until the Invoke Application phase.  Because
347    *           validation runs during Process Validators (after
348    *           Apply Request Values, but before Invoke Application),
349    *           setting immediate to true will skip validation.
350    * 
351    * @param immediate  the new immediate value
352    */
353   final public void setImmediate(boolean immediate)
354   {
355     setProperty(IMMEDIATE_KEY, immediate ? Boolean.TRUE : Boolean.FALSE);
356   }
357 
358   /**
359    * Adds a action listener.
360    *
361    * @param listener  the action listener to add
362    */
363   final public void addActionListener(
364     ActionListener listener)
365   {
366     addFacesListener(listener);
367   }
368 
369   /**
370    * Removes a action listener.
371    *
372    * @param listener  the action listener to remove
373    */
374   final public void removeActionListener(
375     ActionListener listener)
376   {
377     removeFacesListener(listener);
378   }
379 
380   /**
381    * Returns an array of attached action listeners.
382    *
383    * @return  an array of attached action listeners.
384    */
385   final public ActionListener[] getActionListeners()
386   {
387     return (ActionListener[])getFacesListeners(ActionListener.class);
388   }
389 
390   /**
391    * Adds a return listener.
392    *
393    * @param listener  the return listener to add
394    */
395   final public void addReturnListener(
396     ReturnListener listener)
397   {
398     addFacesListener(listener);
399   }
400 
401   /**
402    * Removes a return listener.
403    *
404    * @param listener  the return listener to remove
405    */
406   final public void removeReturnListener(
407     ReturnListener listener)
408   {
409     removeFacesListener(listener);
410   }
411 
412   /**
413    * Returns an array of attached return listeners.
414    *
415    * @return  an array of attached return listeners.
416    */
417   final public ReturnListener[] getReturnListeners()
418   {
419     return (ReturnListener[])getFacesListeners(ReturnListener.class);
420   }
421 
422   /**
423    * Adds a launch listener.
424    *
425    * @param listener  the launch listener to add
426    */
427   final public void addLaunchListener(
428     LaunchListener listener)
429   {
430     addFacesListener(listener);
431   }
432 
433   /**
434    * Removes a launch listener.
435    *
436    * @param listener  the launch listener to remove
437    */
438   final public void removeLaunchListener(
439     LaunchListener listener)
440   {
441     removeFacesListener(listener);
442   }
443 
444   /**
445    * Returns an array of attached launch listeners.
446    *
447    * @return  an array of attached launch listeners.
448    */
449   final public LaunchListener[] getLaunchListeners()
450   {
451     return (LaunchListener[])getFacesListeners(LaunchListener.class);
452   }
453 
454   @Override
455   public String getFamily()
456   {
457     return COMPONENT_FAMILY;
458   }
459 
460   @Override
461   protected FacesBean.Type getBeanType()
462   {
463     return TYPE;
464   }
465 
466   /**
467    * Construct an instance of the UIXCommand.
468    */
469   protected UIXCommand(
470     String rendererType
471     )
472   {
473     super(rendererType);
474   }
475 
476   static
477   {
478     TYPE.lockAndRegister("org.apache.myfaces.trinidad.Command","org.apache.myfaces.trinidad.Button");
479   }
480 }