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.services;
016
017import java.util.Map;
018
019import org.apache.tapestry.IRequestCycle;
020import org.apache.tapestry.engine.IEngineService;
021import org.apache.tapestry.engine.ILink;
022import org.apache.tapestry.engine.ServiceEncoder;
023
024/**
025 * A source of {@link org.apache.tapestry.engine.ILink}instances. This is primarily used by
026 * {@link org.apache.tapestry.engine.IEngineService}s.
027 * 
028 * @author Howard M. Lewis Ship
029 * @since 4.0
030 */
031public interface LinkFactory
032{
033    /**
034     * Constructs an {@link org.apache.tapestry.engine.ILink}.
035     * 
036     * @param service
037     *            the service for which the link is being generated
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 parameters
042     *            A map; keys are strings and values are strings or string arrays (exception: key
043     *            {@link ServiceConstants#PARAMETER} is an array of objects. Certain keys, defined
044     *            in {@link ServiceConstants} may have special meaning. The map will typically be
045     *            modified internally. May not be null.
046     * @param stateful
047     *            If true, then the final URL should be encoded (with the session id) if necessary.
048     *            If false, the session encoding should not occur. The latter case is useful for
049     *            services that will absolutely not need any access to user-specific state.
050     */
051    public ILink constructLink(IEngineService service, boolean post, Map parameters,
052            boolean stateful);
053
054    /**
055     * A secondary function of the service is to convert encoded (aka "squeezed") listener
056     * parameters back into an array of Objects. This does (barely) makes sense .. the link factory
057     * is responsible for encoding the listener parameters, it should be responsible for decoding
058     * them.
059     * 
060     * @param cycle
061     *            the current request cycle
062     * @return an array of Object[]. May return an empty array, but won't return null.
063     */
064
065    public Object[] extractListenerParameters(IRequestCycle cycle);
066
067    /**
068     * Returns an array of {@link org.apache.tapestry.engine.ServiceEncoder}, ordering into
069     * execution order. May return an empty array, but won't return null.
070     */
071
072    public ServiceEncoder[] getServiceEncoders();
073}