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