001// Copyright 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.form;
016
017import org.apache.tapestry.FormBehavior;
018import org.apache.tapestry.IRender;
019import org.apache.tapestry.engine.ILink;
020
021/**
022 * Interface for a utility object that encapsulates the majority of the
023 * {@link org.apache.tapestry.form.Form}'s behavior.
024 * 
025 * @author Howard M. Lewis Ship
026 * @since 4.0
027 */
028public interface FormSupport extends FormBehavior
029{
030
031    /**
032     * Invoked when the form is rendering. This should only be invoked by the {@link Form}
033     * component.
034     * 
035     * @param method
036     *            the HTTP method ("get" or "post")
037     * @param informalParametersRenderer
038     *            object that will render informal parameters
039     * @param link
040     *            The link to which the form will submit (encapsulating the URL and the query
041     *            parameters)
042     * @param scheme
043     *            the desired scheme for the generated URL, typically "http" or "https". If
044     *            non-null, and the scheme does not match the current request's scheme, then an
045     *            absolute URL with the specified scheme will be generated, rather than a URI.
046     * @param port
047     *            the desired port for the generated URL, typically "80", "443". If
048     *            non-null, and the port does not match the current request's port, then an
049     *            absolute URL with the specified port will be generated, rather than a URI.
050     */
051    public void render(String method, IRender informalParametersRenderer, ILink link, String scheme, Integer port);
052
053    /**
054     * Old interface left around for backwards compatibility.  Please use the second render method.
055     * 
056     * @param method
057     *            the HTTP method ("get" or "post")
058     * @param informalParametersRenderer
059     *            object that will render informal parameters
060     * @param link
061     *            The link to which the form will submit (encapsulating the URL and the query
062     *            parameters)
063     * @param scheme
064     *            the desired scheme for the generated URL, typically "http" or "https". If
065     *            non-null, and the scheme does not match the current request's scheme, then an
066     *            absolute URL with the specified scheme will be generated, rather than a URI.
067     * @deprecated To be removed in 4.1, see new render method that adds the Port parameter.
068     */
069    public void render(String method, IRender informalParametersRenderer, ILink link, String scheme);
070
071    /**
072     * Invoked to rewind the form, which renders the body of the form, allowing form element
073     * components to pull data from the request and update page properties. This should only be
074     * invoked by the {@link Form} component.
075     * 
076     * @return a code indicating why the form was submitted: {@link FormConstants#SUBMIT_NORMAL},
077     *         {@link FormConstants#SUBMIT_CANCEL} or {@link FormConstants#SUBMIT_REFRESH}.
078     */
079    public String rewind();
080}