Library to manage Resource references using URI and JSON Pointer.
The JSONRef
class in the kjson-pointer
library provides a means of
navigating around a JSON or YAML structure.
The resource-loader
library simplifies the process of loading resources
identified by URL, including the managing of relative URLs.
The resource-ref
library brings these together and provides a concise API for navigating structures of related JSON or
YAML resources.
First, get an instance of RefResourceLoader
:
val loader = RefResourceLoader()
Then, you can get a Resource
in one of a number of ways:
val fileResource = loader.resource(File("path.to.file")) // using java.io.File
val pathResource = loader.resource(FileSystems.getDefault().getPath("path.to.file")) // using java.nio.file.Path
val urlResource = loader.resource(URL("https://example.com/resource")) // using java.net.URL
val classpathResource = loader.resource(Resource.classPathURL("path.to.file")!!) // using classpath
The ref()
extension function on the Resource
will load the resource as JSON, or if it has an extension of .yaml
or
.yml
, or it is an HTTP(S) resource with a MIME type containing "yaml" or "yml" (there is no official MIME type for
YAML) it will load the resource as YAML, and return a ResourceRef<JSONObject>
.
val ref = resource.ref()
The ResourceRef
has two properties (both publicly accessible):
resource
: theResource
from which the data was loaded – this allows navigation between resources using the rules specified by RFC-3986, andref
: theJSONRef
pointing to the identified location in the structure – this allows navigation within the resource.
The ResourceRef
object is immutable – any navigation functions such as resolve(destination)
etc. will return
a new ResourceRef
.
Most of the functions available on JSONRef
and also available on ResourceRef
, for example child()
, parent()
,
optionalString()
etc. (see JSONRef
for more details), but
because the ResourceRef
also carries the URL used to locate the resource, error messages will be much more helpful.
And the ResourceRef
also has the function that combines the two areas of functionality – the resolve()
function will take a relative reference of the form "resource#node" and return a new ResourceRef
pointing to the
specified location.
val targetRef = ref.resolve(destination)
There are three possibilities:
- Relative URI with no fragment (the part following the "
#
" sign) – in this case the function will attempt to locate the resource identified by the relative URI using RFC-3986, and return aResourceRef
pointing to the root of the object. - A relative URI with a fragment – the function will attempt to locate the resource as above, and will return a
new
ResourceRef
with the pointer set to the node identified by the fragment, as a JSON Pointer. - A fragment (with preceding "
#
" sign) only – the function will return a newResourceRef
for the current resource, with the pointer set to the node identified by the fragment.
More documentation to follow…
The latest version of the library is 2.1, and it may be obtained from the Maven Central repository.
<dependency>
<groupId>io.kjson</groupId>
<artifactId>resource-ref</artifactId>
<version>2.1</version>
</dependency>
implementation 'io.kjson:kjson-pointer:2.1'
implementation("io.kjson:kjson-pointer:2.1")
Peter Wall
2024-08-06