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