<commit_before>/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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.qpid.proton4j.engine;

import java.util.concurrent.ScheduledExecutorService;
import java.util.function.Consumer;

import org.apache.qpid.proton4j.buffer.ProtonBuffer;
import org.apache.qpid.proton4j.engine.exceptions.EngineFailedException;
import org.apache.qpid.proton4j.engine.exceptions.EngineShutdownException;
import org.apache.qpid.proton4j.engine.exceptions.EngineStateException;
import org.apache.qpid.proton4j.engine.exceptions.ProtonException;

/**
 * AMQP Engine interface.
 */
public interface Engine extends Consumer<ProtonBuffer> {

    /**
     * Returns true if the engine is accepting input from the ingestion entry points.
     * <p>
     * When false any attempts to write more data into the engine will result in an
     * error being returned from the write operation.  An engine that has not been
     * started or that has been failed or shutdown will report as not writable.
     *
     * TODO What is the best why to reflect the state, how do we trigger changes
     *
     * @return true if the engine is current accepting more input.
     */
    boolean isWritable();

    /**
     * @return true if the Engine has been shutdown and is no longer usable.
     */
    boolean isShutdown();

    /**
     * @return true if the Engine has encountered a critical error and cannot produce new data.
     */
    boolean isFailed();

    /**
     * @return the error that caused the {@link Engine} fail and shutdown (or null if not failed).
     */
    Throwable failureCause();

    /**
     * @return the current state of the engine.
     */
    EngineState state();

    /**
     * Gets the {@link Connection} instance that is associated with this {@link Engine} instance.
     * It is valid for an engine implementation to not return a {@link Connection} instance prior
     * to the engine having been started.
     *
     * @return the {@link Connection} that is linked to this engine instance.
     */
    Connection connection();

    /**
     * Starts the engine and returns the {@link Connection} instance that is bound to this Engine.
     *
     * A non-started Engine will not allow ingestion of any inbound data and a Connection linked to
     * the engine that was obtained from the {@link Engine#connection()} method cannot produce any
     * outbound data.
     *
     * @return the Connection instance that is linked to this {@link Engine}
     *
     * @throws EngineStateException if the Engine state has already transition to shutdown or failed.
     */
    Connection start() throws EngineStateException;

    /**
     * Shutdown the engine preventing any future outbound or inbound processing.
     *
     * When the engine is shut down any resources, {@link Connection}, {@link Session} or {@link Link}
     * instances that have an engine shutdown event handler registered will be notified and should react
     * by locally closing that resource if they wish to ensure that the resource's local close event
     * handler gets signaled.
     *
     * @return this Engine
     */
    Engine shutdown();

    /**
     * Transition the {@link Engine} to a failed state if not already closed or closing.
     *
     * If called when the engine has not failed the engine will be transition to the failed state
     * and the method will return an appropriate {@link EngineFailedException} that wraps the given
     * cause.  If called after the engine was shutdown the method returns an {@link EngineShutdownException}
     * indicating that the engine was already shutdown.
     *
     * @param cause
     *      The exception that caused the engine to be forcibly transitioned to the failed state.
     *
     * @return an {@link EngineStateException} that can be thrown indicating the failure and engine state.
     */
    EngineStateException engineFailed(Throwable cause);

    /**
     * Provide data input for this Engine from some external source.
     *
     * @param input
     *      The data to feed into to Engine.
     *
     * @return this Engine
     *
     * @throws EngineStateException if the Engine state precludes accepting new input.
     */
    Engine ingest(ProtonBuffer input) throws EngineStateException;

    /**
     * Provide data input for this Engine from some external source.
     *
     * @param input
     *      The data to feed into to Engine.
     *
     * @throws EngineStateException if the Engine state precludes accepting new input.
     */
    @Override
    default void accept(ProtonBuffer input) throws EngineStateException {
        ingest(input);
    }
<commit_msg>Add more documentation to engine API methods.<commit_after>/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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.qpid.proton4j.engine;

import java.util.concurrent.ScheduledExecutorService;
import java.util.function.Consumer;

import org.apache.qpid.proton4j.buffer.ProtonBuffer;
import org.apache.qpid.proton4j.engine.exceptions.EngineFailedException;
import org.apache.qpid.proton4j.engine.exceptions.EngineNotWritableException;
import org.apache.qpid.proton4j.engine.exceptions.EngineShutdownException;
import org.apache.qpid.proton4j.engine.exceptions.EngineStateException;
import org.apache.qpid.proton4j.engine.exceptions.ProtonException;

/**
 * AMQP Engine interface.
 */
public interface Engine extends Consumer<ProtonBuffer> {

    /**
     * Returns true if the engine is accepting input from the ingestion entry points.
     * <p>
     * When false any attempts to write more data into the engine will result in an
     * error being returned from the write operation.  An engine that has not been
     * started or that has been failed or shutdown will report as not writable.
     *
     * @return true if the engine is current accepting more input.
     */
    boolean isWritable();

    /**
     * @return true if the Engine has been shutdown and is no longer usable.
     */
    boolean isShutdown();

    /**
     * @return true if the Engine has encountered a critical error and cannot produce new data.
     */
    boolean isFailed();

    /**
     * @return the error that caused the {@link Engine} fail and shutdown (or null if not failed).
     */
    Throwable failureCause();

    /**
     * @return the current state of the engine.
     */
    EngineState state();

    /**
     * Gets the {@link Connection} instance that is associated with this {@link Engine} instance.
     * It is valid for an engine implementation to not return a {@link Connection} instance prior
     * to the engine having been started.
     *
     * @return the {@link Connection} that is linked to this engine instance.
     */
    Connection connection();

    /**
     * Starts the engine and returns the {@link Connection} instance that is bound to this Engine.
     *
     * A non-started Engine will not allow ingestion of any inbound data and a Connection linked to
     * the engine that was obtained from the {@link Engine#connection()} method cannot produce any
     * outbound data.
     *
     * @return the Connection instance that is linked to this {@link Engine}
     *
     * @throws EngineStateException if the Engine state has already transition to shutdown or failed.
     */
    Connection start() throws EngineStateException;

    /**
     * Shutdown the engine preventing any future outbound or inbound processing.
     *
     * When the engine is shut down any resources, {@link Connection}, {@link Session} or {@link Link}
     * instances that have an engine shutdown event handler registered will be notified and should react
     * by locally closing that resource if they wish to ensure that the resource's local close event
     * handler gets signaled if that resource is not already locally closed.
     *
     * @return this Engine
     */
    Engine shutdown();

    /**
     * Transition the {@link Engine} to a failed state if not already closed or closing.
     *
     * If called when the engine has not failed the engine will be transition to the failed state
     * and the method will return an appropriate {@link EngineFailedException} that wraps the given
     * cause.  If called after the engine was shutdown the method returns an {@link EngineShutdownException}
     * indicating that the engine was already shutdown.  Repeated calls to this method while the engine
     * is in the failed state should not alter the original failure error or elicit new engine failed
     * event notifications.
     *
     * @param cause
     *      The exception that caused the engine to be forcibly transitioned to the failed state.
     *
     * @return an {@link EngineStateException} that can be thrown indicating the failure and engine state.
     */
    EngineStateException engineFailed(Throwable cause);

    /**
     * Provide data input for this Engine from some external source.  If the engine is not writable
     * when this method is called an {@link EngineNotWritableException} will be thrown if unless the
     * reason for the not writable state is due to engine failure or the engine already having been
     * shut down in which case the appropriate {@link EngineStateException} will be thrown to indicate
     * the reason.
     *
     * @param input
     *      The data to feed into to Engine.
     *
     * @return this Engine
     *
     * @throws EngineStateException if the Engine state precludes accepting new input.
     */
    Engine ingest(ProtonBuffer input) throws EngineStateException;

    /**
     * Provide data input for this Engine from some external source.  If the engine is not writable
     * when this method is called an {@link EngineNotWritableException} will be thrown if unless the
     * reason for the not writable state is due to engine failure or the engine already having been
     * shut down in which case the appropriate {@link EngineStateException} will be thrown to indicate
     * the reason.
     *
     * @param input
     *      The data to feed into to Engine.
     *
     * @throws EngineStateException if the Engine state precludes accepting new input.
     */
    @Override
    default void accept(ProtonBuffer input) throws EngineStateException {
        ingest(input);
    }

{'fraction_non_alphanumeric': 0.06375181113099804, 'fraction_numerical': 0.0017898235745333673, 'mean_word_length': 3.02400548696845, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3143587', 'n_tokens_mistral': 2892, 'n_tokens_neox': 2811, 'n_words': 1408}