1 /*
2 * $Id: FacesEvent.java,v 1.14 2007/04/27 22:00:08 ofung Exp $
3 */
4
5 /*
6 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
7 *
8 * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
9 *
10 * The contents of this file are subject to the terms of either the GNU
11 * General Public License Version 2 only ("GPL") or the Common Development
12 * and Distribution License("CDDL") (collectively, the "License"). You
13 * may not use this file except in compliance with the License. You can obtain
14 * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
15 * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
16 * language governing permissions and limitations under the License.
17 *
18 * When distributing the software, include this License Header Notice in each
19 * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
20 * Sun designates this particular file as subject to the "Classpath" exception
21 * as provided by Sun in the GPL Version 2 section of the License file that
22 * accompanied this code. If applicable, add the following below the License
23 * Header, with the fields enclosed by brackets [] replaced by your own
24 * identifying information: "Portions Copyrighted [year]
25 * [name of copyright owner]"
26 *
27 * Contributor(s):
28 *
29 * If you wish your version of this file to be governed by only the CDDL or
30 * only the GPL Version 2, indicate your decision by adding "[Contributor]
31 * elects to include this software in this distribution under the [CDDL or GPL
32 * Version 2] license." If you don't indicate a single choice of license, a
33 * recipient has the option to distribute your version of this file under
34 * either the CDDL, the GPL Version 2 or to extend the choice of license to
35 * its licensees as provided above. However, if you add GPL Version 2 code
36 * and therefore, elected the GPL Version 2 license, then the option applies
37 * only if the new code is made subject to such option by the copyright
38 * holder.
39 */
40
41 package javax.faces.event;
42
43
44 import java.util.EventObject;
45 import javax.faces.component.UIComponent;
46 import javax.faces.component.UIViewRoot;
47
48
49 /**
50 * <p><strong>FacesEvent</strong> is the base class for user interface and
51 * application events that can be fired by {@link UIComponent}s. Concrete
52 * event classes must subclass {@link FacesEvent} in order to be supported
53 * by the request processing lifecycle.</p>
54 */
55
56 public abstract class FacesEvent extends EventObject {
57
58
59 // ------------------------------------------------------------ Constructors
60
61
62 /**
63 * <p>Construct a new event object from the specified source component.</p>
64 *
65 * @param component Source {@link UIComponent} for this event
66 *
67 * @throws IllegalArgumentException if <code>component</code> is
68 * <code>null</code>
69 */
70 public FacesEvent(UIComponent component) {
71
72 super(component);
73
74 }
75
76
77 // -------------------------------------------------------------- Properties
78
79
80 /**
81 * <p>Return the source {@link UIComponent} that sent this event.
82 */
83 public UIComponent getComponent() {
84
85 return ((UIComponent) getSource());
86
87 }
88
89 private PhaseId phaseId = PhaseId.ANY_PHASE;
90
91 /**
92 * <p>Return the identifier of the request processing phase during
93 * which this event should be delivered. Legal values are the
94 * singleton instances defined by the {@link PhaseId} class,
95 * including <code>PhaseId.ANY_PHASE</code>, which is the default
96 * value.</p>
97 */
98 public PhaseId getPhaseId() {
99 return phaseId;
100 }
101
102 /**
103 * <p>Set the {@link PhaseId} during which this event will be
104 * delivered.</p>
105 *
106 * @throws IllegalArgumentException phaseId is null.
107 *
108 */
109
110 public void setPhaseId(PhaseId phaseId) {
111 if (null == phaseId) {
112 throw new IllegalArgumentException();
113 }
114 this.phaseId = phaseId;
115 }
116
117
118 // ------------------------------------------------- Event Broadcast Methods
119
120
121 /**
122 * <p>Convenience method to queue this event for broadcast at the end
123 * of the current request processing lifecycle phase.</p>
124 *
125 * @throws IllegalStateException if the source component for this
126 * event is not a descendant of a {@link UIViewRoot}
127 */
128 public void queue() {
129
130 getComponent().queueEvent(this);
131
132 }
133
134
135 /**
136 * <p>Return <code>true</code> if this {@link FacesListener} is an instance
137 * of a listener class that this event supports. Typically, this will be
138 * accomplished by an "instanceof" check on the listener class.</p>
139 *
140 * @param listener {@link FacesListener} to evaluate
141 */
142 public abstract boolean isAppropriateListener(FacesListener listener);
143
144
145 /**
146 * <p>Broadcast this {@link FacesEvent} to the specified
147 * {@link FacesListener}, by whatever mechanism is appropriate. Typically,
148 * this will be accomplished by calling an event processing method, and
149 * passing this {@link FacesEvent} as a paramter.</p>
150 *
151 * @param listener {@link FacesListener} to send this {@link FacesEvent} to
152 *
153 * @throws AbortProcessingException Signal the JavaServer Faces
154 * implementation that no further processing on the current event
155 * should be performed
156 */
157 public abstract void processListener(FacesListener listener);
158
159
160 }