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.linktransform; 014 015import org.apache.tapestry5.Link; 016import org.apache.tapestry5.internal.services.PageRenderDispatcher; 017import org.apache.tapestry5.ioc.annotations.UsesOrderedConfiguration; 018import org.apache.tapestry5.services.ComponentEventLinkEncoder; 019import org.apache.tapestry5.services.LocalizationSetter; 020import org.apache.tapestry5.services.PageRenderRequestParameters; 021import org.apache.tapestry5.services.Request; 022 023/** 024 * Allows the default {@link Link} for a page render request to be replaced. 025 * This is a service, but also the contribution to the service, as a chain of command. 026 * 027 * A contributed implementation of this interface is expected to identify which requests it wants to transform. The 028 * {@link #transformPageRenderLink(Link, PageRenderRequestParameters)} method can return a {@link Link} that is allowed 029 * to differ from Tapestry normal default. Later, when that request is triggered, 030 * {@link #decodePageRenderRequest(Request)} is required to reverse the operation, identifying the original parameters 031 * so that request handling can continue. 032 * 033 * @since 5.2.0 034 */ 035@UsesOrderedConfiguration(PageRenderLinkTransformer.class) 036public interface PageRenderLinkTransformer 037{ 038 /** 039 * Transforms a page render link. 040 * 041 * @param defaultLink 042 * default Link for this request 043 * @param parameters 044 * that define the request 045 * @return replacement Link, or null 046 */ 047 Link transformPageRenderLink(Link defaultLink, PageRenderRequestParameters parameters); 048 049 /** 050 * Attempts to decode the page render request, to perform the opposite action for 051 * {@link #transformPageRenderLink(Link, PageRenderRequestParameters)}. The transformer 052 * is also responsible for identifying the locale in the request (as part of the path, or as a 053 * query parameter or cookie) and setting the locale for the request. 054 * 055 * This method will be invoked from the {@link PageRenderDispatcher} and a non-null value returned from this method 056 * will prevent the default {@link ComponentEventLinkEncoder#decodePageRenderRequest(Request)} method from being 057 * invoked. 058 * 059 * @return decoded parameters, or null to proceed normally 060 * @see LocalizationSetter#setLocaleFromLocaleName(String) 061 */ 062 PageRenderRequestParameters decodePageRenderRequest(Request request); 063}