001: /*
002: * $Id: IRequestCycleProcessor.java 459238 2006-02-12 22:57:36Z ehillenius $
003: * $Revision: 459238 $ $Date: 2006-02-12 23:57:36 +0100 (Sun, 12 Feb 2006) $
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.request;
019:
020: import wicket.IRequestTarget;
021: import wicket.RequestCycle;
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 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 uncaught
045: * exception occurs during the event handling or response phase so that an
046: * appropriate exception response can be generated. This method is guaranteed to
047: * be called whenever such an exception happens, but will never be called
048: * otherwise. </li>
049: * </ul>
050: * </p>
051: * <p>
052: * A convience implementation that makes breaking up this processor in smaller
053: * delegate strategies easier can be found as
054: * {@link wicket.request.compound.CompoundRequestCycleProcessor} (or
055: * {@link wicket.request.compound.AbstractCompoundRequestCycleProcessor}).
056: * </p>
057: *
058: * @author hillenius
059: */
060: public interface IRequestCycleProcessor {
061: /**
062: * Gets the object that is responsible for encoding request targets (like
063: * url's in links etc) and decoding urls and request parameters etc into
064: * {@link wicket.request.RequestParameters} objects.
065: *
066: * @return the request encoder
067: */
068: IRequestCodingStrategy getRequestCodingStrategy();
069:
070: /**
071: * <p>
072: * Resolves the request and returns the request target. Typically, the
073: * resolver uses the {@link wicket.request.RequestParameters} object that is
074: * passed in.
075: * </p>
076: * <p>
077: * Implementors of this method should be careful not to mix this code with
078: * event handling code; method {@link #processEvents(RequestCycle)} is meant
079: * for that purpose.
080: * </p>
081: *
082: * @param requestCycle
083: * the current request cycle
084: * @param requestParameters
085: * The request parameters object as decoded by this processor's
086: * {@link IRequestCodingStrategy}.
087: * @return the request target; has to be non-null!
088: */
089: IRequestTarget resolve(RequestCycle requestCycle,
090: RequestParameters requestParameters);
091:
092: /**
093: * After a page is restored, this method is responsible for calling any
094: * event handling code based on the request. For example, when a link is
095: * clicked, {@link #resolve(RequestCycle, RequestParameters)} should return
096: * the page that that link resides on, and this method should call the
097: * {@link wicket.markup.html.link.ILinkListener} interface on that
098: * component.
099: *
100: * @param requestCycle
101: * the current request cycle
102: */
103: void processEvents(RequestCycle requestCycle);
104:
105: /**
106: * After the target is resolved and the request events are handled, it is
107: * time to respond to the request. This method is responsible for executing
108: * the proper response sequence given the current request target and
109: * response.
110: *
111: * @param requestCycle
112: * the current request cycle
113: */
114: void respond(RequestCycle requestCycle);
115:
116: /**
117: * Whenever a unhandled exception is encountered during the processing of a
118: * request cycle, this method is called to respond to the request in a
119: * proper way.
120: *
121: * @param e
122: * any unhandled exception
123: * @param requestCycle
124: * the current request cycle
125: */
126: void respond(RuntimeException e, RequestCycle requestCycle);
127: }
|