org.eclipse.jetty.io.Connection Maven / Gradle / Ivy
//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
package org.eclipse.jetty.io;
import java.io.Closeable;
import java.nio.ByteBuffer;
import java.util.EventListener;
import java.util.concurrent.TimeoutException;
import org.eclipse.jetty.util.component.Container;
/**
* A {@link Connection} is associated to an {@link EndPoint} so that I/O events
* happening on the {@link EndPoint} can be processed by the {@link Connection}.
* A typical implementation of {@link Connection} overrides {@link #onOpen()} to
* {@link EndPoint#fillInterested(org.eclipse.jetty.util.Callback) set read interest} on the {@link EndPoint},
* and when the {@link EndPoint} signals read readyness, this {@link Connection} can
* read bytes from the network and interpret them.
*/
public interface Connection extends Closeable
{
/**
* Adds a listener of connection events.
*
* @param listener the listener to add
*/
void addEventListener(EventListener listener);
/**
* Removes a listener of connection events.
*
* @param listener the listener to remove
*/
void removeEventListener(EventListener listener);
/**
* Callback method invoked when this connection is opened.
* Creators of the connection implementation are responsible for calling this method.
*/
void onOpen();
/**
* Callback method invoked when this connection is closed.
* Creators of the connection implementation are responsible for calling this method.
*
* @param cause The cause of the close or null for a normal close
*/
void onClose(Throwable cause);
/**
* @return the {@link EndPoint} associated with this Connection.
*/
EndPoint getEndPoint();
/**
* Performs a logical close of this connection.
* For simple connections, this may just mean to delegate the close to the associated
* {@link EndPoint} but, for example, SSL connections should write the SSL close message
* before closing the associated {@link EndPoint}.
*/
@Override
void close();
/**
* Callback method invoked upon an idle timeout event.
* Implementations of this method may return true to indicate that the idle timeout
* handling should proceed normally, typically failing the EndPoint and causing it to
* be closed.
* When false is returned, the handling of the idle timeout event is halted
* immediately and the EndPoint left in the state it was before the idle timeout event.
*
* @return true to let the EndPoint handle the idle timeout,
* false to tell the EndPoint to halt the handling of the idle timeout.
*/
boolean onIdleExpired(TimeoutException timeoutException);
long getMessagesIn();
long getMessagesOut();
long getBytesIn();
long getBytesOut();
long getCreatedTimeStamp();
/**
* {@link Connection} implementations implement this interface when they
* can upgrade from the protocol they speak (for example HTTP/1.1)
* to a different protocol (e.g. HTTP/2).
*
* @see EndPoint#upgrade(Connection)
* @see UpgradeTo
*/
interface UpgradeFrom
{
/**
* Invoked during an {@link EndPoint#upgrade(Connection) upgrade}
* to produce a buffer containing bytes that have not been consumed by
* this connection, and that must be consumed by the upgrade-to
* connection.
*
* @return a buffer of unconsumed bytes to pass to the upgrade-to connection.
* The buffer does not belong to any pool and should be discarded after
* having consumed its bytes.
* The returned buffer may be null if there are no unconsumed bytes.
*/
ByteBuffer onUpgradeFrom();
}
/**
* {@link Connection} implementations implement this interface when they
* can be upgraded to the protocol they speak (e.g. HTTP/2)
* from a different protocol (e.g. HTTP/1.1).
*/
interface UpgradeTo
{
/**
* Invoked during an {@link EndPoint#upgrade(Connection) upgrade}
* to receive a buffer containing bytes that have not been consumed by
* the upgrade-from connection, and that must be consumed by this
* connection.
*
* @param buffer a non-null buffer of unconsumed bytes received from
* the upgrade-from connection.
* The buffer does not belong to any pool and should be discarded after
* having consumed its bytes.
*/
void onUpgradeTo(ByteBuffer buffer);
}
/**
* A Listener for connection events.
* Listeners can be added to a {@link Connection} to get open and close events.
* The AbstractConnectionFactory implements a pattern where objects implement
* this interface that have been added via {@link Container#addBean(Object)} to
* the Connector or ConnectionFactory are added as listeners to all new connections
*
*/
interface Listener extends EventListener
{
default void onOpened(Connection connection)
{
}
default void onClosed(Connection connection)
{
}
}
}