From 35f7a20b22271f8f28d15da8df85cff2fc9cd716 Mon Sep 17 00:00:00 2001 From: Matthias Andreas Benkard Date: Tue, 14 Dec 2021 19:29:26 +0100 Subject: Simplify types, replace Value with Variant. Change-Id: I2e492ebfefc7e9a47c874ed22ff199412e9948ee --- src/main/java/eu/mulk/jgvariant/core/Decoder.java | 108 +++++++++----------- src/main/java/eu/mulk/jgvariant/core/Value.java | 112 --------------------- src/main/java/eu/mulk/jgvariant/core/Variant.java | 102 +++++++++++++++++++ .../java/eu/mulk/jgvariant/core/package-info.java | 20 ++-- src/main/java/module-info.java | 6 +- 5 files changed, 164 insertions(+), 184 deletions(-) delete mode 100644 src/main/java/eu/mulk/jgvariant/core/Value.java create mode 100644 src/main/java/eu/mulk/jgvariant/core/Variant.java (limited to 'src/main/java') diff --git a/src/main/java/eu/mulk/jgvariant/core/Decoder.java b/src/main/java/eu/mulk/jgvariant/core/Decoder.java index c51a723..8134d45 100644 --- a/src/main/java/eu/mulk/jgvariant/core/Decoder.java +++ b/src/main/java/eu/mulk/jgvariant/core/Decoder.java @@ -2,17 +2,6 @@ package eu.mulk.jgvariant.core; import static java.nio.ByteOrder.LITTLE_ENDIAN; -import eu.mulk.jgvariant.core.Value.Array; -import eu.mulk.jgvariant.core.Value.Bool; -import eu.mulk.jgvariant.core.Value.Float64; -import eu.mulk.jgvariant.core.Value.Int16; -import eu.mulk.jgvariant.core.Value.Int32; -import eu.mulk.jgvariant.core.Value.Int64; -import eu.mulk.jgvariant.core.Value.Int8; -import eu.mulk.jgvariant.core.Value.Maybe; -import eu.mulk.jgvariant.core.Value.Str; -import eu.mulk.jgvariant.core.Value.Structure; -import eu.mulk.jgvariant.core.Value.Variant; import java.lang.reflect.InvocationTargetException; import java.lang.reflect.RecordComponent; import java.nio.ByteBuffer; @@ -25,7 +14,7 @@ import java.util.Optional; import org.jetbrains.annotations.Nullable; /** - * Type class for decodable {@link Value} types. + * Type class for decodable {@link Variant} types. * *

Use the {@code of*} family of constructor methods to acquire a suitable {@link Decoder} for * the type you wish to decode. @@ -36,23 +25,23 @@ import org.jetbrains.annotations.Nullable; * {@code int}, you can use the following code: * * 

{@code
- * record ExampleRecord(Value.Str s, Value.Int32 i) {}
+ * record ExampleRecord(String s, int i) {}
  *
  * var decoder =
  *   Decoder.ofArray(
  *     Decoder.ofStructure(
  *       ExampleRecord.class,
- *       Decoder.ofStr(UTF_8),
- *       Decoder.ofInt32().withByteOrder(LITTLE_ENDIAN)));
+ *       Decoder.ofString(UTF_8),
+ *       Decoder.ofInt().withByteOrder(LITTLE_ENDIAN)));
  *
  * byte[] bytes = ...;
- * Value.Array> example = decoder.decode(ByteBuffer.wrap(bytes));
+ * List example = decoder.decode(ByteBuffer.wrap(bytes));
  * }
* * @param the type that the {@link Decoder} can decode. */ @SuppressWarnings("java:S1610") -public abstract class Decoder { +public abstract class Decoder { private Decoder() {} @@ -100,13 +89,13 @@ public abstract class Decoder { } /** - * Creates a {@link Decoder} for an {@link Array} type. + * Creates a {@link Decoder} for an {@code Array} type. * * @param elementDecoder a {@link Decoder} for the elements of the array. * @param the element type. * @return a new {@link Decoder}. */ - public static Decoder> ofArray(Decoder elementDecoder) { + public static Decoder> ofArray(Decoder elementDecoder) { return new Decoder<>() { @Override public byte alignment() { @@ -120,7 +109,7 @@ public abstract class Decoder { } @Override - public Array decode(ByteBuffer byteSlice) { + public List decode(ByteBuffer byteSlice) { List elements; var elementSize = elementDecoder.fixedSize(); @@ -150,7 +139,7 @@ public abstract class Decoder { } } - return new Array<>(elements); + return elements; } }; } @@ -171,13 +160,13 @@ public abstract class Decoder { } /** - * Creates a {@link Decoder} for a {@link Maybe} type. + * Creates a {@link Decoder} for a {@code Maybe} type. * * @param elementDecoder a {@link Decoder} for the contained element. * @param the element type. * @return a new {@link Decoder}. */ - public static Decoder> ofMaybe(Decoder elementDecoder) { + public static Decoder> ofMaybe(Decoder elementDecoder) { return new Decoder<>() { @Override public byte alignment() { @@ -191,32 +180,31 @@ public abstract class Decoder { } @Override - public Maybe decode(ByteBuffer byteSlice) { + public Optional decode(ByteBuffer byteSlice) { if (!byteSlice.hasRemaining()) { - return new Maybe<>(Optional.empty()); + return Optional.empty(); } else { if (!elementDecoder.hasFixedSize()) { // Remove trailing zero byte. byteSlice.limit(byteSlice.limit() - 1); } - return new Maybe<>(Optional.of(elementDecoder.decode(byteSlice))); + return Optional.of(elementDecoder.decode(byteSlice)); } } }; } /** - * Creates a {@link Decoder} for a {@link Structure} type. + * Creates a {@link Decoder} for a {@code Structure} type. * * @param recordType the {@link Record} type that represents the components of the structure. * @param componentDecoders a {@link Decoder} for each component of the structure. * @param the {@link Record} type that represents the components of the structure. * @return a new {@link Decoder}. */ - @SafeVarargs - public static Decoder> ofStructure( - Class recordType, Decoder... componentDecoders) { + public static Decoder ofStructure( + Class recordType, Decoder... componentDecoders) { var recordComponents = recordType.getRecordComponents(); if (componentDecoders.length != recordComponents.length) { throw new IllegalArgumentException( @@ -251,7 +239,7 @@ public abstract class Decoder { } @Override - public Structure decode(ByteBuffer byteSlice) { + public U decode(ByteBuffer byteSlice) { int framingOffsetSize = byteCount(byteSlice.limit()); var recordConstructorArguments = new Object[recordComponents.length]; @@ -296,7 +284,7 @@ public abstract class Decoder { .map(RecordComponent::getType) .toArray(Class[]::new); var recordConstructor = recordType.getDeclaredConstructor(recordComponentTypes); - return new Structure<>(recordConstructor.newInstance(recordConstructorArguments)); + return recordConstructor.newInstance(recordConstructorArguments); } catch (NoSuchMethodException | InstantiationException | IllegalAccessException @@ -334,11 +322,11 @@ public abstract class Decoder { } /** - * Creates a {@link Decoder} for the {@link Bool} type. + * Creates a {@link Decoder} for the {@code Boolean} type. * * @return a new {@link Decoder}. */ - public static Decoder ofBool() { + public static Decoder ofBoolean() { return new Decoder<>() { @Override public byte alignment() { @@ -351,21 +339,21 @@ public abstract class Decoder { } @Override - public Bool decode(ByteBuffer byteSlice) { - return new Bool(byteSlice.get() != 0); + public Boolean decode(ByteBuffer byteSlice) { + return byteSlice.get() != 0; } }; } /** - * Creates a {@link Decoder} for the {@link Int8} type. + * Creates a {@link Decoder} for the 8-bit {@ode byte} type. * *

Note: It is often useful to apply {@link #withByteOrder(ByteOrder)} to the * result of this method. * * @return a new {@link Decoder}. */ - public static Decoder ofInt8() { + public static Decoder ofByte() { return new Decoder<>() { @Override public byte alignment() { @@ -378,21 +366,21 @@ public abstract class Decoder { } @Override - public Int8 decode(ByteBuffer byteSlice) { - return new Int8(byteSlice.get()); + public Byte decode(ByteBuffer byteSlice) { + return byteSlice.get(); } }; } /** - * Creates a {@link Decoder} for the {@link Int16} type. + * Creates a {@link Decoder} for the 16-bit {@code short} type. * *

Note: It is often useful to apply {@link #withByteOrder(ByteOrder)} to the * result of this method. * * @return a new {@link Decoder}. */ - public static Decoder ofInt16() { + public static Decoder ofShort() { return new Decoder<>() { @Override public byte alignment() { @@ -405,21 +393,21 @@ public abstract class Decoder { } @Override - public Int16 decode(ByteBuffer byteSlice) { - return new Int16(byteSlice.getShort()); + public Short decode(ByteBuffer byteSlice) { + return byteSlice.getShort(); } }; } /** - * Creates a {@link Decoder} for the {@link Int32} type. + * Creates a {@link Decoder} for the 32-bit {@code int} type. * *

Note: It is often useful to apply {@link #withByteOrder(ByteOrder)} to the * result of this method. * * @return a new {@link Decoder}. */ - public static Decoder ofInt32() { + public static Decoder ofInt() { return new Decoder<>() { @Override public byte alignment() { @@ -432,21 +420,21 @@ public abstract class Decoder { } @Override - public Int32 decode(ByteBuffer byteSlice) { - return new Int32(byteSlice.getInt()); + public Integer decode(ByteBuffer byteSlice) { + return byteSlice.getInt(); } }; } /** - * Creates a {@link Decoder} for the {@link Int64} type. + * Creates a {@link Decoder} for the 64-bit {@code long} type. * *

Note: It is often useful to apply {@link #withByteOrder(ByteOrder)} to the * result of this method. * * @return a new {@link Decoder}. */ - public static Decoder ofInt64() { + public static Decoder ofLong() { return new Decoder<>() { @Override public byte alignment() { @@ -459,18 +447,18 @@ public abstract class Decoder { } @Override - public Int64 decode(ByteBuffer byteSlice) { - return new Int64(byteSlice.getLong()); + public Long decode(ByteBuffer byteSlice) { + return byteSlice.getLong(); } }; } /** - * Creates a {@link Decoder} for the {@link Float64} type. + * Creates a {@link Decoder} for the {@code double} type. * * @return a new {@link Decoder}. */ - public static Decoder ofFloat64() { + public static Decoder ofDouble() { return new Decoder<>() { @Override public byte alignment() { @@ -483,21 +471,21 @@ public abstract class Decoder { } @Override - public Float64 decode(ByteBuffer byteSlice) { - return new Float64(byteSlice.getDouble()); + public Double decode(ByteBuffer byteSlice) { + return byteSlice.getDouble(); } }; } /** - * Creates a {@link Decoder} for the {@link Str} type. + * Creates a {@link Decoder} for the {@link String} type. * *

Note: While GVariant does not prescribe any particular encoding, {@link * java.nio.charset.StandardCharsets#UTF_8} is the most common choice. * * @return a new {@link Decoder}. */ - public static Decoder ofStr(Charset charset) { + public static Decoder ofString(Charset charset) { return new Decoder<>() { @Override public byte alignment() { @@ -511,9 +499,9 @@ public abstract class Decoder { } @Override - public Str decode(ByteBuffer byteSlice) { + public String decode(ByteBuffer byteSlice) { byteSlice.limit(byteSlice.limit() - 1); - return new Str(charset.decode(byteSlice).toString()); + return charset.decode(byteSlice).toString(); } }; } diff --git a/src/main/java/eu/mulk/jgvariant/core/Value.java b/src/main/java/eu/mulk/jgvariant/core/Value.java deleted file mode 100644 index 54c0b79..0000000 --- a/src/main/java/eu/mulk/jgvariant/core/Value.java +++ /dev/null @@ -1,112 +0,0 @@ -package eu.mulk.jgvariant.core; - -import java.util.List; -import java.util.Optional; - -/** - * A value representable by the GVariant - * serialization format. - * - *

{@link Value} is a sum type (sealed interface) that represents a GVariant value. Its subtypes - * represent the different types of values that GVariant supports. - * - * @see Decoder - */ -public sealed interface Value { - - /** - * A homogeneous sequence of GVariant values. - * - *

Arrays of fixed width (i.e. of values of fixed size) are represented in a similar way to - * plain C arrays. Arrays of variable width require additional space for padding and framing. - * - *

Heterogeneous sequences are represented by {@code Array}. - * - * @param the type of the elements of the array. - * @see Decoder#ofArray - */ - record Array(List values) implements Value {} - - /** - * A value that is either present or absent. - * - * @param the contained type. - * @see Decoder#ofMaybe - */ - record Maybe(Optional value) implements Value {} - - /** - * A tuple of values of fixed types. - * - *

GVariant structures are represented as {@link Record} types. For example, a two-element - * structure consisting of a string and an int can be modelled as follows: - * - * 

{@code
-   * record TestRecord(Str s, Int32 i) {}
-   * var testStruct = new Structure<>(new TestRecord(new Str("hello"), new Int32(123));
-   * }
- * - * @param the {@link Record} type that represents the components of the structure. - * @see Decoder#ofStructure - */ - record Structure(T values) implements Value {} - - /** - * A dynamically typed box that can hold a single value of any GVariant type. - * - * @see Decoder#ofVariant - */ - record Variant(Class type, Value value) implements Value {} - - /** - * Either true or false. - * - * @see Decoder#ofBool() - */ - record Bool(boolean value) implements Value { - static Bool TRUE = new Bool(true); - static Bool FALSE = new Bool(false); - } - - /** - * A {@code byte}-sized integer. - * - * @see Decoder#ofInt8() - */ - record Int8(byte value) implements Value {} - - /** - * A {@code short}-sized integer. - * - * @see Decoder#ofInt16() - */ - record Int16(short value) implements Value {} - - /** - * An {@code int}-sized integer. - * - * @see Decoder#ofInt32() - */ - record Int32(int value) implements Value {} - - /** - * A {@code long}-sized integer. - * - * @see Decoder#ofInt64() - */ - record Int64(long value) implements Value {} - - /** - * A double-precision floating point number. - * - * @see Decoder#ofFloat64() - */ - record Float64(double value) implements Value {} - - /** - * A character string. - * - * @see Decoder#ofStr - */ - record Str(String value) implements Value {} -} diff --git a/src/main/java/eu/mulk/jgvariant/core/Variant.java b/src/main/java/eu/mulk/jgvariant/core/Variant.java new file mode 100644 index 0000000..05e28d5 --- /dev/null +++ b/src/main/java/eu/mulk/jgvariant/core/Variant.java @@ -0,0 +1,102 @@ +package eu.mulk.jgvariant.core; + +import java.util.List; +import java.util.Optional; + +/** + * A value representable by the GVariant + * serialization format, tagged with its type. + * + *

{@link Variant} is a sum type (sealed interface) that represents a GVariant value. Its + * subtypes represent the different types of values that GVariant supports. + * + * @see Decoder#ofVariant() + */ +public sealed interface Variant { + + /** + * A homogeneous sequence of GVariant values. + * + *

Arrays of fixed width (i.e. of values of fixed size) are represented in a similar way to + * plain C arrays. Arrays of variable width require additional space for padding and framing. + * + *

Heterogeneous sequences are represented by {@code Array}. + * + * @param the type of the elements of the array. + * @see Decoder#ofArray + */ + record Array(List values) implements Variant {} + + /** + * A value that is either present or absent. + * + * @param the contained type. + * @see Decoder#ofMaybe + */ + record Maybe(Optional value) implements Variant {} + + /** + * A tuple of values of fixed types. + * + *

GVariant structures are represented as {@link Record} types. For example, a two-element + * structure consisting of a string and an int can be modelled as follows: + * + * 

{@code
+   * record TestRecord(String s, int i) {}
+   * var testStruct = new Structure<>(new TestRecord("hello", 123);
+   * }
+ * + * @param the {@link Record} type that represents the components of the structure. + * @see Decoder#ofStructure + */ + record Structure(T values) implements Variant {} + + /** + * Either true or false. + * + * @see Decoder#ofBoolean() + */ + record Bool(boolean value) implements Variant {} + + /** + * A {@code byte}-sized integer. + * + * @see Decoder#ofByte() + */ + record Byte(byte value) implements Variant {} + + /** + * A {@code short}-sized integer. + * + * @see Decoder#ofShort() + */ + record Short(short value) implements Variant {} + + /** + * An {@code int}-sized integer. + * + * @see Decoder#ofInt() + */ + record Int(int value) implements Variant {} + + /** + * A {@code long}-sized integer. + * + * @see Decoder#ofLong() + */ + record Long(long value) implements Variant {} + + /** + * A double-precision floating point number. + * + * @see Decoder#ofDouble() + */ + record Double(double value) implements Variant {} + + /** + * A character string. + * + * @see Decoder#ofString + */ + record String(java.lang.String value) implements Variant {} +} diff --git a/src/main/java/eu/mulk/jgvariant/core/package-info.java b/src/main/java/eu/mulk/jgvariant/core/package-info.java index dba7a09..1b819c5 100644 --- a/src/main/java/eu/mulk/jgvariant/core/package-info.java +++ b/src/main/java/eu/mulk/jgvariant/core/package-info.java @@ -1,32 +1,32 @@ /** - * Provides {@link eu.mulk.jgvariant.core.Value} and {@link eu.mulk.jgvariant.core.Decoder}, the + * Provides {@link eu.mulk.jgvariant.core.Variant} and {@link eu.mulk.jgvariant.core.Decoder}, the * foundational classes for GVariant * parsing. * - *

{@link eu.mulk.jgvariant.core.Value} is a sum type (sealed interface) that represents a + *

{@link eu.mulk.jgvariant.core.Variant} is a sum type (sealed interface) that represents a * GVariant value. Its subtypes represent the different types of values that GVariant supports. * *

Instances of {@link eu.mulk.jgvariant.core.Decoder} read a given concrete subtype of {@link - * eu.mulk.jgvariant.core.Value} from a {@link java.nio.ByteBuffer}. The class also contains factory - * methods to create those instances. + * eu.mulk.jgvariant.core.Variant} from a {@link java.nio.ByteBuffer}. The class also contains + * factory methods to create those instances. * *

Example * - *

To parse a GVariant of type {@code "a(si)"}, which is an array of pairs of {@link String} and - * {@code int}, you can use the following code: + *

To parse a GVariant of type {@code "a(si)"}, which is an array of pairs of {@link + * java.lang.String} and {@code int}, you can use the following code: * * 

{@code
- * record ExampleRecord(Value.Str s, Value.Int32 i) {}
+ * record ExampleRecord(String s, int i) {}
  *
  * var decoder =
  *   Decoder.ofArray(
  *     Decoder.ofStructure(
  *       ExampleRecord.class,
- *       Decoder.ofStr(UTF_8),
- *       Decoder.ofInt32().withByteOrder(LITTLE_ENDIAN)));
+ *       Decoder.ofString(UTF_8),
+ *       Decoder.ofInt().withByteOrder(LITTLE_ENDIAN)));
  *
  * byte[] bytes = ...;
- * Value.Array> example = decoder.decode(ByteBuffer.wrap(bytes));
+ * List example = decoder.decode(ByteBuffer.wrap(bytes));
  * }
*/ package eu.mulk.jgvariant.core; diff --git a/src/main/java/module-info.java b/src/main/java/module-info.java index 403cf1f..af28413 100644 --- a/src/main/java/module-info.java +++ b/src/main/java/module-info.java @@ -1,9 +1,11 @@ +import eu.mulk.jgvariant.core.Variant; + /** * Provides a parser for the GVariant * serialization format. * - *

The {@link eu.mulk.jgvariant.core} package contains the {@link eu.mulk.jgvariant.core.Value} - * and {@link eu.mulk.jgvariant.core.Decoder} types. which form the foundation of this library. + *

The {@link eu.mulk.jgvariant.core} package contains the {@link Variant} and {@link + * eu.mulk.jgvariant.core.Decoder} types. which form the foundation of this library. */ module eu.mulk.jgvariant.core { requires com.google.errorprone.annotations; -- cgit v1.2.3