ratpack.stream.StreamEvent Maven / Gradle / Ivy
/*
* Copyright 2014 the original author or authors.
*
* 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 ratpack.stream;
import ratpack.api.Nullable;
/**
* Represents an event emitted by a publisher.
*
* @param the type of data item
* @see Streams#wiretap(org.reactivestreams.Publisher, ratpack.func.Action)
*/
public interface StreamEvent {
/**
* The opaque id of the subscription that this event relates to.
*
* Events are emitted for each subscription to a publisher.
* This value can be used for differentiating events from different subscriptions.
*
* The ids are only unique for a context. That is, they are not globally unique.
* More precise semantics of ids should be specified by methods that emit events.
*
* @return an opaque id of the subscription this event belongs to
*/
int getSubscriptionId();
/**
* Whether or not this event represents the completion of the stream.
*
* @return whether or not this event represents the completion of the stream
*/
boolean isComplete();
/**
* Whether or not this event represents an error.
*
* If this method returns {@code true}, {@link #getError()} will return the corresponding exception.
* If this method returns {@code false}, {@link #getError()} will return {@code null}.
*
* @return whether or not this event represents an error
*/
boolean isError();
/**
* Whether or not this event represents an emission of data.
*
* If this method returns {@code true}, {@link #getItem()} will return the corresponding data.
* If this method returns {@code false}, {@link #getItem()} will return {@code null}.
*
* @return whether or not this event represents an error
*/
boolean isData();
/**
* Whether or not this event represents cancellation of the stream.
*
* @return whether or not this event represents cancellation of the stream
*/
boolean isCancel();
/**
* Whether or not this event represents a request for more data.
*
* If this method returns {@code true}, {@link #getRequestAmount()} will return the amount requested.
* If this method returns {@code false}, {@link #getRequestAmount()} will return {@code 0}.
*
* @return whether or not this event represents an error
*/
boolean isRequest();
/**
* The request amount, if this event represents a request.
*
* If {@link #isRequest()} returns {@code true}, this method will return the corresponding request amount.
* If {@link #isRequest()} returns {@code false}, this method will return {@code 0}.
*
* @return the request amount if this event represents a request, else {@code 0}
*/
int getRequestAmount();
/**
* The error, if this event represents an error.
*
* If {@link #isError()} returns {@code true}, this method will return the corresponding exception.
* If {@link #isError()} returns {@code false}, this method will return null.
*
* @return the error if this event represents an error, else {@code null}
*/
@Nullable
Throwable getError();
/**
* The data, if this event represents an emission of data.
*
* If {@link #isData()} returns {@code true}, this method will return the corresponding data item.
* If {@link #isData()} returns {@code false}, this method will return null.
*
* @return the data if this event represents data, else {@code null}
*/
@Nullable
T getItem();
}