001// Copyright 2004, 2005 The Apache Software Foundation 002// 003// Licensed under the Apache License, Version 2.0 (the "License"); 004// you may not use this file except in compliance with the License. 005// You may obtain a copy of the License at 006// 007// http://www.apache.org/licenses/LICENSE-2.0 008// 009// Unless required by applicable law or agreed to in writing, software 010// distributed under the License is distributed on an "AS IS" BASIS, 011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 012// See the License for the specific language governing permissions and 013// limitations under the License. 014 015package org.apache.tapestry.engine; 016 017import java.io.IOException; 018 019import org.apache.tapestry.IRequestCycle; 020 021/** 022 * A service, provided by the {@link org.apache.tapestry.IEngine}, for its pages and/or components. 023 * Services are responsible for constructing {@link EngineServiceLink}s (an encoding of URLs) to 024 * represent dynamic application behavior, and for parsing those URLs when a subsequent request 025 * involves them. 026 * 027 * @author Howard Lewis Ship 028 */ 029 030public interface IEngineService 031{ 032 /** 033 * Builds a URL for a service. This is performed during the rendering phase of one request cycle 034 * and bulds URLs that will invoke activity in a subsequent request cycle. 035 * <p> 036 * <b>This method changed incompatibly between release 3.0 and release 4.0. </b> 037 * </p> 038 * @param post 039 * if true, then the link will be used for a post (not a get, i.e., for a HTML form); 040 * this may affect what information is encoded into the link 041 * @param parameter 042 * An object that provide any additional information needed by the service. Each 043 * service implementation will expect that an object of the proper type be passed in. 044 * In some cases, a simple String will do; in others, a specific object (possibly 045 * implementing an interface) will be required. 046 * 047 * @return The URL for the service. The URL will have to be encoded via 048 * {@link javax.servlet.http.HttpServletResponse#encodeURL(java.lang.String)}. 049 */ 050 051 public ILink getLink(boolean post, Object parameter); 052 053 /** 054 * Perform the service, interpreting the URL (from the 055 * {@link javax.servlet.http.HttpServletRequest}) responding appropriately, and rendering a 056 * result page. 057 * 058 * @param cycle 059 * the incoming request 060 * @see org.apache.tapestry.IEngine#service(org.apache.tapestry.request.RequestContext) 061 */ 062 063 public void service(IRequestCycle cycle) throws IOException; 064 065 /** 066 * Returns the name of the service. 067 * 068 * @since 1.0.1 069 */ 070 071 public String getName(); 072}