001    // Copyright 2004, 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    
015    package org.apache.tapestry.components;
016    
017    /**
018     * An interface for converting an objects to their primary keys and back.
019     * Typically used to determine how to store a given object as a hidden value
020     * when rendering a form.
021     * <p>
022     * This interface is used by the
023     * {@link org.apache.tapestry.components.ForBean For component}. When a primary
024     * key converter is available, it is used during the render, and as part of the
025     * rewind phase that processes the form submission.
026     * <p>
027     * During rendering, {@link #getPrimaryKey(Object)} is invoked for each value.
028     * This method is invoked just before the For's body is rendered. The resulting
029     * primary key is written into the client as a hidden form field.
030     * <p>
031     * Likewise, during rewind, {@link #getValue(Object)} is invoked for each key,
032     * to get back the same (or equivalent) object. Again, the method is invoked
033     * just before the For's body is rendered.
034     * <p>
035     * The {@link org.apache.tapestry.util.DefaultPrimaryKeyConverter} uses this
036     * relationship between a For component and its primary key converter to track
037     * what the current value being rendered or rewound is.
038     * 
039     * @author mb
040     * @since 4.0
041     */
042    public interface IPrimaryKeyConverter
043    {
044    
045        /**
046         * Returns the primary key of the given value.
047         * 
048         * @param objValue
049         *            the value for which a primary key needs to be extracted
050         * @return the primary key of the value
051         */
052        Object getPrimaryKey(Object value);
053    
054        /**
055         * Returns the value corresponding the given primary key.
056         * 
057         * @param objPrimaryKey
058         *            the primary key for which a value needs to be generated
059         * @return the generated value corresponding to the given primary key
060         */
061        Object getValue(Object primaryKey);
062    
063    }