[YANGTOOLS-1341] Rework yang-repo-api in terms of java.nio

Relates — Thu, 18 Jan 2024 10:42:40 +0000

we have a very much free-standing yang-repo-api, which has a weird placement between being user-facing and internal.

This is centered around SchemaSourceRepresentation:

@Beta
public interface SchemaSourceRepresentation extends Identifiable<SourceIdentifier>, Immutable {
    @Override
    SourceIdentifier getIdentifier();
    /**
     * Return the concrete representation type.
     *
     * @return The type of representation.
     */
    @NonNull Class<? extends SchemaSourceRepresentation> getType();
    /**
     * Return the symbolic name, if available. This name has no semantic meaning beyond being useful for debugging
     * by humans.
     *
     * @return Symbolic name, if available
     */
    Optional<String> getSymbolicName();
}

which is a type-safe baseline for things like YangTextFileSchemaSource, which little more than a ByteSource, i.e. an API-enriched Supplier<InputStream>. What it has is some additional metadata related to import/include statement handling, so that these can be cross-related. Most of the metadata is static, some is actually validated against the actual content.

That metadata is encapsulated in SourceIdentifier, which is an internable concepts.Identifier composed of a String name and an optional Revision. There is a SemVer version which adds an optional concepts.SemVer, which is our try at versions based on OpenConfig.

Reactor side of SemVer is scary, but I think the logic could use some amount of decoupling before we decide what to do with it.

Now we are typically already interfacing java.nio, for example YangTextFileSchemaSource actually does:

    @Override
    public InputStream openStream() throws IOException {
        return Files.newInputStream(file.toPath());
    }

So at the very least it would be nice if we started talking java.nio.file.Path instead of java.io.File() – hence ~~YANGTOOLS-1342~~.

Now if we look at other YangTextFileSchemaSource implementations, these are just a number of variations on how the input stream is supplied and perhaps passing some more information from the upper layer. There is a provision to supply that content potentially lazily, which really all about connecting to a Path (or a URI) and retrieving the stream there.

So now we have something which is a java.nio.file.Path implementation providing metadata and binary content – which fits exactly with how a file system operates: it provides a set of files and those files have attributes. It can additionally provide other services as well, if we provide utilities similar to java.nio.file.Files and our implementation of Path to hold the attached data, we just expose SchemaSourceRepresentation as something you can acquire from the appropriate java.nio.file.attribute.AttributeView.

OpenDaylight JIRA

[YANGTOOLS-1341] Rework yang-repo-api in terms of java.nio