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 primarily used by
026     * {@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         * 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    }