001/*
002 * Copyright 2024-2026 Revetware LLC.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.soklet.servlet.jakarta;
018
019import org.jspecify.annotations.NonNull;
020import org.jspecify.annotations.Nullable;
021
022import java.util.Locale;
023
024import static java.util.Objects.requireNonNull;
025
026/**
027 * The set of all possible event payloads emittable by {@link SokletServletPrintWriter}.
028 *
029 * @author <a href="https://www.revetkn.com">Mark Allen</a>
030 */
031public sealed interface SokletServletPrintWriterEvent permits
032                SokletServletPrintWriterEvent.CharsWritten,
033                SokletServletPrintWriterEvent.CharWritten,
034                SokletServletPrintWriterEvent.StringWritten,
035                SokletServletPrintWriterEvent.ValuePrinted,
036                SokletServletPrintWriterEvent.ValueWithNewlinePrinted,
037                SokletServletPrintWriterEvent.NewlinePrinted,
038                SokletServletPrintWriterEvent.PrintfPerformed,
039                SokletServletPrintWriterEvent.FormatPerformed,
040                SokletServletPrintWriterEvent.CharSequenceAppended,
041                SokletServletPrintWriterEvent.CharAppended {
042
043        /**
044         * Event emitted when a {@code char[]} is written to the {@link SokletServletPrintWriter}.
045         */
046        record CharsWritten(
047                        @NonNull char[] chars,
048                        int offset,
049                        int length
050        ) implements SokletServletPrintWriterEvent {
051                public CharsWritten {
052                        requireNonNull(chars);
053                }
054        }
055
056        /**
057         * Event emitted when an {@code int} (character) is written to the {@link SokletServletPrintWriter}.
058         */
059        record CharWritten(
060                        int ch
061        ) implements SokletServletPrintWriterEvent {}
062
063        /**
064         * Event emitted when a {@link String} is written to the {@link SokletServletPrintWriter}.
065         */
066        record StringWritten(
067                        @NonNull String string,
068                        int offset,
069                        int length
070        ) implements SokletServletPrintWriterEvent {
071                public StringWritten {
072                        requireNonNull(string);
073                }
074        }
075
076        /**
077         * Event emitted when an {@link Object} value is written to the {@link SokletServletPrintWriter}.
078         */
079        record ValuePrinted(
080                        @Nullable Object value
081        ) implements SokletServletPrintWriterEvent {}
082
083        /**
084         * Event emitted when an {@link Object} value with a newline is written to the {@link SokletServletPrintWriter}.
085         */
086        record ValueWithNewlinePrinted(
087                        @Nullable Object value
088        ) implements SokletServletPrintWriterEvent {}
089
090        /**
091         * Event emitted when a newline is written to the {@link SokletServletPrintWriter}.
092         */
093        record NewlinePrinted() implements SokletServletPrintWriterEvent {}
094
095        /**
096         * Event emitted when the result of a "printf" operation is written to the {@link SokletServletPrintWriter}.
097         */
098        record PrintfPerformed(
099                        @Nullable Locale locale,
100                        @NonNull String format,
101                        @Nullable Object @NonNull [] args
102        ) implements SokletServletPrintWriterEvent {
103                public PrintfPerformed {
104                        requireNonNull(format);
105                        requireNonNull(args);
106                }
107        }
108
109        /**
110         * Event emitted when the result of a "format" operation is written to the {@link SokletServletPrintWriter}.
111         */
112        record FormatPerformed(
113                        @Nullable Locale locale,
114                        @NonNull String format,
115                        @Nullable Object @NonNull [] args
116        ) implements SokletServletPrintWriterEvent {
117                public FormatPerformed {
118                        requireNonNull(format);
119                        requireNonNull(args);
120                }
121        }
122
123        /**
124         * Event emitted when a {@link CharSequence} is appended to the {@link SokletServletPrintWriter}.
125         */
126        record CharSequenceAppended(
127                        @NonNull CharSequence charSequence,
128                        int start,
129                        int end
130        ) implements SokletServletPrintWriterEvent {
131                public CharSequenceAppended {
132                        requireNonNull(charSequence);
133                }
134        }
135
136        /**
137         * Event emitted when a {@code char} is appended to the {@link SokletServletPrintWriter}.
138         */
139        record CharAppended(
140                        char ch
141        ) implements SokletServletPrintWriterEvent {
142                public CharAppended {}
143        }
144}