001// Licensed under the Apache License, Version 2.0 (the "License");
002// you may not use this file except in compliance with the License.
003// You may obtain a copy of the License at
004//
005//     http://www.apache.org/licenses/LICENSE-2.0
006//
007// Unless required by applicable law or agreed to in writing, software
008// distributed under the License is distributed on an "AS IS" BASIS,
009// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
010// See the License for the specific language governing permissions and
011// limitations under the License.
012
013package org.apache.tapestry5.services;
014
015import org.apache.tapestry5.ioc.annotations.UsesMappedConfiguration;
016
017import java.io.IOException;
018
019/**
020 * Responsible for handling the return value provided by a component event handler method.
021 *
022 * There are two services built into Tapestry that implement this interface: ComponentEventResultProcessor (used for
023 * ordinary page-oriented requests, and distinguished by the @{@link org.apache.tapestry5.services.Traditional}
024 * and/or @{@link org.apache.tapestry5.ioc.annotations.Primary} marker annotations) and
025 * AjaxComponentEventResultProcessor, used
026 * for Ajax requests (which typically return a partially rendered page), distinguished by the @{@link
027 * org.apache.tapestry5.services.Ajax} marker annotation.
028 *
029 * @param <T> the type of the values being handled
030 */
031@UsesMappedConfiguration(key = Class.class, value = ComponentEventResultProcessor.class)
032public interface ComponentEventResultProcessor<T>
033{
034    /**
035     * For a given, non-null return value from a component event method, construct and send a response.
036     *
037     * Starting in release 5.4, it is recommended that for any response that involves Tapestry pages or components,
038     * the implementation should create an {@link org.apache.tapestry5.ioc.IOOperation} to do the rendering, and
039     * add the operation to the {@link org.apache.tapestry5.http.services.Request} as attribute
040     * {@link org.apache.tapestry5.TapestryConstants#RESPONSE_RENDERER}.
041     * This avoids a number of issues related to the {@link org.apache.tapestry5.services.Environment}.
042     *
043     * @param value
044     *         the value returned from a method
045     * @throws RuntimeException
046     *         if the value can not handled
047     */
048    void processResultValue(T value) throws IOException;
049}