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    
015    package org.apache.tapestry.record;
016    
017    import java.util.Collection;
018    
019    import org.apache.tapestry.engine.ServiceEncoding;
020    
021    /**
022     * Defines how a persistent property is made persistent. The typical
023     * implementation is to store the persistent property into the session as a
024     * session attribute.
025     * 
026     * @author Howard M. Lewis Ship
027     * @since 4.0
028     */
029    public interface PropertyPersistenceStrategy
030    {
031    
032        /**
033         * Stores the new value.
034         * 
035         * @param pageName
036         *            the name of the page containing the property
037         * @param idPath
038         *            the path to the component with the property (may be null)
039         * @param propertyName
040         *            the name of the property to be persisted
041         * @param newValue
042         *            the new value (which may be null)
043         */
044    
045        void store(String pageName, String idPath, String propertyName,
046                Object newValue);
047    
048        /**
049         * Returns a collection of {@link org.apache.tapestry.record.PropertyChange}s.
050         * These represent prior changes previously stored. The order is not
051         * significant. Must not return null. Does not have to reflect changes made
052         * during the current request (this method is typically invoked as part of
053         * rolling back a page to a prior state, before any further changes are
054         * possible).
055         */
056    
057        Collection getStoredChanges(String pageName);
058    
059        /**
060         * Invoked to discard any stored changes for the specified page.
061         */
062        void discardStoredChanges(String pageName);
063    
064        /**
065         * Invoked by a {@link org.apache.tapestry.services.LinkFactory} , the
066         * parameters may be modified (added to) to store information related to
067         * persistent properties. This method is forwarded to all
068         * {@link PropertyPersistenceStrategy}s.
069         * 
070         * @param encoding
071         *            Service encoding, which indentifies the URL and the query
072         *            parameters from which the
073         *            {@link org.apache.tapestry.engine.ILink} will be
074         *            created.
075         * @param post
076         *            if true, then the link will be used for a post (not a get,
077         *            i.e., for a HTML form); this may affect what information is
078         *            encoded into the link
079         * @see PropertyPersistenceStrategySource
080         */
081    
082        void addParametersForPersistentProperties(ServiceEncoding encoding,
083                boolean post);
084    }