001// Copyright 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.record;
016
017import org.apache.tapestry.engine.ServiceEncoding;
018
019/**
020 * Service tapestry.persist.ClientPropertyPersistenceScope. Determines whether a particular property
021 * needs to be persisted or not.
022 * 
023 * @author Mindbridge
024 * @since 4.0
025 * @see org.apache.tapestry.record.ClientPropertyPersistenceStrategy
026 */
027public interface ClientPropertyPersistenceScope
028{
029    /**
030     * Determines whether state should be encoded for the request.
031     * 
032     * @param encoding
033     *            identifies the service, URL and base set of parameters
034     * @param pageName
035     *            the page for which data is potentially to be encoded
036     * @param data
037     * @return true if state should be encoded into the encoding, false otherwise
038     */
039
040    public boolean shouldEncodeState(ServiceEncoding encoding, String pageName,
041            PersistentPropertyData data);
042
043    /**
044     * Constructs a parameter name for a particular page name. The parameter name can be recognized
045     * (in a later request) by the {@link #isParameterForScope(String)} method.
046     * 
047     * @param pageName
048     *            the name of the page for which a corresponding parameter name should be generated.
049     * @returns a query parameter name that identifies the page and this client persistence scope.
050     */
051
052    public String constructParameterName(String pageName);
053
054    /**
055     * Checks a parameter to see if it was the result of {@link #constructParameterName(String)} for
056     * this persistence scope.
057     * 
058     * @param parameterName
059     *            a query parameter name
060     * @return true if the parameterName was genereted (i.e., is properly prefixed) by this scope,
061     *         false otherwise.
062     */
063
064    public boolean isParameterForScope(String parameterName);
065
066    /**
067     * Extracts a page name from a query parameter name.
068     * 
069     * @param parameterName
070     *            the paramter name, for which {@link #isParameterForScope(String) must return true
071     * @return the name of the page
072     */
073    public String extractPageName(String parameterName);
074}