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.services;
016    
017    /**
018     * Lightweight serialization used to encode values into strings that are stored in query parameters
019     * and hidden fields.
020     */
021    public interface DataSqueezer
022    {
023        /**
024         * Squeezes the data object into a String by locating an appropriate adaptor that can perform
025         * the conversion. data may be null.
026         *
027         * @param data
028         *          The object to squeeze.
029         *
030         * @return The string equivalent of the data in "squeezed" form.
031         */
032        String squeeze(Object data);
033    
034        /**
035         * A convenience; invokes {@link #squeeze(Object)} for each element in the data array. If data
036         * is null, returns null.
037         *
038         * @param data
039         *          Array of objects to squeeze.
040         *
041         * @return Squeezed string array.
042         */
043        String[] squeeze(Object[] data);
044    
045        /**
046         * Unsqueezes the string. Note that in a special case, where the first character of the string
047         * is not a recognized prefix, it is assumed that the string is simply a string, and returned
048         * with no change.
049         *
050         * @param string
051         *          The data to unsqueeze.
052         *
053         * @return The object representation of the data - theoretically matching the object
054         *          passed in via {@link #squeeze(Object)}. 
055         */
056        Object unsqueeze(String string);
057    
058        /**
059         * Convenience method for unsqueezing many strings (back into objects).
060         * <p>
061         * If strings is null, returns null.
062         * </p>
063         *
064         * @param strings
065         *          The string data array to unsqueeze.
066         *
067         * @return The data in its object form, as was passed in to {@link #squeeze(Object[])}. 
068         */
069        Object[] unsqueeze(String[] strings);
070    }