URI empty: ProtoIO + docz

common/common/src/main/java/dev/enola/common/io/resource/EmptyResource.java

@@ -21,29 +21,40 @@
 import com.google.common.io.CharSource;
 import com.google.common.net.MediaType;
 
+import dev.enola.common.io.mediatype.MediaTypes;
+
 import java.net.URI;
 
-class EmptyResource implements ReadableResource {
+public class EmptyResource implements ReadableResource {
     // TODO Perhaps rename this to VoidResource with void:/ URI?
 
-    static final EmptyResource INSTANCE = new EmptyResource();
-
     static final String SCHEME = "empty";
 
-    private static final URI EMPTY_URI = URI.create("empty:-");
+    private final MediaType mediaType;
 
-    private static final MediaType MEDIA_TYPE = MediaType.OCTET_STREAM;
+    private final URI uri;
+
+    public EmptyResource(MediaType mediaType) {
+        this.mediaType = mediaType;
+        this.uri = uri(this.mediaType);
+    }
 
-    private EmptyResource() {}
+    public EmptyResource(String mediaType) {
+        this(MediaTypes.parse(mediaType));
+    }
+
+    public static URI uri(MediaType mediaType) {
+        return URI.create(SCHEME + ":" + mediaType.withoutParameters());
+    }
 
     @Override
     public URI uri() {
-        return EMPTY_URI;
+        return uri;
     }
 
     @Override
     public MediaType mediaType() {
-        return MEDIA_TYPE;
+        return mediaType;
     }
 
     @Override
@@ -58,6 +69,6 @@ public CharSource charSource() {
 
     @Override
     public String toString() {
-        return "EmptyResource{uri=" + uri() + '}';
+        return "EmptyResource{uri=" + uri() + ", mediaType=" + mediaType + "}";
     }
 }

common/common/src/main/java/dev/enola/common/io/resource/ResourceProviders.java

@@ -51,7 +51,8 @@ public Resource getResource(URI uri) {
             return new ReadableButNotWritableResource(
                     new StringResource(uri.getSchemeSpecificPart()));
         } else if (scheme.startsWith(EmptyResource.SCHEME)) {
-            return new ReadableButNotWritableResource(EmptyResource.INSTANCE);
+            return new ReadableButNotWritableResource(
+                    new EmptyResource(uri.getSchemeSpecificPart()));
         } else if (scheme.startsWith(NullResource.SCHEME)) {
             return NullResource.INSTANCE;
         } else if (scheme.startsWith(ErrorResource.SCHEME)) {

common/common/src/main/java/dev/enola/common/io/resource/StringResource.java

@@ -48,7 +48,7 @@ public StringResource(String text, MediaType mediaType) {
             if (!text.isEmpty()) {
                 this.uri = new URI(SCHEME, string, null);
             } else {
-                this.uri = EmptyResource.INSTANCE.uri();
+                this.uri = EmptyResource.uri(mediaType);
             }
 
         } catch (URISyntaxException e) {

common/common/src/test/java/dev/enola/common/io/resource/EmptyResourceTest.java

@@ -19,17 +19,19 @@
 
 import static com.google.common.truth.Truth.assertThat;
 
+import dev.enola.common.io.mediatype.YamlMediaType;
+
 import org.junit.Test;
 
 import java.io.IOException;
 
 public class EmptyResourceTest {
     @Test
     public void testEmptyResource() throws IOException {
-        var e = EmptyResource.INSTANCE;
+        var e = new EmptyResource(YamlMediaType.YAML_UTF_8.toString());
         assertThat(e.byteSource().isEmpty()).isTrue();
         assertThat(e.charSource().isEmpty()).isTrue();
-        assertThat(e.mediaType()).isNotNull();
-        assertThat(e.uri()).isNotNull();
+        assertThat(e.mediaType()).isEqualTo(YamlMediaType.YAML_UTF_8);
+        assertThat(e.uri().toString()).isEqualTo("empty:application/yaml");
     }
 }

common/protobuf/src/main/java/dev/enola/common/protobuf/ProtoIO.java

@@ -74,6 +74,16 @@ public static void check(String pathToResourceOnClasspath, Message.Builder build
         new ProtoIO().read(resource, builder);
     }
 
+    private static boolean isEmpty(Reader reader) throws IOException {
+        if (!reader.markSupported()) {
+            throw new IllegalArgumentException("Reader !markSupported()");
+        }
+        reader.mark(3);
+        var first = reader.read();
+        reader.reset();
+        return first == -1;
+    }
+
     public void write(Message message, WritableResource resource) throws IOException {
         MediaType mediaType = resource.mediaType();
         if (ProtobufMediaTypes.PROTOBUF_BINARY.equals(mediaType)) {
@@ -121,15 +131,20 @@ public <B extends Message.Builder> B read(ReadableResource resource, B builder)
                 builder.mergeFrom(is, extensionRegistry);
             }
         } else {
+            // TODO Use resource.mediaType().charset().or(UTF_8)
             try (Reader reader = resource.charSource(UTF_8).openBufferedStream()) {
                 if (normalizedNoParamsEquals(mediaType, PROTOBUF_TEXTPROTO_UTF_8)) {
                     textFormatParser.merge(reader, extensionRegistry, builder);
                 } else if (normalizedNoParamsEquals(mediaType, PROTOBUF_JSON_UTF_8, JSON_UTF_8)) {
-                    JsonFormat.parser().usingTypeRegistry(typeRegistry).merge(reader, builder);
+                    if (!isEmpty(reader)) {
+                        JsonFormat.parser().usingTypeRegistry(typeRegistry).merge(reader, builder);
+                    }
                 } else if (normalizedNoParamsEquals(mediaType, PROTOBUF_YAML_UTF_8, YAML_UTF_8)) {
                     var yaml = resource.charSource(UTF_8).read();
                     var json = YamlJson.yamlToJson(yaml);
-                    JsonFormat.parser().usingTypeRegistry(typeRegistry).merge(json, builder);
+                    if (!json.isEmpty()) {
+                        JsonFormat.parser().usingTypeRegistry(typeRegistry).merge(json, builder);
+                    }
                 } else {
                     throw new IllegalArgumentException(
                             mediaType + " unknown mediaType for URI: " + resource);

common/protobuf/src/test/java/dev/enola/common/protobuf/ProtoIOTest.java

@@ -27,7 +27,9 @@
 import com.google.protobuf.TypeRegistry;
 
 import dev.enola.common.io.resource.ClasspathResource;
+import dev.enola.common.io.resource.EmptyResource;
 import dev.enola.common.io.resource.MemoryResource;
+import dev.enola.common.io.resource.ReadableResource;
 
 import org.junit.Test;
 
@@ -42,15 +44,37 @@ public ProtoIOTest() {
         super("ok.textproto", Timestamp.newBuilder());
     }
 
+    private Timestamp readTimestamp(ReadableResource resource) throws IOException {
+        return new ProtoIO().read(resource, Timestamp.newBuilder(), Timestamp.class);
+    }
+
     @Test
     public void readGoodTextproto() throws IOException {
-        Timestamp timestamp =
-                new ProtoIO()
-                        .read(
-                                new ClasspathResource("ok.textproto"),
-                                Timestamp.newBuilder(),
-                                Timestamp.class);
-        assertThat(timestamp).isEqualTo(TIMESTAMP);
+        assertThat(readTimestamp(new ClasspathResource("ok.textproto"))).isEqualTo(TIMESTAMP);
+    }
+
+    @Test
+    public void readEmptyBinary() throws IOException {
+        var r = new EmptyResource(ProtobufMediaTypes.PROTOBUF_BINARY);
+        assertThat(readTimestamp(r)).isEqualTo(Timestamp.getDefaultInstance());
+    }
+
+    @Test
+    public void readEmptyTextproto() throws IOException {
+        var r = new EmptyResource(ProtobufMediaTypes.PROTOBUF_TEXTPROTO_UTF_8);
+        assertThat(readTimestamp(r)).isEqualTo(Timestamp.getDefaultInstance());
+    }
+
+    @Test
+    public void readEmptyJSON() throws IOException {
+        var r = new EmptyResource(ProtobufMediaTypes.PROTOBUF_JSON_UTF_8);
+        assertThat(readTimestamp(r)).isEqualTo(Timestamp.getDefaultInstance());
+    }
+
+    @Test
+    public void readEmptyYAML() throws IOException {
+        var r = new EmptyResource(ProtobufMediaTypes.PROTOBUF_YAML_UTF_8);
+        assertThat(readTimestamp(r)).isEqualTo(Timestamp.getDefaultInstance());
     }
 
     @Test

docs/use/get/index.md

@@ -24,7 +24,7 @@
 
 ![Demo](script.svg)
 
-## Enola Get
+## Get Book
 
 Get a `book` - note how the _related_ `kind` and `library` ID are set, based on the template
 [from the model](../library/index.md):

docs/use/help/index.md

@@ -53,6 +53,8 @@ $ ./enola get --help
 
 ## List
 
+[List Entities](../list/index.md) has the following options:
+
 ```bash $? cd .././.././..
 $ ./enola list --help
 ...

docs/use/library/index.md

@@ -27,18 +27,3 @@ Different formats are supported, and can be converted using [Rosetta](../rosetta
 ```yaml
 {% include "model.yaml" %}
 ```
-
-## List Kinds
-
-Because Entity Kinds are Entities themselves, you can also list them like this, with details:
-
-```bash cd .././.././..
-$ ./enola list --model file:docs/use/library/model.yaml --format=yaml enola.entity_kind
-...
-```
-
-In order to get a list of only the names of Entity Kinds, use e.g. [`yq`](https://github.com/mikefarah/yq).
-
-## Screencast (Asciinema)
-
-![Demo](script.svg)

docs/use/list/index.md

@@ -0,0 +1,58 @@
+<!--
+    SPDX-License-Identifier: Apache-2.0
+
+    Copyright 2023 The Enola <https://enola.dev> 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.
+-->
+
+# List Entities
+
+`enola list` will retrieve a list of _entities_ from [connectors](../connector/index.md).
+
+<!--
+
+    THIS DOESN'T ACTUALLY WORK - BECAUSE model.yaml HAS NO CONNECTORS WHICH LIST ANYTHING!
+
+## List Books
+
+```bash cd .././.././..
+$ ./enola list --model file:docs/use/library/model.yaml demo.book
+...
+```
+-->
+
+## List Kinds
+
+Because Entity Kinds are Entities themselves, you can also list them like this, with details:
+
+```bash cd .././.././..
+$ ./enola list --model file:docs/use/library/model.yaml --format=yaml enola.entity_kind
+...
+```
+
+## List Built-In Kinds
+
+Note how the section above showed some additional entity kinds, in addition to those from the example.
+It's possible to list only those built-in entity kinds, using an "empty" model URI, like this:
+
+```bash cd .././.././..
+$ ./enola list --model empty:application/json enola.entity_kind
+...
+```
+
+To get a list of only the names of Entity Kinds, just use e.g. [`yq`](https://github.com/mikefarah/yq).
+
+## Screencast (Asciinema)
+
+![Demo](script.svg)

mkdocs.yaml

@@ -31,8 +31,8 @@ nav:
       - Help: use/help/index.md
       - Example Model: use/library/index.md
       - DocGen: use/docgen/index.md
-      # - List Entites:
       - Get Entity: use/get/index.md
+      - List Entities: use/list/index.md
       - Connectors: use/connector/index.md
       - Server: use/server/index.md
       - Rosetta: use/rosetta/index.md