    001    // Copyright 2006, 2007, 2008 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.tapestry5.internal.services;
    016
    017    import org.apache.tapestry5.ComponentResources;
    018    import org.apache.tapestry5.ioc.annotations.UsesMappedConfiguration;
    019    import org.apache.tapestry5.services.PersistentFieldBundle;
    020    import org.apache.tapestry5.services.PersistentFieldStrategy;
    021
    022    /**
    023     * Handle persistent property changes. Primarily, delegates to a number of {@link org.apache.tapestry5.services.PersistentFieldStrategy}
    024     * instances.
    025     */
    026    @UsesMappedConfiguration(PersistentFieldStrategy.class)
    027    public interface PersistentFieldManager
    028    {
    029        /**
    030         * Posts a change of a persistent property.
    031         *
    032         * @param pageName  the logical name of the page containing the component
    033         * @param resources the resources for the component or mixin (used to determine the persistence strategy)
    034         * @param fieldName the name of the field whose persistent value has changed
    035         * @param newValue  the new value for the field, possibly null
    036         */
    037        void postChange(String pageName, ComponentResources resources, String fieldName, Object newValue);
    038
    039        /**
    040         * Locates all persistently stored changes to all properties within the page (for the current session and request)
    041         * and gathers them together into a bundle.
    042         *
    043         * @param pageName the logical name of the page to gather changes for
    044         * @return a bundle identifying all such changes
    045         */
    046        PersistentFieldBundle gatherChanges(String pageName);
    047
    048        /**
    049         * Discards all changes for the indicated page. This will not affect pages that have already been attached to this
    050         * request, but will affect subsequent page attachments in this and later requests.
    051         *
    052         * @param pageName logical name of page whose persistent field data is to be discarded
    053         */
    054        void discardChanges(String pageName);
    055
    056        /**
    057         * Discards changes on the indicated page for a specific strategy only. This will not affect pages that have already
    058         * been attached to this request, but will affect subsequent page attachments in this and later requests.
    059         *
    060         * @param pageName logical name of page whose persistent field data is to be discarded
    061         *
    062         * @param strategyName name of the strategy of which field data is to be discarded
    063         */
    064        void discardChanges(String pageName, String strategyName);
    065
    066    }