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