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.request;
018:
019: import org.apache.wicket.IRequestTarget;
020: import org.apache.wicket.RequestCycle;
021: import org.apache.wicket.protocol.http.WebRequestCycleProcessor;
022:
023: /**
024: * <p>
025: * The request cycle processor is responsible for handling the steps of a
026: * request cycle. It's methods are called in a pre-defined order:
027: * <ul>
028: * <li> {@link #resolve(RequestCycle, RequestParameters)} is called to get the
029: * request target. A request might refer to e.g. a bookmarkable page, a listener
030: * interface call on a component on a previously rendered page, a shared
031: * resource or e.g. a non-wicket resource that resides in the web application
032: * folder. </li>
033: * <li> {@link #processEvents(RequestCycle)} is called after the target is
034: * resolved. It is meant to handle/ distribute events like e.g. listener
035: * interface calls on components. During this processing, the request target may
036: * be changed (e.g. by calling setResponsePage). What actually happens is that
037: * {@link org.apache.wicket.RequestCycle} holds a stack of targets, of which it will take
038: * to last addition as the recent one, but walks the whole stack in order to do
039: * cleaning up after the request is handled.</li>
040: * <li> {@link #respond(RequestCycle)} is called to create a response to the
041: * requesting client. Typically, the actual response handling is to be (or
042: * delegated) by the request target implementation, but different strategies
043: * might do as they seem fit. </li>
044: * <li> {@link #respond(RuntimeException, RequestCycle)} is called whenever an
045: * uncaught exception occurs during the event handling or response phase so that
046: * an appropriate exception response can be generated. This method is guaranteed
047: * to be called whenever such an exception happens, but will never be called
048: * otherwise. </li>
049: * </ul>
050: * </p>
051: *
052: * @see AbstractRequestCycleProcessor
053: * @see WebRequestCycleProcessor
054: *
055: * @author hillenius
056: */
057: public interface IRequestCycleProcessor {
058: /**
059: * Gets the object that is responsible for encoding request targets (like
060: * url's in links etc) and decoding urls and request parameters etc into
061: * {@link org.apache.wicket.request.RequestParameters} objects.
062: *
063: * @return the request encoder
064: */
065: IRequestCodingStrategy getRequestCodingStrategy();
066:
067: /**
068: * <p>
069: * Resolves the request and returns the request target. Typically, the
070: * resolver uses the {@link org.apache.wicket.request.RequestParameters} object that is
071: * passed in.
072: * </p>
073: * <p>
074: * Implementors of this method should be careful not to mix this code with
075: * event handling code; method {@link #processEvents(RequestCycle)} is meant
076: * for that purpose.
077: * </p>
078: *
079: * @param requestCycle
080: * the current request cycle
081: * @param requestParameters
082: * The request parameters object as decoded by this processor's
083: * {@link IRequestCodingStrategy}.
084: * @return the request target; has to be non-null!
085: */
086: IRequestTarget resolve(RequestCycle requestCycle,
087: RequestParameters requestParameters);
088:
089: /**
090: * After a page is restored, this method is responsible for calling any
091: * event handling code based on the request. For example, when a link is
092: * clicked, {@link #resolve(RequestCycle, RequestParameters)} should return
093: * the page that that link resides on, and this method should call the
094: * {@link org.apache.wicket.markup.html.link.ILinkListener} interface on that
095: * component.
096: *
097: * @param requestCycle
098: * the current request cycle
099: */
100: void processEvents(RequestCycle requestCycle);
101:
102: /**
103: * After the target is resolved and the request events are handled, it is
104: * time to respond to the request. This method is responsible for executing
105: * the proper response sequence given the current request target and
106: * response.
107: *
108: * @param requestCycle
109: * the current request cycle
110: */
111: void respond(RequestCycle requestCycle);
112:
113: /**
114: * Whenever a unhandled exception is encountered during the processing of a
115: * request cycle, this method is called to respond to the request in a
116: * proper way.
117: *
118: * @param e
119: * any unhandled exception
120: * @param requestCycle
121: * the current request cycle
122: */
123: void respond(RuntimeException e, RequestCycle requestCycle);
124: }
|