/*
 * Copyright (c) 2008, 2017 Oracle and/or its affiliates. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0, which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * This Source Code may also be made available under the following Secondary
 * Licenses when the conditions for such availability set forth in the
 * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
 * version 2 with the GNU Classpath Exception, which is available at
 * https://www.gnu.org/software/classpath/license.html.
 *
 * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
 */

package org.glassfish.grizzly;

import org.glassfish.grizzly.attributes.AttributeStorage;

Transformer interface, which knows how to transform the original
data to some custom representation.
A Transformer implementation could be stateful or stateless. However
it's very easy to write stateful Transformer, which actaully doesn't save any state internally, but uses AttributeStorage as an external state storage. Please note, that AttributeStorage is being passed as the parameter to all Transformer methods. This way it's
possible to reuse single instance of a stateful Transformer to
process lots of concurrent transformations.
Author:
Alexey Stashok/**
 * <tt>Transformer</tt> interface, which knows how to transform the original
 * data to some custom representation.
 * A <tt>Transformer</tt> implementation could be stateful or stateless. However
 * it's very easy to write stateful <tt>Transformer</tt>, which actaully doesn't
 * save any state internally, but uses {@link AttributeStorage} as an external
 * state storage. Please note, that {@link AttributeStorage} is being passed
 * as the parameter to all <tt>Transformer</tt> methods. This way it's
 * possible to reuse single instance of a stateful <tt>Transformer</tt> to
 * process lots of concurrent transformations.
 *
 * @author Alexey Stashok
 */
public interface Transformer<K, L> {
    
Get the Transformer name. The name is used to store
Transformer associated data.
Returns:
The Transformer name./**
     * Get the <tt>Transformer</tt> name. The name is used to store
     * <tt>Transformer</tt> associated data.
     * 
     * @return The <tt>Transformer</tt> name.
     */
    String getName();

    
Transforms an input data to some custom representation.
Input and output are not passed implicitly, which means that
Transformer is able to retrieve input and output from its internal state or from external storage (AttributeStorage). 
Params:
storage – the external state storage, where Transformer could
       get/put a state.
Throws:
TransformationException – 
Returns:
the result TransformationResult/**
     * Transforms an input data to some custom representation.
     * Input and output are not passed implicitly, which means that
     * <tt>Transformer</tt> is able to retrieve input and output from its
     * internal state or from external storage ({@link AttributeStorage}).
     * 
     * @param storage the external state storage, where <tt>Transformer</tt> could
     *        get/put a state.
     * @return the result {@link TransformationResult}
     * 
     * @throws org.glassfish.grizzly.TransformationException
     */
    TransformationResult<K, L> transform(AttributeStorage storage, K input)
            throws TransformationException;

    
Gets the last returned Transformer result.
Last result could be either retrieved from internal state, or external
storage, which is passed as the parameter.
Params:
storage – the external state storage, where Transformer
       could retrieve or store its state.
Returns:
the last returned Transformer result./**
     * Gets the last returned <tt>Transformer</tt> result.
     * Last result could be either retrieved from internal state, or external
     * storage, which is passed as the parameter.
     * 
     * @param storage the external state storage, where <tt>Transformer</tt>
     *        could retrieve or store its state.
     * @return the last returned <tt>Transformer</tt> result.
     */
    TransformationResult<K, L> getLastResult(AttributeStorage storage);

    
The Transformer has done its work and can release all
associated resource.
Params:
storage – the external state storage, where Transformer
       could retrieve or store its state./**
     * The <tt>Transformer</tt> has done its work and can release all
     * associated resource.
     *
     * @param storage the external state storage, where <tt>Transformer</tt>
     *        could retrieve or store its state.
     */
    void release(AttributeStorage storage);

    boolean hasInputRemaining(AttributeStorage storage, K input);
}