Skip to content
Scala client to consume JSON home documents
Scala
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
project
src Add logVerbose parameter to filter verbose output Feb 16, 2018
.gitignore
.travis.yml
LICENSE
README.md
build.sbt
version.sbt

README.md

json-home-client

Build Status

No-magic Scala client to consume JSON home documents like this:

{
  "resources": {
    "http://spec.example.org/rels/artists": {
      "href": "/artists"
    },
    "http://spec.example.org/rels/artist": {
	  "href-template": "/artists/{artist-id}",
      "href-vars": {
        "artist-id": "http://spec.example.org/params/artist"
      }
	}
  }
}

The json-home-client regularly loads json home documents from json home document providers, and caches them in memory. When your application retrieves some information from this json-home-client, the cached json home documents are used so that there'll be no network roundtrip.

This library uses Play's JSON library.

Installation

You must add the json-home-client to the dependencies of the build file, e.g. add to build.sbt:

libraryDependencies += "de.kaufhof" %% "json-home-client" % "3.0.3"

It is published to sonatype nexus for scala 2.11 and 2.12.

Usage

At first you setup the JsonHomeService for various hosts that provide json home documents. The first host serves a json home like the one shown above.

import de.kaufhof.jsonhomeclient._

// Specify which service/host provides which link relations
// By default, json home docs are assumed to be served from `/.well-known/home`.
val host1 = JsonHomeHost("http://some.host", Seq(
  // A link relation without params
  DirectLinkRelationType("http://spec.example.org/rels/artists"),
  // A link relation with template params
  TemplateLinkRelationType("http://spec.example.org/rels/artist")
))

// Create the client, it loads the json home doc from the host
//Make sure to shutdown the ActorSystem after usage
implicit val system: ActorSystem  = ActorSystem()
implicit val materializer: ActorMaterializer  = ActorMaterializer()
val client1 = new JsonHomeClient(host1)

// Create the cache, it will regularly (using the Akka scheduler) load json home doc
// using the client. The initialTimeToWait is used for requests when the schedule did not yet
// kick in (might happen e.g. in tests) so that the json home doc was not yet requested/loaded.
// In this case the json home doc is directly loaded from the client and the cache will wait for
// the result using the given `initialTimeToWait`. Decide whether the cache
// should log output verbose or not.
val cache1 = new JsonHomeCache(
  client1,
  updateInterval = 5 minutes,
  initialTimeToWait = 10 seconds,
  logVerbose = false
)

// The json home service, the interface for applications, set up with several json home caches
val jsonHomeService = JsonHomeService(Seq(cache1, cache2, ...))

Once the json home service is set up, you can use it to retrieve links for link-relations.

// Example 1: Get a link relation that does not expect template params
jsonHomeService.getUrl(
  host1,
  DirectLinkRelationType("http://spec.example.org/rels/artists")
) == Some("/artists")

// Example 2: Some link relation that expects template params
jsonHomeService.getUrl(
  host1,
  TemplateLinkRelationType("http://spec.example.org/rels/artist"),
  Map("artist-id" -> "acdc")
) == Some("/artists/acdc")

Release

sbt

sbt Release

License

The license is Apache 2.0, see LICENSE.

You can’t perform that action at this time.