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.core.request.handler;
018
019import org.apache.wicket.protocol.http.PageExpiredException;
020import org.apache.wicket.request.component.IRequestablePage;
021import org.apache.wicket.request.mapper.parameter.PageParameters;
022
023
024/**
025 * Represents object capable of providing a page instance. In some cases the implementation class
026 * might now page class and page parameters without having the actual page instance. Thus it's
027 * recommended to call {@link #getPageParameters()} instead of calling {@link #getPageInstance()}
028 * .getPageParameters(). Same goes for page class.
029 *
030 * @author Matej Knopp
031 */
032public interface IPageProvider
033{
034        /**
035         * Returns page instance specified by the constructor.
036         *
037         * @return page instance
038         * @throws PageExpiredException if the specified page
039     *          could not have been found and the constructor used did not provide enough information
040     *          to create new page instance
041         */
042        IRequestablePage getPageInstance()  throws PageExpiredException;
043
044        /**
045         * Returns {@link PageParameters} of the page.
046         *
047         * @return page parameters
048         * @throws PageExpiredException if the specified page
049     *          could not have been found and the constructor used did not provide enough information
050     *          to create new page instance
051         */
052        PageParameters getPageParameters()  throws PageExpiredException;
053
054        /**
055         * Returns whether the provided page was expired prior to this access.
056         *
057         * @return <code>true</code> if the page was created after its original instance expired.
058         */
059        boolean wasExpired();
060
061        /**
062         * Returns class of the page.
063         * @throws PageExpiredException if the specified page
064     *          could not have been found and the constructor used did not provide enough information
065     *          to create new page instance
066         * @return page class
067         */
068        Class<? extends IRequestablePage> getPageClass() throws PageExpiredException;
069
070        /**
071         * Returns the page id.
072         *
073         * @return page id
074         */
075        Integer getPageId();
076
077        /**
078         * Returns the number of times this page has been rendered.
079         *
080         * @return the number of times this page has been rendered.
081         */
082        Integer getRenderCount();
083
084        /**
085         * Detaches the page if it has been loaded.
086         */
087        void detach();
088
089        /**
090         * If this provider returns existing page, regardless if it was already created by PageProvider
091         * itself or is or can be found in the data store. The only guarantee is that by calling
092         * {@link PageProvider#getPageInstance()} this provider will return an existing instance and no
093         * page will be created.
094         * 
095         * @return if provides an existing page
096         */
097        boolean hasPageInstance();
098
099        /**
100         * Returns whether or not the page instance held by this provider has been instantiated by the
101         * provider.
102         *
103         * @throws IllegalStateException
104         *             if this method is called and the provider does not yet have a page instance, ie
105         *             if {@link #getPageInstance()} has never been called on this provider
106         * @return {@code true} iff the page instance held by this provider was instantiated by the
107         *         provider
108         */
109        boolean doesProvideNewPage();
110}