org.glassfish.grizzly.Transformer Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of grizzly-http-all Show documentation
The newest version!
/*
 * Copyright (c) 2008, 2020 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 actually 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
 * Transformer methods. This way it's possible to reuse single instance of a stateful Transformer to
 * process lots of concurrent transformations.
 *
 * @author Alexey Stashok
 */
public interface Transformer {
    /**
     * Get the Transformer name. The name is used to store Transformer associated data.
     *
     * @return The Transformer 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
     * ({@link AttributeStorage}).
     *
     * @param storage the external state storage, where Transformer could get/put a state.
     * @param input data to transform
     * @return the result {@link TransformationResult}
     *
     * @throws org.glassfish.grizzly.TransformationException if failed to transport i.e. invalid types
     */
    TransformationResult 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.
     *
     * @param storage the external state storage, where Transformer could retrieve or store its state.
     * @return the last returned Transformer result.
     */
    TransformationResult getLastResult(AttributeStorage storage);

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

    boolean hasInputRemaining(AttributeStorage storage, K input);
}