diff --git a/src/main/java/net/openhft/chronicle/wire/ValueIn.java b/src/main/java/net/openhft/chronicle/wire/ValueIn.java index 4b2c506d5d..ae73e1a39b 100644 --- a/src/main/java/net/openhft/chronicle/wire/ValueIn.java +++ b/src/main/java/net/openhft/chronicle/wire/ValueIn.java @@ -1,14 +1,6 @@ -/* - * Copyright 2016-2020 chronicle.software - * - * https://chronicle.software - * - * 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 - * +/** + * Reads a LocalTime from the wire and applies it to a given object using the provided BiConsumer. + *

* 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. @@ -41,7 +33,11 @@ import java.util.function.*; /** - * Read in data after reading a field. + * Represents an interface for reading values in various formats from a serialized data source. + * This interface is part of the Chronicle Wire library, which is designed for high-performance + * serialization and deserialization of data. It provides methods to read data types like text, + * binary, numeric, and temporal values, as well as support for more complex types like collections + * and marshallable objects. */ @SuppressWarnings({"rawtypes", "unchecked"}) public interface ValueIn { @@ -148,62 +144,215 @@ default void byteBuffer(@NotNull ByteBuffer bb) { @NotNull WireIn bool(T t, @NotNull ObjBooleanConsumer tFlag); + /** + * Reads an 8-bit integer (byte) value and applies an ObjByteConsumer with the provided object and the read value. + * + * @param The type of object to be passed to the ObjByteConsumer. + * @param t The object to be passed to the ObjByteConsumer. + * @param tb The ObjByteConsumer that accepts the object and the read 8-bit integer value. + * @return The WireIn instance for method chaining. + */ @NotNull WireIn int8(@NotNull T t, @NotNull ObjByteConsumer tb); + /** + * Reads an unsigned 8-bit integer (short) value and applies an ObjShortConsumer with the provided object and the read value. + * + * @param The type of object to be passed to the ObjShortConsumer. + * @param t The object to be passed to the ObjShortConsumer. + * @param ti The ObjShortConsumer that accepts the object and the read unsigned 8-bit integer value. + * @return The WireIn instance for method chaining. + */ @NotNull WireIn uint8(@NotNull T t, @NotNull ObjShortConsumer ti); + /** + * Reads a 16-bit integer (short) value and applies an ObjShortConsumer with the provided object and the read value. + * + * @param The type of object to be passed to the ObjShortConsumer. + * @param t The object to be passed to the ObjShortConsumer. + * @param ti The ObjShortConsumer that accepts the object and the read 16-bit integer value. + * @return The WireIn instance for method chaining. + */ @NotNull WireIn int16(@NotNull T t, @NotNull ObjShortConsumer ti); + /** + * Reads an unsigned 16-bit integer (int) value and applies an ObjIntConsumer with the provided object and the read value. + * + * @param The type of object to be passed to the ObjIntConsumer. + * @param t The object to be passed to the ObjIntConsumer. + * @param ti The ObjIntConsumer that accepts the object and the read unsigned 16-bit integer value. + * @return The WireIn instance for method chaining. + */ @NotNull WireIn uint16(@NotNull T t, @NotNull ObjIntConsumer ti); + /** + * Reads a 32-bit integer (int) value and applies an ObjIntConsumer with the provided object and the read value. + * + * @param The type of object to be passed to the ObjIntConsumer. + * @param t The object to be passed to the ObjIntConsumer. + * @param ti The ObjIntConsumer that accepts the object and the read 32-bit integer value. + * @return The WireIn instance for method chaining. + */ @NotNull WireIn int32(@NotNull T t, @NotNull ObjIntConsumer ti); + /** + * Reads an unsigned 32-bit integer (long) value and applies an ObjLongConsumer with the provided object and the read value. + * + * @param The type of object to be passed to the ObjLongConsumer. + * @param t The object to be passed to the ObjLongConsumer. + * @param tl The ObjLongConsumer that accepts the object and the read unsigned 32-bit integer value. + * @return The WireIn instance for method chaining. + */ @NotNull WireIn uint32(@NotNull T t, @NotNull ObjLongConsumer tl); + /** + * Reads a 64-bit integer (long) value and applies an ObjLongConsumer with the provided object and the read value. + * + * @param The type of object to be passed to the ObjLongConsumer. + * @param t The object to be passed to the ObjLongConsumer. + * @param tl The ObjLongConsumer that accepts the object and the read 64-bit integer value. + * @return The WireIn instance for method chaining. + */ @NotNull WireIn int64(@NotNull T t, @NotNull ObjLongConsumer tl); + /** + * Reads a 32-bit floating-point (float) value and applies an ObjFloatConsumer with the provided object and the read value. + * + * @param The type of object to be passed to the ObjFloatConsumer. + * @param t The object to be passed to the ObjFloatConsumer. + * @param tf The ObjFloatConsumer that accepts the object and the read 32-bit floating-point value. + * @return The WireIn instance for method chaining. + */ @NotNull WireIn float32(@NotNull T t, @NotNull ObjFloatConsumer tf); + /** + * Reads a 64-bit floating-point (double) value and applies an ObjDoubleConsumer with the provided object and the read value. + * + * @param The type of object to be passed to the ObjDoubleConsumer. + * @param t The object to be passed to the ObjDoubleConsumer. + * @param td The ObjDoubleConsumer that accepts the object and the read 64-bit floating-point value. + * @return The WireIn instance for method chaining. + */ @NotNull WireIn float64(@NotNull T t, @NotNull ObjDoubleConsumer td); @NotNull WireIn time(@NotNull T t, @NotNull BiConsumer setLocalTime); + /** + * Reads a ZonedDateTime from the wire and applies it to a given object using the provided BiConsumer. + * + * @param The type of object to be passed to the BiConsumer. + * @param t The object to be passed to the BiConsumer. + * @param tZonedDateTime The BiConsumer that accepts the object and the read ZonedDateTime. + * @return The WireIn instance for method chaining. + */ @NotNull WireIn zonedDateTime(@NotNull T t, @NotNull BiConsumer tZonedDateTime); + /** + * Reads a LocalDate from the wire and applies it to a given object using the provided BiConsumer. + * + * @param The type of object to be passed to the BiConsumer. + * @param t The object to be passed to the BiConsumer. + * @param tLocalDate The BiConsumer that accepts the object and the read LocalDate. + * @return The WireIn instance for method chaining. + */ @NotNull WireIn date(@NotNull T t, @NotNull BiConsumer tLocalDate); + /** + * Reads a LocalDate directly from the wire. + * + * @return The LocalDate read from the wire. + */ default LocalDate date() { return WireInternal.intern(LocalDate.class, text()); } + /** + * Reads a LocalTime directly from the wire. + * + * @return The LocalTime read from the wire. + */ default LocalTime time() { return WireInternal.intern(LocalTime.class, text()); } + /** + * Reads a LocalDateTime directly from the wire. + * + * @return The LocalDateTime read from the wire. + */ default LocalDateTime dateTime() { return WireInternal.intern(LocalDateTime.class, text()); } + /** + * Reads a ZonedDateTime directly from the wire. + * + * @return The ZonedDateTime read from the wire. + */ default ZonedDateTime zonedDateTime() { return WireInternal.intern(ZonedDateTime.class, text()); } + /** + * Checks if there is another element to read in a sequence or collection. + * + * @return True if there is another element to read, false otherwise. + */ boolean hasNext(); + /** + * Checks if there is another item in a sequence. + * + * @return True if there is another sequence item, false otherwise. + */ boolean hasNextSequenceItem(); + /** + * Reads a UUID from the wire and applies it to a given object using the provided BiConsumer. + * + * @param The type of object to be passed to the BiConsumer. + * @param t The object to be passed to the BiConsumer. + * @param tuuid The BiConsumer that accepts the object and the read UUID. + * @return The WireIn instance for method chaining. + */ @NotNull WireIn uuid(@NotNull T t, @NotNull BiConsumer tuuid); + /** + * Reads a LongArrayValues from the wire and applies it to a given object using the provided BiConsumer. + * + * @param The type of object to be passed to the BiConsumer. + * @param values The LongArrayValues to read the data into. + * @param t The object to be passed to the BiConsumer. + * @param setter The BiConsumer that accepts the object and the LongArrayValues. + * @return The WireIn instance for method chaining. + */ @NotNull WireIn int64array(@Nullable LongArrayValues values, T t, @NotNull BiConsumer setter); + /** + * Reads a 128-bit integer value from the wire into the specified TwoLongValue. + * + * @param value The TwoLongValue to read the 128-bit integer into. + * @return The WireIn instance for method chaining. + */ @NotNull default WireIn int128(@NotNull TwoLongValue value) { throw new UnsupportedOperationException(); } + /** + * Reads a 64-bit integer value from the wire into the specified LongValue. + * + * @param value The LongValue to read the 64-bit integer into. + * @return The WireIn instance for method chaining. + */ @NotNull WireIn int64(@NotNull LongValue value); + /** + * Reads a 32-bit integer value from the wire into the specified IntValue. + * + * @param value The IntValue to read the 32-bit integer into. + * @return The WireIn instance for method chaining. + */ @NotNull WireIn int32(@NotNull IntValue value); @@ -222,12 +371,37 @@ default LongValue int64ForBinding(@Nullable LongValue value) { boolean sequence(@NotNull T t, @NotNull BiConsumer tReader); +/** + * Processes a sequence of values from the wire, storing them in a list. It uses a buffer to minimize object creation. + * + * @param list The list to store the processed items. + * @param buffer The buffer for reusing objects. + * @param bufferAdd Supplier to provide new instances for the buffer. + * @param reader0 The reader that processes each item in the sequence. + * @return True if the sequence was processed, false otherwise. + */ boolean sequence(List list, @NotNull List buffer, Supplier bufferAdd, Reader reader0) throws InvalidMarshallableException; +/** + * Processes a sequence of values from the wire using a SerializationStrategy. + * + * @param The type of the object to be processed. + * @param t The object to be processed. + * @param tReader The SerializationStrategy to process the object. + * @return True if the sequence was processed, false otherwise. + */ default boolean sequence(@NotNull T t, @NotNull SerializationStrategy tReader) throws InvalidMarshallableException { return sequence(t, (using, in) -> tReader.readUsing(null, using, in, BracketType.UNKNOWN)); } +/** + * Helper method to read a sequence of values into a list using a buffer. + * + * @param v The ValueIn to read from. + * @param list The list to store the read values. + * @param buffer The buffer for reusing objects. + * @param bufferAdd Supplier to provide new instances for the buffer. + */ default void reader0(ValueIn v, List list, List buffer, Supplier bufferAdd) throws InvalidMarshallableException { while (v.hasNextSequenceItem()) { int size = list.size(); @@ -256,6 +430,16 @@ default boolean sequence(@NotNull List list, return sequence(list, buffer, bufferAdd, this::reader0); } +/** + * Processes a sequence of values from the wire, applying a TriConsumer to each item in the sequence. + * + * @param The type of the first object to be passed to the TriConsumer. + * @param The type of the second object to be passed to the TriConsumer. + * @param t The first object to be passed to the TriConsumer. + * @param k The second object to be passed to the TriConsumer. + * @param tReader The TriConsumer that processes each item in the sequence. + * @return The WireIn instance for method chaining. + */ @NotNull WireIn sequence(@NotNull T t, K k, @NotNull TriConsumer tReader) throws InvalidMarshallableException; default int sequenceWithLength(@NotNull T t, @NotNull ToIntBiFunction tReader) { @@ -264,6 +448,12 @@ default int sequenceWithLength(@NotNull T t, @NotNull ToIntBiFunction { int i = 0; @@ -276,6 +466,12 @@ default int array(Bytes[] array) { }); } +/** + * Reads an array of double values from the wire, populating the provided array. + * + * @param array The array of double values to be populated. + * @return The number of double values read and populated. + */ default int array(double[] array) { return sequenceWithLength(array, (in, a) -> { int i = 0; @@ -285,6 +481,12 @@ default int array(double[] array) { }); } +/** + * Reads an array of double values with delta compression from the wire, populating the provided array. + * + * @param array The array of double values to be populated. + * @return The number of double values read and populated. + */ default int arrayDelta(double[] array) { return sequenceWithLength(array, (in, a) -> { if (!in.hasNextSequenceItem() || a.length == 0) @@ -297,6 +499,12 @@ default int arrayDelta(double[] array) { }); } +/** + * Reads an array of boolean values from the wire, populating the provided array. + * + * @param array The array of boolean values to be populated. + * @return The number of boolean values read and populated. + */ default int array(boolean[] array) { return sequenceWithLength(array, (in, a) -> { int i = 0; @@ -306,6 +514,12 @@ default int array(boolean[] array) { }); } +/** + * Reads an array of long values from the wire, populating the provided array. + * + * @param array The array of long values to be populated. + * @return The number of long values read and populated. + */ default int array(long[] array) { return sequenceWithLength(array, (in, a) -> { int i = 0; @@ -315,6 +529,12 @@ default int array(long[] array) { }); } +/** + * Reads an array of long values with delta compression from the wire, populating the provided array. + * + * @param array The array of long values to be populated. + * @return The number of long values read and populated. + */ default int arrayDelta(long[] array) { return sequenceWithLength(array, (in, a) -> { if (!in.hasNextSequenceItem() || a.length == 0) @@ -327,6 +547,12 @@ default int arrayDelta(long[] array) { }); } +/** + * Reads an array of int values from the wire, populating the provided array. + * + * @param array The array of int values to be populated. + * @return The number of int values read and populated. + */ default int array(int[] array) { return sequenceWithLength(array, (in, a) -> { int i = 0; @@ -336,6 +562,12 @@ default int array(int[] array) { }); } +/** + * Reads an array of byte values from the wire, populating the provided array. + * + * @param array The array of byte values to be populated. + * @return The number of byte values read and populated. + */ default int array(byte[] array) { return sequenceWithLength(array, (in, a) -> { int i = 0; @@ -345,14 +577,37 @@ default int array(byte[] array) { }); } +/** + * Reads a Set of objects of a specified type from the wire. + * + * @param The type of objects in the Set. + * @param t The Class object representing the type T. + * @return A Set containing objects of type T, or throws InvalidMarshallableException in case of an error. + */ default Set set(Class t) throws InvalidMarshallableException { return collection(LinkedHashSet::new, t); } +/** + * Reads a List of objects of a specified type from the wire. + * + * @param The type of objects in the List. + * @param t The Class object representing the type T. + * @return A List containing objects of type T, or throws InvalidMarshallableException in case of an error. + */ default List list(Class t) throws InvalidMarshallableException { return collection(ArrayList::new, t); } +/** + * Reads a Collection of objects of a specified type from the wire, using the provided supplier for the Collection type. + * + * @param The type of objects in the Collection. + * @param The type of the Collection. + * @param supplier A Supplier providing instances of the Collection type C. + * @param t The Class object representing the type T. + * @return A Collection containing objects of type T, or throws InvalidMarshallableException in case of an error. + */ default > C collection(@NotNull Supplier supplier, Class t) throws InvalidMarshallableException { C list = supplier.get(); sequence(list, t, (s, kls, v) -> { @@ -362,11 +617,29 @@ default > C collection(@NotNull Supplier supplier, return list; } +/** + * Reads a Set of ReadMarshallable objects from the wire, and applies them to a provided object using the function. + * + * @param The type of the object to apply the Set to. + * @param The type of the ReadMarshallable objects. + * @param o The object to apply the Set to. + * @param tSupplier A Function providing instances of type T. + * @return The WireIn instance for method chaining. + */ @NotNull default WireIn set(@NotNull O o, Function tSupplier) throws InvalidMarshallableException { return collection(o, tSupplier); } +/** + * Reads a List of ReadMarshallable objects from the wire, and applies them to a provided object using the function. + * + * @param The type of the object to apply the List to. + * @param The type of the ReadMarshallable objects. + * @param o The object to apply the List to. + * @param tSupplier A Function providing instances of type T. + * @return The WireIn instance for method chaining. + */ @NotNull default WireIn list(@NotNull O o, Function tSupplier) throws InvalidMarshallableException { return collection(o, tSupplier); @@ -383,20 +656,62 @@ default WireIn collection(@NotNull O o, Function return wireIn(); } +/** + * Reads a Map of marshallable key-value pairs as specified by the provided classes. + * + * @param The type of keys in the Map. + * @param The type of values in the Map. + * @param kClass The class of the keys. + * @param vClass The class of the values. + * @return A Map containing the key-value pairs, or null if the Map could not be read. + * @throws InvalidMarshallableException if the key or value types are invalid + */ @Nullable default Map marshallableAsMap(Class kClass, @NotNull Class vClass) throws InvalidMarshallableException { return marshallableAsMap(kClass, vClass, new LinkedHashMap<>()); } +/** + * Reads a Map of marshallable key-value pairs into the provided Map. + * + * @param The type of keys in the Map. + * @param The type of values in the Map. + * @param kClass The class of the keys. + * @param vClass The class of the values. + * @param map The Map to populate with the read key-value pairs. + * @return The provided Map populated with key-value pairs, or null if the Map could not be read. + */ @Nullable default Map marshallableAsMap(Class kClass, @NotNull Class vClass, @NotNull Map map) { return marshallable(m -> m.readAllAsMap(kClass, vClass, map)) ? map : null; } +/** + * Applies a Function to this ValueIn, interpreting it as a WireIn for a marshallable object. + * + * @param The type of the result from the Function. + * @param marshallableReader The Function to apply to this ValueIn. + * @return The result of applying the Function to this ValueIn, or null if it cannot be applied. + */ @Nullable T applyToMarshallable(Function marshallableReader); +/** + * Reads a typed marshallable object from the wire. + * + * @return The marshallable object read from the wire, or null if it cannot be read. + * @throws IORuntimeException if an I/O error occurs + * @throws InvalidMarshallableException if the marshallable object is invalid + */ @Nullable T typedMarshallable() throws IORuntimeException, InvalidMarshallableException; +/** + * Reads a typed marshallable object from the wire, using the provided function to create instances. + * + * @param marshallableFunction The function to create marshallable object instances. + * @return The marshallable object read from the wire, or null if it cannot be read. + * @throws IORuntimeException if an I/O error occurs + * @throws InvalidMarshallableException if the marshallable object is invalid + */ @Nullable default T typedMarshallable(@NotNull Function marshallableFunction) throws IORuntimeException, InvalidMarshallableException { @@ -410,6 +725,14 @@ default T typedMarshallable(@NotNull Function marsh return object(null, aClass); } +/** + * Reads a type prefix and applies it to a given object using the provided BiConsumer. + * + * @param The type of the object to apply the type prefix to. + * @param t The object to apply the type prefix to. + * @param ts The BiConsumer that accepts the object and the type prefix. + * @return The WireIn instance for method chaining. + */ @NotNull ValueIn typePrefix(T t, @NotNull BiConsumer ts); @NotNull WireIn typeLiteralAsText(T t, @NotNull BiConsumer classNameConsumer) @@ -417,6 +740,17 @@ default T typedMarshallable(@NotNull Function marsh ClassLookup classLookup(); + + /** + * Reads a type literal as text and applies it to a given object using the provided BiConsumer. + * + * @param The type of the object to apply the type literal to. + * @param t The object to apply the type literal to. + * @param classNameConsumer The BiConsumer that accepts the object and the type literal. + * @return The WireIn instance for method chaining. + * @throws IORuntimeException if an I/O error occurs + * @throws BufferUnderflowException if the buffer underflows while reading + */ @NotNull default WireIn typeLiteral(T t, @NotNull BiConsumer classConsumer) throws IORuntimeException { return typeLiteralAsText(t, (o, x) -> @@ -424,6 +758,15 @@ default WireIn typeLiteral(T t, @NotNull BiConsumer classConsumer) ); } +/** + * Reads a type literal from the wire, applies it to a given object using the provided BiConsumer, and uses a default Class if necessary. + * + * @param The type of the object to apply the type literal to. + * @param t The object to apply the type literal to. + * @param classConsumer The BiConsumer that accepts the object and the Class derived from the type literal. + * @param defaultClass The default Class to use if the type literal cannot be resolved. + * @return The WireIn instance for method chaining. + */ @NotNull default WireIn typeLiteral(T t, @NotNull BiConsumer classConsumer, Class defaultClass) { return typeLiteralAsText(t, (o, x) -> { @@ -432,40 +775,116 @@ default WireIn typeLiteral(T t, @NotNull BiConsumer classConsumer, }); } +/** + * Reads a marshallable object from the wire and applies a specified SerializationStrategy. + * + * @param object The object to populate with the marshallable data. + * @param strategy The SerializationStrategy to use for reading the marshallable data. + * @return The object populated with marshallable data, or null if it cannot be read. + * @throws BufferUnderflowException if the buffer underflows while reading + * @throws IORuntimeException if an I/O error occurs + * @throws InvalidMarshallableException if the marshallable object is invalid + */ @Nullable Object marshallable(@NotNull Object object, @NotNull SerializationStrategy strategy) throws BufferUnderflowException, IORuntimeException, InvalidMarshallableException; +/** + * Reads a Serializable object from the wire. + * + * @param object The Serializable object to populate with the data. + * @return True if the object was successfully read, false otherwise. + * @throws BufferUnderflowException if the buffer underflows while reading + * @throws IORuntimeException if an I/O error occurs + * @throws InvalidMarshallableException if the Serializable object is invalid + */ default boolean marshallable(@NotNull Serializable object) throws BufferUnderflowException, IORuntimeException, InvalidMarshallableException { return marshallable(object, SerializationStrategies.SERIALIZABLE) != null; } +/** + * Reads a ReadMarshallable object from the wire. + * + * @param object The ReadMarshallable object to populate with the data. + * @return True if the object was successfully read, false otherwise. + * @throws BufferUnderflowException if the buffer underflows while reading + * @throws IORuntimeException if an I/O error occurs + * @throws InvalidMarshallableException if the ReadMarshallable object is invalid + */ default boolean marshallable(@NotNull ReadMarshallable object) throws BufferUnderflowException, IORuntimeException, InvalidMarshallableException { return marshallable(object, SerializationStrategies.MARSHALLABLE) != null; } +/** + * Reads a boolean value from the wire. + * + * @return The boolean value read from the wire. + */ boolean bool(); +/** + * Reads an 8-bit integer (byte) value from the wire. + * + * @return The 8-bit integer value read from the wire. + */ byte int8(); +/** + * Reads a 16-bit integer (short) value from the wire. + * + * @return The 16-bit integer value read from the wire. + */ short int16(); +/** + * Reads an unsigned 16-bit integer (represented as an int) from the wire. + * + * @return The unsigned 16-bit integer value read from the wire. + */ int uint16(); +/** + * Reads a 32-bit integer (int) value from the wire. + * + * @return The 32-bit integer value read from the wire. + */ int int32(); +/** + * Reads a 32-bit integer (int) value from the wire with a previous value as a reference. + * + * @param previous The previous 32-bit integer value. + * @return The 32-bit integer value read from the wire. + */ default int int32(int previous) { return int32(); } +/** + * Reads a 64-bit integer (long) value from the wire. + * + * @return The 64-bit integer value read from the wire. + */ long int64(); +/** + * Reads a 64-bit integer (long) value from the wire with a previous value as a reference. + * + * @param previous The previous 64-bit integer value. + * @return The 64-bit integer value read from the wire. + */ default long int64(long previous) { return int64(); } float float32(); +/** + * Reads a 32-bit floating-point (float) value from the wire with a previous value as a reference. + * + * @param previous The previous 32-bit floating-point value. + * @return The 32-bit floating-point value read from the wire. + */ default float float32(float previous) { return float32(); } @@ -475,10 +894,23 @@ default float float32(float previous) { */ double float64(); +/** + * Reads a 64-bit floating-point (double) value from the wire with a previous value as a reference. + * + * @param previous The previous 64-bit floating-point value. + * @return The 64-bit floating-point value read from the wire. + */ default double float64(double previous) { return float64(); } +/** + * Reads a Class type literal from the wire. + * + * @return The Class corresponding to the type literal read from the wire, or null if it cannot be resolved. + * @throws IORuntimeException if an I/O error occurs + * @throws BufferUnderflowException if the buffer underflows while reading + */ @Nullable default Class typeLiteral() throws IORuntimeException, BufferUnderflowException { return (Class) typeLiteral((sb, e) -> { @@ -486,17 +918,43 @@ default Class typeLiteral() throws IORuntimeException, BufferUnderflowExc }); } +/** + * Reads a type literal from the wire, returning it as a Type object, with a fallback for unresolved types. + * + * @return The Type corresponding to the literal read from the wire, or a fallback unresolved type. + * @throws IORuntimeException if an I/O error occurs + * @throws BufferUnderflowException if the buffer underflows while reading + */ @Nullable default Type lenientTypeLiteral() throws IORuntimeException, BufferUnderflowException { return typeLiteral((sb, e) -> UnresolvedType.of(sb.toString())); } +/** + * Reads a type literal from the wire, applying a handler for unresolved types. + * + * @param unresolvedHandler The handler to apply for unresolved types. + * @return The Type corresponding to the literal read from the wire, or the result of the unresolved handler. + */ Type typeLiteral(BiFunction unresolvedHandler); +/** + * Reads a Throwable from the wire, optionally appending the current stack trace. + * + * @param appendCurrentStack True to append the current stack trace to the Throwable. + * @return The Throwable read from the wire. + * @throws InvalidMarshallableException if the Throwable object is invalid + */ default Throwable throwable(boolean appendCurrentStack) throws InvalidMarshallableException { return WireInternal.throwable(this, appendCurrentStack); } +/** + * Reads an Enum value of the specified type from the wire. + * + * @param eClass The class of the Enum type. + * @return The Enum value read from the wire, or null if it cannot be read. + */ @Nullable default > E asEnum(Class eClass) { try (ScopedResource stlSb = Wires.acquireStringBuilderScoped()) { @@ -506,12 +964,27 @@ default > E asEnum(Class eClass) { } } +/** + * Reads an Enum value of the specified type from the wire and applies it to a Consumer. + * + * @param eClass The class of the Enum type. + * @param eConsumer The Consumer to apply the Enum value to. + * @return The WireIn instance for method chaining. + */ @NotNull default > WireIn asEnum(Class eClass, @NotNull Consumer eConsumer) { eConsumer.accept(asEnum(eClass)); return wireIn(); } +/** + * Reads an Enum value of the specified type from the wire and applies it to a given object using a BiConsumer. + * + * @param eClass The class of the Enum type. + * @param t The object to apply the Enum value to. + * @param teConsumer The BiConsumer that accepts the object and the Enum value. + * @return The WireIn instance for method chaining. + */ @NotNull default , T> WireIn asEnum(Class eClass, T t, @NotNull BiConsumer teConsumer) { teConsumer.accept(t, asEnum(eClass)); @@ -519,14 +992,27 @@ default , T> WireIn asEnum(Class eClass, T t, @NotNull BiCo } /** - * @param clazz Expected object type. {@code null} can be passed to request proxy marshallable tuple - * if {@link Wires#GENERATE_TUPLES} is enabled. + * Reads an object of the specified class from the wire. + * + * @param clazz The class of the object to read. + * @return The object read from the wire, or null if it cannot be read. + * @throws InvalidMarshallableException if the object is invalid */ @Nullable default E object(@Nullable Class clazz) throws InvalidMarshallableException { return Wires.object0(this, null, clazz); } +/** + * Reads an object from the wire. + * + * @param The type of the object to read. + * @param using An instance of the object to reuse, or null to create a new instance. + * @param clazz The class of the object to read. + * @param bestEffort Set to true for best effort reading, which may not throw exceptions for some errors. + * @return The object read from the wire, or null if it cannot be read. + * @throws InvalidMarshallableException if the object is invalid + */ @Nullable default Object object() throws InvalidMarshallableException { @Nullable final Object o = objectWithInferredType(null, SerializationStrategies.ANY_OBJECT, null); @@ -558,24 +1044,56 @@ default E object(@Nullable E using, @Nullable Class clazz, boolean bestEffor return Wires.object0(this, using, clazz, bestEffort); } +/** + * Gets the bracket type for the current value in the wire. + * + * @return The BracketType of the current value. + */ @NotNull BracketType getBracketType(); +/** + * Checks if the current value in the wire is null. + * + * @return True if the current value is null, false otherwise. + */ boolean isNull(); +/** + * Reads an object of a specified class from the wire and applies it to a given object using a BiConsumer. + * + * @param The type of the object to apply the read value to. + * @param The type of the object being read. + * @param clazz The class of the object being read. + * @param t The object to apply the read value to. + * @param e The BiConsumer that accepts the object and the read value. + * @return The WireIn instance for method chaining. + * @throws InvalidMarshallableException if the object is invalid + */ @Nullable default WireIn object(@NotNull Class clazz, T t, @NotNull BiConsumer e) throws InvalidMarshallableException { e.accept(t, object(clazz)); return wireIn(); } +/** + * Checks if the current value in the wire is typed. + * + * @return True if the current value is typed, false otherwise. + */ boolean isTyped(); +/** + * Reads the type prefix from the wire. + * + * @return The type prefix as a Class, or null if it cannot be read. + */ @Nullable Class typePrefix(); /** * read a class with a super class or actual class as a hint + * * @param tClass the super-class, or actual class to use * @return the class or an instance of an object to use. * @throws ClassNotFoundRuntimeException if the specific class couldn't be found. @@ -585,8 +1103,20 @@ default Object typePrefixOrObject(Class tClass) throws ClassNotFoundRuntimeExcep return typePrefix(); } +/** + * Resets the internal state of this ValueIn. + */ void resetState(); +/** + * Reads an object from the wire with an inferred type. + * + * @param using An instance of the object to reuse, or null to create a new instance. + * @param strategy The SerializationStrategy to use for reading the object. + * @param type The type of the object to read. + * @return The object read from the wire, or null if it cannot be read. + * @throws InvalidMarshallableException if the object is invalid + */ @Nullable Object objectWithInferredType(Object using, SerializationStrategy strategy, Class type) throws InvalidMarshallableException; @@ -599,15 +1129,31 @@ default boolean isPresent() { return true; } +/** + * Reads a UUID from the wire. + * + * @return The UUID read from the wire, or null if it cannot be read. + */ @NotNull default UUID uuid() { return UUID.fromString(text()); } +/** + * Checks if the current value in the wire is binary. + * + * @return True if the current value is binary, false otherwise. + */ default boolean isBinary() { return false; } +/** + * Reads a long value from the wire using a LongConverter. + * + * @param longConverter The LongConverter to use for reading the long value. + * @return The long value read from the wire. + */ default long readLong(LongConverter longConverter) { try (ScopedResource stlSb = Wires.acquireStringBuilderScoped()) { StringBuilder sb = stlSb.get(); @@ -616,42 +1162,90 @@ default long readLong(LongConverter longConverter) { } } +/** + * Reads a boolean value from the wire. + * + * @return The boolean value read from the wire. + */ default boolean readBoolean() { return bool(); } +/** + * Reads a byte value from the wire. + * + * @return The byte value read from the wire. + */ default byte readByte() { return int8(); } +/** + * Reads a char value from the wire. + * + * @return The char value read from the wire. + */ default char readChar() { return (char) uint16(); } +/** + * Reads a short value from the wire. + * + * @return The short value read from the wire. + */ default short readShort() { return int16(); } +/** + * Reads an int value from the wire. + * + * @return The int value read from the wire. + */ default int readInt() { return int32(); } +/** + * Reads a long value from the wire. + * + * @return The long value read from the wire. + */ default long readLong() { return int64(); } +/** + * Reads a float value from the wire. + * + * @return The float value read from the wire. + */ default float readFloat() { return float32(); } +/** + * Reads a double value from the wire. + * + * @return The double value read from the wire. + */ default double readDouble() { return float64(); } +/** + * Reads a String from the wire. + * + * @return The String read from the wire, or null if it cannot be read. + */ default String readString() { return text(); } +/** + * Interface for reading values from the wire into a list. + */ interface Reader { void accept(ValueIn valueIn, List list, List buffer, Supplier bufferAdd) throws InvalidMarshallableException; }