Package software.amazon.smithy.model.loader

Class ModelDiscovery

java.lang.Object
software.amazon.smithy.model.loader.ModelDiscovery
public final class ModelDiscovery extends Object
Discovers Smithy models by finding all META-INF/smithy/manifest files on the class path and loading all of the newline separated relative model files referenced from the manifest.

The URLs discovered through model discovery are imported into a ModelAssembler when ModelAssembler.discoverModels(java.lang.ClassLoader) is called, providing a mechanism for discovering Smithy models on the classpath at runtime.

The format of a META-INF/smithy/manifest file is a newline separated UTF-8 text file in which each line is a resource that is relative to the manifest file. A line is considered to be terminated by any one of a line feed ('\n'), a carriage return ('\r'), a carriage return followed immediately by a line feed, or by reaching the end-of-file (EOF). The resources referenced by a manifest are loaded by resolving the relative resource against the URL that contains each META-INF/smithy/manifest file found using ClassLoader.getResources(java.lang.String).

The following restrictions and interpretations apply to the names of model resources that can be placed on manifest lines:

  • Empty lines are ignored.
  • Lines that start with a number sign (#) are comments and are ignored.
  • Lines must contain only ASCII characters
  • Lines must not start with "/" or end with "/". Models are resolved as relative resources to the manifest URL and expected to be contained within the same JAR/JMOD as the manifest.
  • Lines must not contain empty segments (//).
  • Lines must not contain dot-dot segments (..).
  • Lines must not contain dot segments (/./) (./).
  • Lines must not contain spaces ( ) or tabs (\t).
  • Lines must not contain a backslash (\).
  • Lines must not contain a question mark (?).
  • Lines must not contain a percent sign (%).
  • Lines must not contain an asterisk (*).
  • Lines must not contain a colon (:).
  • Lines must not contain a vertical bar (|).
  • Lines must not contain a quote (") or (').
  • Lines must not contain greater than (>) or less than (<) signs.
  • Lines must not contain pound signs (#).

For example, given the following META-INF/smithy/manifest file discovered at jar:file:///C:/foo/baz/bar.jar!/META-INF/smithy/manifest on the class path, 

 smithy.example.traits.smithy
 foo/another.file.smithy

Smithy will attempt to discover the following models:

  • jar:file:///C:/foo/baz/bar.jar!/META-INF/smithy/smithy.example.traits.smithy
  • jar:file:///C:/foo/baz/bar.jar!/META-INF/smithy/foo/another.file.smithy

Models defined in META-INF/smithy should be named after the namespace that is defined within the file. Files that define multiple namespaces are free to use whatever naming scheming they choose, but model files should be globally unique in an application.

  • Method Details

    • findModels

      public static List<URL> findModels()
      Finds Smithy models using the thread context ClassLoader.
      Returns:
      Returns the URLs of each model referenced by manifests.

    • findModels

      public static List<URL> findModels(ClassLoader loader)
      Finds Smithy models using the given ClassLoader.
      Parameters:
      loader - ClassLoader used to discover models.
      Returns:
      Returns the URLs of each model referenced by manifests.

    • findModels

      public static List<URL> findModels(URL jarManifestUrl)
      Parse the Smithy models from the given URL that points to a Smithy manifest file in a JAR.

      The provided URL is expected to point to a manifest stored in JAR (e.g., "jar:file:/example.jar!/META-INF/smithy/manifest).

      Parameters:
      jarManifestUrl - Manifest URL to parse line by line.
      Returns:
      Returns the URLs of each model referenced by the manifest.

    • getSmithyModelPathFromJarUrl

      public static String getSmithyModelPathFromJarUrl(URL modelUrl)
      Extracts the relative name of a Smithy model from a URL that points to a Smithy model returned from findModels().

      For example, given "jar:file:/example.jar!/META-INF/smithy/example.json", this method will return "example.json".

      Parameters:
      modelUrl - Model URL to get the name from.
      Returns:
      Returns the extracted name.

    • createSmithyJarManifestUrl

      public static URL createSmithyJarManifestUrl(String fileOrUrl)
      Creates a URL that points to the Smithy manifest file of a JAR.

      The provided fileOrUrl string can be an absolute path to a file, (e.g., "/foo/baz.jar"), a file URL (e.g., "file:/baz.jar"), or a JAR URL (e.g., "jar:file:/baz.jar").

      Parameters:
      fileOrUrl - Filename or URL that points to a JAR.
      Returns:
      Returns the computed URL.