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    }