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