{"id":13514919,"url":"https://github.com/fauna/faunadb-jvm","last_synced_at":"2025-04-13T07:48:13.473Z","repository":{"id":24232120,"uuid":"27624737","full_name":"fauna/faunadb-jvm","owner":"fauna","description":"Scala and Java driver for FaunaDB v4","archived":false,"fork":false,"pushed_at":"2024-10-14T18:33:36.000Z","size":13201,"stargazers_count":74,"open_issues_count":6,"forks_count":19,"subscribers_count":32,"default_branch":"v4","last_synced_at":"2025-04-13T07:48:08.374Z","etag":null,"topics":["client","clients","database","driver","drivers","fauna","faunadb","java","scala"],"latest_commit_sha":null,"homepage":"https://fauna.com","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fauna.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.txt","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-12-06T06:23:42.000Z","updated_at":"2024-09-09T19:30:31.000Z","dependencies_parsed_at":"2024-08-28T20:44:59.410Z","dependency_job_id":"e1d1a3d7-68be-473e-98f5-8efbf826b7f3","html_url":"https://github.com/fauna/faunadb-jvm","commit_stats":null,"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fauna%2Ffaunadb-jvm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fauna%2Ffaunadb-jvm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fauna%2Ffaunadb-jvm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fauna%2Ffaunadb-jvm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fauna","download_url":"https://codeload.github.com/fauna/faunadb-jvm/tar.gz/refs/heads/v4","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248681494,"owners_count":21144700,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","clients","database","driver","drivers","fauna","faunadb","java","scala"],"created_at":"2024-08-01T05:01:03.790Z","updated_at":"2025-04-13T07:48:13.447Z","avatar_url":"https://github.com/fauna.png","language":"Java","funding_links":[],"categories":["Java"],"sub_categories":[],"readme":"# Java and Scala drivers for Fauna v4 (deprecated)\n\n[![Maven Central](https://img.shields.io/maven-central/v/com.faunadb/faunadb-common.svg?maxAge=21600)](https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.faunadb%22)\n[![License](https://img.shields.io/badge/license-MPL_2.0-blue.svg?maxAge=2592000)](https://raw.githubusercontent.com/fauna/faunadb-jvm/main/LICENSE)\n\n\u003e [!WARNING]\n\u003e  Fauna is decommissioning FQL v4 on June 30, 2025.\n\u003e\n\u003e This driver is not compatible with FQL v10, the latest version. Fauna accounts\n\u003e created after August 21, 2024 must use FQL v10. Ensure you migrate existing\n\u003e projects to the official v10 driver by the v4 EOL date:\n\u003e https://github.com/fauna/fauna-jvm.\n\u003e\n\u003e For more information, see the [v4 end of life (EOL)\n\u003e announcement](https://docs.fauna.com/fauna/v4/#fql-v4-end-of-life) and\n\u003e [related FAQ](https://docs.fauna.com/fauna/v4/migration/faq).\n\nThis repository contains the official Java and Scala drivers for [Fauna\nv4](https://docs.fauna.com/fauna/v4/).\n\nSee the [Fauna v4 documentation](https://docs.fauna.com/fauna/v4) and\n[tutorials](https://docs.fauna.com/fauna/v4/learn/tutorials/fql/crud?lang=javascript)\nfor guides and a complete database [API\nreference](https://docs.fauna.com/fauna/v4/api/fql/).\n\n### Features\n\n* All drivers fully support the current version of the [FaunaDB API](https://docs.fauna.com/fauna/current/reference/queryapi/).\n* Java and Scala clients share the same underlying library [faunadb-common](./faunadb-common).\n* Supports [Dropwizard Metrics](https://dropwizard.github.io/metrics/3.1.0/) hooks for stats reporting.\n\n## Documentation\n\nJavadocs and Scaladocs are hosted on GitHub:\n\n* [faunadb-java](http://fauna.github.io/faunadb-jvm/4.5.0/faunadb-java/api/)\n* [faunadb-scala](http://fauna.github.io/faunadb-jvm/4.5.0/faunadb-scala/api/)\n\nDetails Documentation for each language:\n\n* [Java](docs/java.md)\n* [Scala](docs/scala.md)\n\n## Dependencies\n\n### Shared\n\n* [Jackson](https://github.com/FasterXML/jackson) for JSON parsing.\n\n### Java\n\n* Java 11\n\n### Scala\n\n* Scala 2.11.x\n* Scala 2.12.x\n\n## Using the Driver\n\n### Java\n\n#### Installation\n\nDownload from the Maven central repository:\n\n##### faunadb-java/pom.xml:\n\n```xml\n\u003cdependencies\u003e\n  ...\n  \u003cdependency\u003e\n    \u003cgroupId\u003ecom.faunadb\u003c/groupId\u003e\n    \u003cartifactId\u003efaunadb-java\u003c/artifactId\u003e\n    \u003cversion\u003e4.5.0\u003c/version\u003e\n    \u003cscope\u003ecompile\u003c/scope\u003e\n  \u003c/dependency\u003e\n  ...\n\u003c/dependencies\u003e\n```\n\n##### Basic Java Usage\n\n```java\nimport com.faunadb.client.FaunaClient;\n\nimport static com.faunadb.client.query.Language.*;\n\n/**\n * This example connects to FaunaDB Cloud using the secret provided\n * and creates a new database named \"my-first-database\"\n */\npublic class Main {\n    public static void main(String[] args) throws Exception {\n\n        //Create an admin connection to FaunaDB.\n        FaunaClient adminClient =\n            FaunaClient.builder()\n                .withSecret(\"put-your-key-secret-here\")\n                .build();\n\n        adminClient.query(\n            CreateDatabase(\n                Obj(\"name\", Value(\"my-first-database\"))\n            )\n        ).get();\n    }\n}\n```\n\n##### Per query metrics\nThere are several metrics that returned per each request in response headers. Read this [doc](https://docs.fauna.com/fauna/current/concepts/billing.html#perquery) to have more info.\nYou can access these metrics by:\n```java\nimport com.faunadb.client.FaunaClient;\n\nimport static com.faunadb.client.query.Language.*;\n\npublic class Main {\n    public static void main(String[] args) throws Exception {\n\n        //Create an admin connection to FaunaDB.\n        FaunaClient adminClient =\n            FaunaClient.builder()\n                .withSecret(\"put-your-key-secret-here\")\n                .build();\n\n        MetricsResponse metricsResponse = adminClient.queryWithMetrics(\n            Paginate(Match(Index(\"spells_by_element\"), Value(\"fire\"))),\n            Optional.empty()\n    \t).get();\n\n        // the result of the query, as if you invoke 'adminClient.query' function instead\n        Value value = metricsResponse.getValue();\n\n        // gets the value of 'x-byte-read-ops' metric\n        Optional\u003cString\u003e byteReadOps = metricsResponse.getMetric(MetricsResponse.Metrics.BYTE_READ_OPS);\n        // gets the value of 'x-byte-write-ops' metric\n        Optional\u003cString\u003e byteWriteOps = metricsResponse.getMetric(MetricsResponse.Metrics.BYTE_WRITE_OPS);\n\n        // you can get other metrics in the same way,\n        // all of them are exposed via MetricsResponse.Metrics enum\n    }\n}\n```\n\n##### Custom headers\nThere is an optional possibility to send custom headers for each http request. They can be defined in the client's constructor:\n```java\nFaunaClient adminClient =\n    FaunaClient.builder()\n        .withSecret(\"put-your-key-secret-here\")\n        .withCustomHeaders(\n            Map.of(\n                \"custom-header-1\", \"value-1\",\n                \"custom-header-2\", \"value-2\"\n            )\n        )\n        .build();\n```\n\n##### Document Streaming\n\nFauna supports document streaming, where changes to a streamed document are pushed to all clients subscribing to that document.\n\nThe streaming API is built using the [java.util.concurrent.Flow](https://docs.oracle.com/javase/9/docs/api/java/util/concurrent/Flow.html) which enable users to establish flow-controlled components in which `Publishers` produce items consumed by one or more `Subscribers`, each managed by a `Subscription`.\n\nThe following example assumes that you have already created a `FaunaClient`.\n\nIn the example below, we are capturing the 4 first messages by manually binding a `Subscriber`.\n\n```java\n// docRef is a reference to the document for which we want to stream updates.\n// You can acquire a document reference with a query like the following, but it\n// needs to work with the documents that you have.\n// Value docRef = Ref(Collection(\"scoreboards\"), \"123\")\n\nFlow.Publisher\u003cValue\u003e valuePublisher = adminClient.stream(createdDoc).get();\nCompletableFuture\u003cList\u003cValue\u003e\u003e capturedEvents = new CompletableFuture\u003c\u003e();\n\nFlow.Subscriber\u003cValue\u003e valueSubscriber = new Flow.Subscriber\u003c\u003e() {\n  Flow.Subscription subscription = null;\n  ArrayList\u003cValue\u003e captured = new ArrayList\u003c\u003e();\n  @Override\n  public void onSubscribe(Flow.Subscription s) {\n    subscription = s;\n    subscription.request(1);\n  }\n\n  @Override\n  public void onNext(Value v) {\n    captured.add(v);\n    if (captured.size() == 4) {\n      capturedEvents.complete(captured);\n      subscription.cancel();\n    } else {\n      subscription.request(1);\n    }\n  }\n\n  @Override\n  public void onError(Throwable throwable) {\n     capturedEvents.completeExceptionally(throwable);\n  }\n\n  @Override\n  public void onComplete() {\n    capturedEvents.completeExceptionally(new IllegalStateException(\"not expecting the stream to complete\"));\n  }\n};\n\n// subscribe to publisher\nvaluePublisher.subscribe(valueSubscriber);\n\n// blocking\nList\u003cValue\u003e events = capturedEvents.get();\n```\n\n[Detailed Java Documentation can be found here](docs/java.md)\n\n### Scala\n\n#### Installation\n\n##### faunadb-scala/sbt\n\n```scala\nlibraryDependencies += (\"com.faunadb\" %% \"faunadb-scala\" % \"4.5.0\")\n```\n\n##### Basic Usage\n\n```scala\nimport faunadb._\nimport faunadb.query._\nimport scala.concurrent._\nimport scala.concurrent.duration._\n\n/**\n  * This example connects to FaunaDB Cloud using the secret provided\n  * and creates a new database named \"my-first-database\"\n  */\nobject Main extends App {\n\n  import ExecutionContext.Implicits._\n\n  val client = FaunaClient(\n    secret = \"put-your-secret-here\"\n  )\n\n  val result = client.query(\n    CreateDatabase(\n      Obj(\"name\" -\u003e \"my-first-database\")\n    )\n  )\n\n  Await.result(result, Duration.Inf)\n}\n```\n\n##### Per query metrics\nThere are several metrics that returned per each request in response headers. Read this [doc](https://docs.fauna.com/fauna/current/concepts/billing.html#perquery) to have more info.\nYou can access these metrics by:\n```scala\nimport faunadb._\nimport faunadb.query._\nimport scala.concurrent._\nimport scala.concurrent.duration._\n\n/**\n  * This example connects to FaunaDB Cloud using the secret provided\n  * and creates a new database named \"my-first-database\"\n  */\nobject Main extends App {\n\n  import ExecutionContext.Implicits._\n\n  val client = FaunaClient(\n    secret = \"put-your-secret-here\"\n  )\n\n  val metricsResponse = client.queryWithMetrics(\n    Paginate(Match(Index(\"spells_by_element\"), Value(\"fire\"))),\n    None\n  ).futureValue\n\n  // the result of the query, as if you invoke 'client.query' function instead\n  val value = metricsResponse.value\n\n  // gets the value of 'x-byte-read-ops' metric\n  val byteReadOps = metricsResponse.getMetric(Metrics.ByteReadOps)\n  // gets the value of 'x-byte-write-ops' metric\n  val byteWriteOps = metricsResponse.getMetric(Metrics.ByteWriteOps)\n\n  // you can get other metrics in the same way,\n  // all of them are exposed via Metrics enum}\n```\n\n##### Custom headers\nThere is an optional possibility to send custom headers for each http request. They can be defined in the client's constructor:\n```scala\nval client = FaunaClient(\n  secret = \"put-your-secret-here\",\n  customHeaders = scala.Predef.Map(\"custom-header-1\" -\u003e \"value-1\", \"custom-header-2\" -\u003e \"value-2\")\n)\n```\n\n##### Document Streaming\n\nFauna supports document streaming, where changes to a streamed document are pushed to all clients subscribing to that document.\n\nThe following sections provide examples for managing streams with Flow or Monix, and\nassume that you have already created a `FaunaClient`.\n\n###### Flow subscriber\n\nIt is possible to use the [java.util.concurrent.Flow](https://docs.oracle.com/javase/9/docs/api/java/util/concurrent/Flow.html) API directly by binding a `Subscriber` manually.\n\nIn the example below, we are capturing the 4 first messages:\n\n```scala\nimport faunadb._\nimport faunadb.query._\n\n// docRef is a reference to the document for which we want to stream updates.\n// You can acquire a document reference with a query like the following, but it\n// needs to work with the documents that you have.\n// val docRef = Ref(Collection(\"scoreboards\"), \"123\")\n\nclient.stream(docRef).flatMap { publisher =\u003e\n  // Promise to hold the final state\n  val capturedEventsP = Promise[List[Value]]\n\n  // Our manual Subscriber\n  val valueSubscriber = new Flow.Subscriber[Value] {\n    var subscription: Flow.Subscription = null\n    val captured = new ConcurrentLinkedQueue[Value]\n\n    override def onSubscribe(s: Flow.Subscription): Unit = {\n      subscription = s\n      subscription.request(1)\n    }\n\n    override def onNext(v: Value): Unit = {\n      captured.add(v)\n      if (captured.size() == 4) {\n        capturedEventsP.success(captured.iterator().asScala.toList)\n        subscription.cancel()\n      } else {\n        subscription.request(1)\n      }\n    }\n\n    override def onError(t: Throwable): Unit =\n      capturedEventsP.failure(t)\n\n    override def onComplete(): Unit =\n      capturedEventsP.failure(new IllegalStateException(\"not expecting the stream to complete\"))\n  }\n  // subscribe to publisher\n  publisher.subscribe(valueSubscriber)\n  // wait for Future completion\n  capturedEventsP.future\n}\n```\n\n###### Monix\n\nThe [reactive-streams](http://www.reactive-streams.org/) standard offers a strong interoperability in the streaming ecosystem.\n\nWe can replicate the previous example using the [Monix](https://monix.io/) streaming library.\n\n```scala\nimport faunadb._\nimport faunadb.query._\nimport monix.execution.Scheduler\nimport monix.reactive.Observable\nimport org.reactivestreams.{FlowAdapters, Publisher}\n\n// docRef is a reference to the document for which we want to stream updates.\n// You can acquire a document reference with a query like the following, but it\n// needs to work with the documents that you have.\n// val docRef = Ref(Collection(\"scoreboards\"), \"123\")\n\nclient.stream(docRef).flatMap { publisher =\u003e\n  val reactiveStreamsPublisher: Publisher[Value] = FlowAdapters.toPublisher(publisherValue)\n  Observable.fromReactivePublisher(reactiveStreamsPublisher)\n    .take(4) // 4 events\n    .toListL\n    .runToFuture(Scheduler.Implicits.global)\n}\n```\n\n\n## Building\n\nThe faunadb-jvm project is built using sbt:\n\n* **sbt**: [Scala Simple Build Tool](http://www.scala-sbt.org/)\n\nTo build and run tests against cloud, set the env variable\n`FAUNA_ROOT_KEY` to your admin key secret and run `sbt test` from the\nproject directory.\n\nAlternatively, tests can be run via a Docker container with\n`FAUNA_ROOT_KEY=\"your-cloud-secret\" make docker-test` (an alternate\nDebian-based JDK image can be provided via `RUNTIME_IMAGE`).\n\nTo run tests against an enterprise cluster or developer instance, you\nwill also need to set `FAUNA_SCHEME` (http or https), `FAUNA_DOMAIN`\nand `FAUNA_PORT`.\n\n### License\n\nAll projects in this repository are licensed under the [Mozilla Public License](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffauna%2Ffaunadb-jvm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffauna%2Ffaunadb-jvm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffauna%2Ffaunadb-jvm/lists"}