org.springframework.http.codec.ServerSentEvent Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of spring-web Show documentation
Spring Web
There is a newer version: 6.2.0
/*
 * Copyright 2002-2024 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
 *
 *      https://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.springframework.http.codec;

import java.time.Duration;

import org.springframework.lang.Nullable;

/**
 * Representation for a Server-Sent Event for use with Spring's reactive Web support.
 * {@code Flux} or {@code Observable} is the
 * reactive equivalent to Spring MVC's {@code SseEmitter}.
 *
 * @author Sebastien Deleuze
 * @author Arjen Poutsma
 * @since 5.0
 * @param  the type of data that this event contains
 * @see ServerSentEventHttpMessageWriter
 * @see Server-Sent Events W3C recommendation
 */
public final class ServerSentEvent {

	@Nullable
	private final String id;

	@Nullable
	private final String event;

	@Nullable
	private final Duration retry;

	@Nullable
	private final String comment;

	@Nullable
	private final T data;


	private ServerSentEvent(@Nullable String id, @Nullable String event, @Nullable Duration retry,
			@Nullable String comment, @Nullable T data) {

		this.id = id;
		this.event = event;
		this.retry = retry;
		this.comment = comment;
		this.data = data;
	}


	/**
	 * Return the {@code id} field of this event, if available.
	 */
	@Nullable
	public String id() {
		return this.id;
	}

	/**
	 * Return the {@code event} field of this event, if available.
	 */
	@Nullable
	public String event() {
		return this.event;
	}

	/**
	 * Return the {@code retry} field of this event, if available.
	 */
	@Nullable
	public Duration retry() {
		return this.retry;
	}

	/**
	 * Return the comment of this event, if available.
	 */
	@Nullable
	public String comment() {
		return this.comment;
	}

	/**
	 * Return the {@code data} field of this event, if available.
	 */
	@Nullable
	public T data() {
		return this.data;
	}


	@Override
	public String toString() {
		return ("ServerSentEvent [id = '" + this.id + "', event='" + this.event + "', retry=" +
				this.retry + ", comment='" + this.comment + "', data=" + this.data + ']');
	}


	/**
	 * Return a builder for a {@code ServerSentEvent}.
	 * @param  the type of data that this event contains
	 * @return the builder
	 */
	public static  Builder builder() {
		return new BuilderImpl<>();
	}

	/**
	 * Return a builder for a {@code ServerSentEvent}, populated with the given {@linkplain #data() data}.
	 * @param  the type of data that this event contains
	 * @return the builder
	 */
	public static  Builder builder(T data) {
		return new BuilderImpl<>(data);
	}


	/**
	 * A mutable builder for a {@code ServerSentEvent}.
	 *
	 * @param  the type of data that this event contains
	 */
	public interface Builder {

		/**
		 * Set the value of the {@code id} field.
		 * @param id the value of the id field
		 * @return {@code this} builder
		 */
		Builder id(String id);

		/**
		 * Set the value of the {@code event} field.
		 * @param event the value of the event field
		 * @return {@code this} builder
		 */
		Builder event(String event);

		/**
		 * Set the value of the {@code retry} field.
		 * @param retry the value of the retry field
		 * @return {@code this} builder
		 */
		Builder retry(Duration retry);

		/**
		 * Set SSE comment. If a multi-line comment is provided, it will be turned into multiple
		 * SSE comment lines as defined in Server-Sent Events W3C recommendation.
		 * @param comment the comment to set
		 * @return {@code this} builder
		 */
		Builder comment(String comment);

		/**
		 * Set the value of the {@code data} field. If the {@code data} argument is a multi-line
		 * {@code String}, it will be turned into multiple {@code data} field lines as defined
		 * in the Server-Sent Events W3C recommendation. If {@code data} is not a String, it will
		 * be {@linkplain org.springframework.http.codec.json.Jackson2JsonEncoder encoded} into JSON.
		 * @param data the value of the data field
		 * @return {@code this} builder
		 */
		Builder data(@Nullable T data);

		/**
		 * Builds the event.
		 * @return the built event
		 */
		ServerSentEvent build();
	}


	private static class BuilderImpl implements Builder {

		@Nullable
		private String id;

		@Nullable
		private String event;

		@Nullable
		private Duration retry;

		@Nullable
		private String comment;

		@Nullable
		private T data;

		public BuilderImpl() {
		}

		public BuilderImpl(T data) {
			this.data = data;
		}

		@Override
		public Builder id(String id) {
			this.id = id;
			return this;
		}

		@Override
		public Builder event(String event) {
			this.event = event;
			return this;
		}

		@Override
		public Builder retry(Duration retry) {
			this.retry = retry;
			return this;
		}

		@Override
		public Builder comment(String comment) {
			this.comment = comment;
			return this;
		}

		@Override
		public Builder data(@Nullable T data) {
			this.data = data;
			return this;
		}

		@Override
		public ServerSentEvent build() {
			return new ServerSentEvent<>(this.id, this.event, this.retry, this.comment, this.data);
		}
	}

}