/**

* Jooby https://jooby.io

* Apache License Version 2.0 https://jooby.io/LICENSE.txt

* Copyright 2014 Edgar Espina

*/

package io.jooby;

import javax.annotation.Nonnull;

import javax.annotation.Nullable;

import java.nio.charset.Charset;

import java.nio.charset.StandardCharsets;

/**

* Non-blocking sender. Reactive responses uses this class to send partial data in non-blocking

* manner.

*

* RxJava example:

*

* <pre>{@code

*

* Sender sender = ctx.getSender();

*

* Flux.fromCallable(...)

* .subscribe(new Subscriber () {

*

* onSubscribe(Subscription s) {

* this.subscription = s;

* this.subscription.request(1);

* }

*

* onNext(Object next) {

* sender.write(next, (ctx, cause) -> {

* subscription.request(1);

* });

* }

*

* onError(Throwable error) {

* subscription.cancel();

* }

*

* onComplete() {

* sender.close();

* }

* })

*

* }</pre>

*

* @since 2.0.0

* @author edgar

*/

public interface Sender {

/**

* Write callback.

*/

interface Callback {

/**

* Callback after for <code>write</code> operation.

*

* @param ctx Web context.

* @param cause Cause in case of error or <code>null</code> for success.

*/

void onComplete(@Nonnull Context ctx, @Nullable Throwable cause);

}

/**

* Write a string chunk. Chunk is flushed immediately.

*

* @param data String chunk.

* @param callback Callback.

* @return This sender.

*/

@Nonnull default Sender write(@Nonnull String data, @Nonnull Callback callback) {

return write(data, StandardCharsets.UTF_8, callback);

}

/**

* Write a string chunk. Chunk is flushed immediately.

*

* @param data String chunk.

* @param charset Charset.

* @param callback Callback.

* @return This sender.

*/

@Nonnull default Sender write(@Nonnull String data, @Nonnull Charset charset,

@Nonnull Callback callback) {

return write(data.getBytes(charset), callback);

}

/**

* Write a bytes chunk. Chunk is flushed immediately.

*

* @param data Bytes chunk.

* @param callback Callback.

* @return This sender.

*/

@Nonnull Sender write(@Nonnull byte[] data, @Nonnull Callback callback);

/**

* Close the sender.

*/

void close();

}