001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.wicket.behavior;
018:
019: import org.apache.wicket.Component;
020: import org.apache.wicket.IClusterable;
021: import org.apache.wicket.markup.ComponentTag;
022:
023: /**
024: * Behaviors are kind of plug-ins for Components. They allow to be added to a
025: * component and get essential events forwarded by the component. they can be
026: * bound to a concrete component (using the bind method is called when the
027: * behavior is attached), but they don't need to. They can modify the components
028: * markup by changing the rendered ComponentTag. Behaviors can have their own
029: * models as well, and they are notified when these are to be detached by the
030: * component.
031: * <p>
032: * It is recommended that you extend from
033: * {@link org.apache.wicket.behavior.AbstractBehavior} instead of directly
034: * implementing this interface.
035: * </p>
036: *
037: * @see org.apache.wicket.behavior.IBehaviorListener
038: * @see org.apache.wicket.markup.html.IHeaderContributor
039: * @see org.apache.wicket.behavior.AbstractAjaxBehavior
040: * @see org.apache.wicket.AttributeModifier
041: *
042: * @author Ralf Ebert
043: * @author Eelco Hillenius
044: * @author Igor Vaynberg (ivaynberg)
045: */
046: public interface IBehavior extends IClusterable {
047: /**
048: * Called when a component is about to render.
049: *
050: * @param component
051: * the component that has this behavior coupled
052: */
053: void beforeRender(Component component);
054:
055: /**
056: * Called when a component that has this behavior coupled was rendered.
057: *
058: * @param component
059: * the component that has this behavior coupled
060: */
061: void afterRender(Component component);
062:
063: /**
064: * Bind this handler to the given component. This method is called by the
065: * host component immediately after this behavior is added to it. This
066: * method is useful if you need to do initialization based on the component
067: * it is attached and you can't wait to do it at render time. Keep in mind
068: * that if you decide to keep a reference to the host component, it is not
069: * thread safe anymore, and should thus only be used in situations where you
070: * do not reuse the behavior for multiple components.
071: *
072: * @param component
073: * the component to bind to
074: */
075: void bind(Component component);
076:
077: /**
078: * Allows the behavior to detach any state it has attached during request
079: * processing.
080: *
081: * @param component
082: * the component that initiates the detachement of this behavior
083: */
084: void detach(Component component);
085:
086: /**
087: * In case an unexpected exception happened anywhere between
088: * onComponentTag() and rendered(), onException() will be called for any
089: * behavior. Typically, if you clean up resources in
090: * {@link #afterRender(Component)}, you should do the same in the
091: * implementation of this method.
092: *
093: * @param component
094: * the component that has a reference to this behavior and during
095: * which processing the exception occured
096: * @param exception
097: * the unexpected exception
098: */
099: void exception(Component component, RuntimeException exception);
100:
101: /**
102: * This method returns false if the behaviour generates a callback url (for
103: * example ajax behaviours)
104: *
105: * @param component
106: * the component that has this behavior coupled.
107: *
108: * @return boolean true or false.
109: */
110: boolean getStatelessHint(Component component);
111:
112: /**
113: * Called when a components is rendering and wants to render this behavior.
114: * If false is returned this behavior will be ignored.
115: *
116: * @param component
117: * the component that has this behavior coupled
118: *
119: * @return true if this behaviour must be executed/rendered
120: */
121: boolean isEnabled(Component component);
122:
123: /**
124: * Called any time a component that has this behavior registered is
125: * rendering the component tag.
126: *
127: * @param component
128: * the component that renders this tag currently
129: * @param tag
130: * the tag that is rendered
131: */
132: void onComponentTag(Component component, ComponentTag tag);
133:
134: /**
135: * Specifies whether or not this behavior is temporary. Temporary behaviors
136: * are removed at the end of request. Such behaviors are useful for
137: * modifying component rendering only when it renders next. Usecases include
138: * javascript effects, initial clientside dom setup, etc.
139: *
140: * @return true if this behavior is temporary
141: */
142: boolean isTemporary();
143: }
|