tapestry/tapestry-framework/src/java/org/apache/tapestry/services/DataSqueezerFilter.java

// Copyright 2006 The Apache Software Foundation
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package org.apache.tapestry.services;

/**
 * @author James Carman
 */
public interface DataSqueezerFilter {

    /**
     * Optionally squeezes the data object into a String.
     * 
     * @param data the data to squeeze
     * @param dataSqueezer the next squeezer in the pipeline
     * 
     * @return the string representation
     */
    String squeeze(Object data, DataSqueezer dataSqueezer);

    /**
     * A convenience; invokes {@link #squeeze(Object, DataSqueezer)}for each element in the
     * data array. If data is null, returns null.
     * 
     * @param data the data to squeeze
     * @param dataSqueezer the next squeezer in the pipeline
     * 
     * @return the string representation
     */
    String[] squeeze(Object[] data, DataSqueezer dataSqueezer);

    /**
     * Unsqueezes the string. Note that in a special case, where the first
     * character of the string is not a recognized prefix, it is assumed that
     * the string is simply a string, and returned with no change.
     * 
     * @param string the string representation of the data
     * @param dataSqueezer the next squeezer in the pipeline
     * 
     * @return the unsqueezed data object
     */
    Object unsqueeze(String string, DataSqueezer dataSqueezer);

    /**
     * Convenience method for unsqueezing many strings (back into objects).
     * <p>
     * If strings is null, returns null.
     * </p>
     * @param strings the string representation of the data
     * @param dataSqueezer the next squeezer in the pipeline
     *
     * @return the unsqueezed data object
     */
    Object[] unsqueeze(String[] strings, DataSqueezer dataSqueezer);
}