001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.wicket.page;
018
019import org.apache.wicket.util.io.IClusterable;
020
021// this iface used to extend IDetachable, however this causes problems because Page becomes IDetachable and some property models will cause an infinite loop triggering detach on the component again because it is their target object. In the future Component should indeed implement IDetachable, for now copied #detach into this iface directly.
022public interface IManageablePage extends IClusterable
023{
024        /**
025         * Gets whether the page is stateless. Components on stateless page must not render any stateful
026         * urls. Stateful urls are urls, which refer to a certain (current) page instance and don't
027         * contain enough information to reconstruct page if it's not available (page class).
028         * 
029         * @return Whether this page is stateless
030         */
031        // note that this has different semantics than Component#isStateless()
032        boolean isPageStateless();
033
034        /**
035         * @return A unique identifier for this page map entry
036         */
037        int getPageId();
038
039        /**
040         * Detaches model after use. This is generally used to null out transient references that can be
041         * re-attached later.
042         */
043        void detach();
044
045        /**
046         * Sets whether or not the page is allowed to change its page id. Implementations of this
047         * interface usually change their page id once a change to the data structure is made and
048         * historical record of the current state needs to be kept (usually to be accessible via the
049         * back button). Keeping a historical record is usually achieved by simply incrementing the page
050         * id to the next unique number, so when the implementation is stored it is done so in a new
051         * slot.
052         * 
053         * This method is useful when for some reason we do not want the implementation to change its
054         * page id under any circumstances. One concrete example is an AJAX request. Suppose the page
055         * with id 10 was written out with callbacks pointing to id 10. Suppose that the user executed
056         * some AJAX callbacks which have changed the page id to 15. Now, the user clicks a non-AJAX
057         * link that was never updated by an AJAX update and still points to id 10 - which causes the
058         * state of the page to be rolled back - which is usually undesirable as all changes made to the
059         * page by AJAX requests are lost. So, instead, whatever is invoking the execution of the AJAX
060         * request on the page can use this method to tell the page to not update its page id thereby
061         * solving the problem.
062         * 
063         * @param freeze
064         * 
065         * @return previous state
066         */
067        boolean setFreezePageId(boolean freeze);
068}