{"id":18510100,"url":"https://github.com/gitana/gitana-java-driver","last_synced_at":"2025-10-13T03:37:06.745Z","repository":{"id":42037734,"uuid":"993373","full_name":"gitana/gitana-java-driver","owner":"gitana","description":"Gitana Java Driver","archived":false,"fork":false,"pushed_at":"2025-07-29T18:16:24.000Z","size":15210,"stargazers_count":4,"open_issues_count":2,"forks_count":4,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-07-29T21:06:38.730Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://gitana.io","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/gitana.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.TXT","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":"2010-10-16T21:13:21.000Z","updated_at":"2025-07-28T18:45:47.000Z","dependencies_parsed_at":"2024-01-30T16:36:55.881Z","dependency_job_id":"edd60b5d-0690-4328-b3fa-7cef921b62b0","html_url":"https://github.com/gitana/gitana-java-driver","commit_stats":null,"previous_names":[],"tags_count":49,"template":false,"template_full_name":null,"purl":"pkg:github/gitana/gitana-java-driver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitana%2Fgitana-java-driver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitana%2Fgitana-java-driver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitana%2Fgitana-java-driver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitana%2Fgitana-java-driver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gitana","download_url":"https://codeload.github.com/gitana/gitana-java-driver/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitana%2Fgitana-java-driver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279013517,"owners_count":26085368,"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","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-11-06T15:20:56.268Z","updated_at":"2025-10-13T03:37:06.685Z","avatar_url":"https://github.com/gitana.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gitana Java Driver\n\nThe Gitana Java Driver is an Apache 2.0 licensed client library that you can drop into your Java or Android\napplications to connect to the Gitana Cloud CMS platform.  It provides a nice client interface with multi-threaded support that works\nwell with modern Java applications including those that run on mobile devices and the Spring Framework.\n\nThe Gitana Java driver handles all of the HTTPS calls, data conversions, OAuth2 authorization handshakes and any and\nall interaction with the Gitana platform in a secure manner.  It works against Gitana running on our SaaS platform\nas well as on-premise installations at any endpoint you configure.\n\n## Maven Dependency\n\nTo include this driver in your projects, add the following repository to your build:\n\n````\n\u003crepositories\u003e\n    \u003crepository\u003e\n        \u003cid\u003ecloudcms-public\u003c/id\u003e\n        \u003cname\u003ecloudcms-public\u003c/name\u003e\n        \u003curl\u003ehttps://maven.cloudcms.com/public\u003c/url\u003e\n    \u003c/repository\u003e\n\u003c/repositories\u003e\n````\n\nAnd then add the following Maven dependency:\n\n````\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eorg.gitana\u003c/groupId\u003e\n        \u003cartifactId\u003egitana-java-driver\u003c/artifactId\u003e\n        \u003cversion\u003e{version}\u003c/version\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n````\n\n## Gitana 4.0 vs Gitana 3.2\n\nIf you're connecting to Gitana 4.0, we recommend using the `4.x.y` versions of this driver.  Going forward,\nthe major version number of this driver will correspond with the API release version. \n\nFor Gitana 3.2, you will need to use the `1.x.y` versions of the driver.\n\n## Connecting to Cloud CMS\n\nTo connect to Cloud CMS, use the static `Gitana.connect()` method.  You can connect using a resource bundle, a JSON\nconfiguration object or a Map of properties.\n\nThe following API Key properties are required:\n\n- `clientKey`\n- `clientSecret`\n- `username`\n- `password`\n\nThese properties are available with your Cloud CMS subscription.\n\nIn addition, you may wish to supply a `baseURL` to indicate an alternative location for the Cloud CMS API endpoint.\nBy default the `baseURL` is `https://api.cloudcms.com`.\n\nThe following method calls are equivalent -\n\n````\nResourceBundle bundle = ...;\nPlatform platform1 = Gitana.connect(bundle);\n\nObjectNode config = ...;\nPlatform platform2 = Gitana.connect(config);\n\nMap\u003cString, String\u003e properties = ...;\nPlatform platform3 = Gitana.connect(properties);\n````\n\n## Examples\n\nOnce you've connected, you may wish to query for repositories:\n\n````\nResultMap\u003cRepository\u003e repositories = platform.listRepositories();\nfor (Repository repository: repositories.values()) {\n    System.out.println(\"Found repository: \" + repository.getId());\n}\n````\n\nOr query for content from the master branch of a known repository:\n\n````\nRepository repository = platform.readRepository(\"abcdef123456\");\nBranch branch = repository.readBranch(\"master\");\n\n// the query we want to run (using MongoDB syntax)\nObjectNode query = JsonUtil.createObject();\nquery.put(\"category\", \"large\");\n\n// run query\nResultMap\u003cNode\u003e nodes = branch.queryNodes(query);\nfor (Node node: nodes.values()) {\n    System.out.println(\"Found content item: \" + node.stringify(true));\n}\n````\n\n## Multithreading\n\nWhen you connect to Cloud CMS using the `Gitana.connect()` method, a thread local is populated that stores the driver\ncontext.  In other words, the authentication is stored on the current thread.\n\nAfter authenticating, you can access the authentication state like this:\n\n````\nDriver driver = DriverContext.getDriver();\n````\n\nIf you decide to spin up a second thread, you can either re-authenticate on that thread or you can copy the `Driver`\ncontext over and use it at zero code.  On the new thread, simply call:\n\n````\nDriverContext.setDriver(driver);\n````\n\nNote that `Driver` is not serializable.  That said, it is a common practice to cache the `Driver` instances in a\nsingleton or producer class to reuse them across requests.  You may also wish to cache other Cloud CMS objects such as\n`Platform`, `Repository`, `Branch` and `Node`s.\n\n## Access and Refresh Tokens\n\nThe driver automatically manages access tokens and refresh tokens for you.  Access and refresh tokens are acquired when\nthe driver connects and are maintained during the lifecycle of the driver.  Access tokens (also referred to as bearer\ntokens) are automatically applied to your requests when they are sent to Cloud CMS.  They are used to assert the identity\nof the user making the connection.  If an access token expires (or is otherwise rejected), the refresh token is used\nautomatically to acquire a new access token.\n\nThe driver's goal is make this transparent so that developers need not worry about handling intermittent or unpredictable\nauthentication issues that may arise.  Bear in mind that an access token may expire at any time (or be forcibly expired)\nand so the handling of 401 unauthenticated status codes is ever-present.  The driver's goal is make this easier for you\ndeveloper so that they don't have to handle these situations each and every time.\n\nThe drivers supports two modes to assist with this - a \"normal\" mode and an \"automatic\" mode.\n\nIn normal mode, the call is made to the remote endpoint, committing the request stream.  If a 401 is received, the\ndriver simply invalidates the access token locally and allows the request to fail.  In this case, the invoker gets back\na 401.  However, the next request will see a null access token and will pre-emptively acquire a new access token ahead\nof committing the request.  Thus, in this scenario, a failed call is allowed provided that the next one will work\nas expected.  This is very HTTP friendly and some would argue is more \"pure\".\n\nIn \"automatic\" mode, the driver attempts to make a call and if it gets back an Invalid Access Token error, it then makes\nanother call using the refresh token to acquire a new access token.  Once acquired, the original call is attempted again.\nIf it fails a second time, the second response is handed back to the invoker.\n\nTo make this possible in \"automatic\" mode, the driver first caches the request stream to disk.  That way, if the original\ncall fails with a 401, it can re-stream the second request after the access token was acquired.  This make things perfectly\nseamless from a usage perspective but does introduce a few interesting factors:\n\n1.  There is a performance penalty due to the stream caching to disk.  The impact of this will depend on the size of the\nstream and the performance of your disk.  It may be fairly negligible for small stream sizes.\n2.  This requires temp file space on disk.  You will need to make sure you size partitions accordingly.\n\nBy default, the driver operates in \"normal\" mode.  To switch automatic mode on, you can use the following system\nproperty (see system properties below):\n\n- `gitana.useAutomaticReattempt` - (boolean)\n\n\n## System Properties\n\nThe following system properties can be used to adjust the driver's behavior.  These can either be plugged into\n`System.getProperties()` or you can supply them at launch time using `-D` switches.\n\n- `gitana.socketSoTimeout` - (ms) socket timeout (default: 10 minutes)\n- `gitana.requestConnectTimeout` - (ms) time to establish connection with remote (default: 2 minutes)\n- `gitana.requestSocketTimeout` - (ms) how long to wait for data to start coming back (default: 10 minutes)\n- `gitana.connectionRequestTimeout` - (ms) how long to wait for a connection from the pool (default: 1 minute)\n\n## Proxy\n\nUse the following system properties to control the HTTP proxy:\n\n- http.proxyHost\n- http.proxyPort\n- https.proxyHost\n- https.proxyPort\n\n## More Examples\n\nOne very good place to look for examples of the Gitana Java Driver in use is within the source code itself.  The\nunit tests work through a variety of interesting use cases and may give you ideas of some of the ways you can use the\ndriver to accomplish what you need.\n\n## Resources\n\n* Gitana: https://gitana.io\n* Gitana Java Driver: https://gitana.io/documentation/gitana/4.0/developers/drivers/java.html\n* Gitana Java Cookbook: https://gitana.io/documentation/gitana/4.0/developers/cookbooks/java.html\n* Gitana Documentation: https://gitana.io/documentation.html\n* Gitana Developers Guide: https://gitana.io/developers.html\n\n## Support\n\nFor information or questions about the Java Driver, please contact Gitana\nat \u003ca href=\"mailto:support@gitana.io\"\u003esupport@gitana.io\u003c/a\u003e.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgitana%2Fgitana-java-driver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgitana%2Fgitana-java-driver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgitana%2Fgitana-java-driver/lists"}