001: /*
002: * $Id: IBehavior.java 508111 2007-02-15 19:50:42Z ivaynberg $ $Revision:
003: * 1.5 $ $Date: 2007-02-15 20:50:42 +0100 (Thu, 15 Feb 2007) $
004: *
005: * ==============================================================================
006: * Licensed under the Apache License, Version 2.0 (the "License"); you may not
007: * use this file except in compliance with the License. You may obtain a copy of
008: * the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing, software
013: * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
014: * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
015: * License for the specific language governing permissions and limitations under
016: * the License.
017: */
018: package wicket.behavior;
019:
020: import java.io.Serializable;
021:
022: import wicket.Component;
023: import wicket.markup.ComponentTag;
024:
025: /**
026: * Behaviors are kind of plug-ins for Components. They allow to be added to a
027: * component and get essential events forwarded by the component. they can be
028: * bound to a concrete component (using the bind method is called when the
029: * behavior is attached), but they don't need to. They can modify the components
030: * markup by changing the rendered ComponentTag. Behaviors can have their own
031: * models as well, and they are notified when these are to be detached by the
032: * component.
033: * <p>
034: * It is recommended that you extend from
035: * {@link wicket.behavior.AbstractBehavior} instead of directly implementing
036: * this interface.
037: * </p>
038: *
039: * @see wicket.behavior.IBehaviorListener
040: * @see wicket.markup.html.IHeaderContributor
041: * @see wicket.behavior.AbstractAjaxBehavior
042: * @see wicket.AttributeModifier
043: *
044: * @author Ralf Ebert
045: * @author Eelco Hillenius
046: */
047: public interface IBehavior extends Serializable {
048: /**
049: * Bind this handler to the given component. This method is called by the
050: * host component immediately after this behavior is added to it. This
051: * method is useful if you need to do initialization based on the component
052: * it is attached can you can't wait to do it at render time. Keep in mind
053: * that if you decide to keep a reference to the host component, it is not
054: * thread safe anymore, and should thus only be used in situations where you
055: * do not reuse the behavior for multiple components.
056: *
057: * @param component
058: * the component to bind to
059: */
060: void bind(Component component);
061:
062: /**
063: * Provides for the ability to detach any models this behavior has. This
064: * method is called by the components which have this behavior attached to
065: * them when they are detaching their models themselves (ie after
066: * rendering). Note that if you share a behavior between components, this
067: * method is called multiple times.
068: *
069: * YOU MUST CALL SUPER WHEN IMPLEMENTING THIS METHOD
070: *
071: * @param component
072: * the component that initiates the detachement of this behavior
073: */
074: void detachModel(Component component);
075:
076: /**
077: * Called any time a component that has this behavior registered is
078: * rendering the component tag.
079: *
080: * @param component
081: * the component that renders this tag currently
082: * @param tag
083: * the tag that is rendered
084: */
085: void onComponentTag(Component component, ComponentTag tag);
086:
087: /**
088: * Called when a component that has this behavior coupled was rendered.
089: *
090: * @param component
091: * the component that has this behavior coupled
092: */
093: void rendered(Component component);
094:
095: /**
096: * In case an unexpected exception happened anywhere between
097: * onComponentTag() and rendered(), onException() will be called for any
098: * behavior. Typically, if you clean up resources in
099: * {@link #rendered(Component)}, you should do the same in the
100: * implementation of this method.
101: *
102: * @param component
103: * the component that has a reference to this behavior and during
104: * which processing the exception occured
105: * @param exception
106: * the unexpected exception
107: */
108: void exception(Component component, RuntimeException exception);
109: }
|