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 */
017package org.apache.wicket.ajax;
018
019import java.util.Map;
020
021import org.apache.wicket.Component;
022import org.apache.wicket.Page;
023import org.apache.wicket.ajax.attributes.AjaxRequestAttributes;
024import org.apache.wicket.core.request.handler.IPartialPageRequestHandler;
025import org.apache.wicket.request.ILoggableRequestHandler;
026
027/**
028 *
029 * @since 6.0
030 */
031public interface AjaxRequestTarget extends IPartialPageRequestHandler, ILoggableRequestHandler
032{
033        /**
034         * An {@link AjaxRequestTarget} listener that can be used to respond to various target-related
035         * events
036         *
037         */
038        interface IListener
039        {
040                /**
041                 * Triggered before the target begins writing components.
042                 *
043                 * @param map
044                 *            modifiable map (markupId -> component) of components already added to the target
045                 * @param target
046                 *            the target itself. Could be used to add components or to append/prepend
047                 *            JavaScript
048                 *
049                 */
050                default void onBeforeRespond(Map<String, Component> map, AjaxRequestTarget target)
051                {}
052
053                /**
054                 * Triggered after the target has written components. At this point only
055                 * additional JavaScript can be added to the response.
056                 *
057                 * NOTE: During this stage of processing any calls that manipulate components will result in
058                 * an exception. After notification of all listeners no JavaScript can be added any longer.
059                 *
060                 * @param map
061                 *            read-only map:markupId-&gt;component of components already added to the target
062                 * @param target
063                 *            the target itself. Could be used to append/prepend JavaScript
064                 */
065                default void onAfterRespond(Map<String, Component> map, AjaxRequestTarget target)
066                {
067                }
068
069                /**
070                 * Triggered for every Ajax behavior. Can be used to configure common settings.
071                 * 
072                 * @param behavior
073                 *            the behavior the attributes are updated for
074                 * @param attributes
075                 *            The attributes for the Ajax behavior
076                 * @since 7.0.0
077                 */
078                default void updateAjaxAttributes(AbstractDefaultAjaxBehavior behavior, AjaxRequestAttributes attributes)
079                {}
080        }
081
082        /**
083         * Components can implement this interface to get a notification when AjaxRequestTarget begins
084         * to respond. This can be used to postpone adding components to AjaxRequestTarget until the
085         * response begins.
086         *
087         * @author Matej Knopp
088         */
089        @FunctionalInterface
090        interface ITargetRespondListener
091        {
092                /**
093                 * Invoked when AjaxRequestTarget is about to respond.
094                 *
095                 * @param target
096                 */
097                void onTargetRespond(AjaxRequestTarget target);
098        }
099
100        /**
101         * Adds a listener to this target
102         *
103         * @param listener
104         * @throws IllegalStateException
105         *             if {@link AjaxRequestTarget.IListener}'s events are currently being fired or have both been fired
106         *             already
107         */
108        void addListener(AjaxRequestTarget.IListener listener);
109
110        /**
111         * Register the given respond listener. The listener's
112         * {@link org.apache.wicket.ajax.AjaxRequestTarget.ITargetRespondListener#onTargetRespond} method will be invoked when
113         * the {@link AjaxRequestTarget} starts to respond.
114         *
115         * @param listener
116         */
117        void registerRespondListener(ITargetRespondListener listener);
118
119        /**
120         * Returns the HTML id of the last focused element.
121         *
122         * @return markup id of last focused element, <code>null</code> if none
123         */
124        String getLastFocusedElementId();
125
126        /**
127         * Returns the page. Be aware that the page can be instantiated if this wasn't the case already.
128         *
129         * @return page instance
130         */
131        @Override
132        Page getPage();
133}