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
015package org.apache.tapestry.engine;
016
017import org.apache.tapestry.IPage;
018import org.apache.tapestry.event.ChangeObserver;
019
020/**
021 * Defines an object that can observe changes to properties of a page and its components, store the
022 * state of the page between request cycles, and restore a page's state on a subsequent request
023 * cycle.
024 * <p>
025 * Concrete implementations of this can store the changes in memory, as client-side cookies, in a
026 * flat file, or in a database.
027 * 
028 * @author Howard Lewis Ship
029 */
030
031public interface IPageRecorder extends ChangeObserver
032{
033    /**
034     * Persists all changes that have been accumulated. If the recorder saves change incrementally,
035     * this should ensure that all changes have been persisted.
036     * <p>
037     * After commiting, a page recorder automatically locks itself.
038     */
039
040    public void commit();
041
042    /**
043     * Rolls back the page to the currently persisted state.
044     * <p>
045     * A page recorder can only rollback changes to properties which have changed at some point.
046     * This can cause some minor problems, addressed by
047     * {@link org.apache.tapestry.event.PageDetachListener#pageDetached(org.apache.tapestry.event.PageEvent)}.
048     */
049
050    public void rollback(IPage page);
051}