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 ajax request target begins its response cycle
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 ajax request target is done with its response cycle. At this point only
055                 * additional javascript can be output to the response using the provided
056                 * {@link AjaxRequestTarget.IJavaScriptResponse} object
057                 *
058                 * NOTE: During this stage of processing any calls to target that manipulate the response
059                 * (adding components, javascript) will have no effect
060                 *
061                 * @param map
062                 *            read-only map:markupId-&gt;component of components already added to the target
063                 * @param response
064                 *            response object that can be used to output javascript
065                 */
066                default void onAfterRespond(Map<String, Component> map, AjaxRequestTarget.IJavaScriptResponse response)
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         * An ajax javascript response that allows users to add javascript to be executed on the client
084         * side
085         *
086         * @author ivaynberg
087         */
088        @FunctionalInterface
089        interface IJavaScriptResponse
090        {
091                /**
092                 * Adds more javascript to the ajax response that will be executed on the client side
093                 *
094                 * @param script
095                 *            javascript
096                 */
097                void addJavaScript(String script);
098        }
099
100        /**
101         * Components can implement this interface to get a notification when AjaxRequestTarget begins
102         * to respond. This can be used to postpone adding components to AjaxRequestTarget until the
103         * response begins.
104         *
105         * @author Matej Knopp
106         */
107        @FunctionalInterface
108        interface ITargetRespondListener
109        {
110                /**
111                 * Invoked when AjaxRequestTarget is about the respond.
112                 *
113                 * @param target
114                 */
115                void onTargetRespond(AjaxRequestTarget target);
116        }
117
118        /**
119         * Adds a listener to this target
120         *
121         * @param listener
122         * @throws IllegalStateException
123         *             if {@link AjaxRequestTarget.IListener}'s events are currently being fired or have both been fired
124         *             already
125         */
126        void addListener(AjaxRequestTarget.IListener listener);
127
128        /**
129         * Register the given respond listener. The listener's
130         * {@link org.apache.wicket.ajax.AjaxRequestTarget.ITargetRespondListener#onTargetRespond} method will be invoked when
131         * the {@link AjaxRequestTarget} starts to respond.
132         *
133         * @param listener
134         */
135        void registerRespondListener(ITargetRespondListener listener);
136
137        /**
138         * Returns the HTML id of the last focused element.
139         *
140         * @return markup id of last focused element, <code>null</code> if none
141         */
142        String getLastFocusedElementId();
143
144        /**
145         * Returns the page. Be aware that the page can be instantiated if this wasn't the case already.
146         *
147         * @return page instance
148         */
149        @Override
150        Page getPage();
151}