{"id":23129816,"url":"https://github.com/detro/jsonconf","last_synced_at":"2025-10-10T22:10:05.978Z","repository":{"id":15407051,"uuid":"18139077","full_name":"detro/jsonconf","owner":"detro","description":"JSON based configuration utility with some cool features","archived":false,"fork":false,"pushed_at":"2014-05-10T00:23:48.000Z","size":735,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-04T06:41:43.554Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/detro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.BSD","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-03-26T13:33:39.000Z","updated_at":"2024-10-25T17:00:10.000Z","dependencies_parsed_at":"2022-08-25T10:11:38.860Z","dependency_job_id":null,"html_url":"https://github.com/detro/jsonconf","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/detro/jsonconf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/detro%2Fjsonconf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/detro%2Fjsonconf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/detro%2Fjsonconf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/detro%2Fjsonconf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/detro","download_url":"https://codeload.github.com/detro/jsonconf/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/detro%2Fjsonconf/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267792804,"owners_count":24144932,"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-07-29T02:00:12.549Z","response_time":2574,"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-12-17T10:10:59.037Z","updated_at":"2025-10-10T22:10:00.941Z","avatar_url":"https://github.com/detro.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JSONConf (for Java)\n\n[![Build Status](https://travis-ci.org/detro/jsonconf.svg?branch=master)](https://travis-ci.org/detro/jsonconf)\n\nJava utlity that to introduce JSON-based configuration to your project.\n\nThe aim is to make it intuitive to define a `default` configuration, that is then\noverridden based on `user` or `environment` (command line) overrides.\n\n## Basic concepts\n\nLet's say you have a JSON file representing the `default` configuration of your project:\n\n```json\n{\n    \"database\" : {\n        \"host\" : \"111.222.333.444\",\n        \"port\" : 123456,\n        \"username\" : \"dbuser\",\n        \"password\" : \"supersecret\"\n    },\n    \"services\" : {\n        \"url1\" : \"http://production/service/api\"\n    }\n}\n```\n\nUsually, while working on your project, you need to override some of the configuration parameters.\nLet's say you want your `user` configuration (aka \"local\" or \"development\" configuration) to look like this:\n\n```json\n{\n    \"database\" : {\n        \"host\" : \"localhost\",\n        \"port\" : 54321,\n        \"username\" : \"dbuser\",\n        \"password\" : \"supersecret\"\n    },\n    \"services\" : {\n        \"url1\" : \"http://production/service/api\"\n    }\n}\n```\n\nAll is the same as `default`, except for `database.host` and `database.port`, that are set to different values.\nIn other words, what you wanted was to change _just those 2 fields_, applying something as simple as:\n\n```json\n{\n    \"database\" : {\n        \"host\" : \"localhost\",\n        \"port\" : 54321\n    }\n}\n```\n\nEssentially, you needed an **algebraic union** of the `default` configuration with the JSON above. This would allow\nto keep your configuration alteration small and to the point.\n\nJSONConf allows to do just that. And more.\n\n### More basic concepts\n\nLet's say you are happy with the way you configure your project `default` and how you override your `user` configuration\nwith an algebraic union. Still, you discover that a new need arised.\n\nIn some instances, you need to override the configuration, but changing `user` configuration file might be \"too much\".\nMaybe your change is based on the environment. Maybe is just a temporary need. Or you want to keep the configuration as constant\nas possible for a testing environment, but still the machines that are running your code require small differences in configuration.\n\nIn Java, usually, this is the place for `SystemProperties`: you just pass a set of `-Dkey=value` to your executable and read it\nin your code.\n\nThis would require you have to programmatically read those parameters and apply them to your configuration.\nFor example, on a specific machine, the `database.port` value would be the only difference. But, we have already said, you don't want\nto create a specific configuration file.\n\nWhat if you could run your application like:\n\n```bash\njava -jar your_app.jar -Djson[0]=database.port=9999 -Djson[1]=services.url1=\"http://qa/service/api\"\n```\n\nThis woud mean that your configuration parameter `database.port` is overridden to the value `9999`,\nand you are using a [JSON-path](https://github.com/jayway/JsonPath) to override it.\n\n## What is it\n\n_Hopefully you have read the section above. If not, **read it** so I can focus on the code here._\n\nJSONConf consist of just 2 classes:\n\n* `JSONConf`, that will represent the configuration of your application\n* `JSONConfBuilder`, that handles creating the JSONConf for you\n\nyou don't need anything else.\n\n### Example use\n\nCreate 2 files for your project (the actual name of the file is up to you):\n\n* `my-default-config.json`\n* `my-user-or-environment-config.json` (optional)\n\nThen load the configuration in your project with something like:\n\n```java\nJSONConf c = new JSONConfBuilder(\"my-default-config.json\")\n                .withUserConfFilePath(\"my-user-or-environment-config.json\")\n                .build();\n```\n\nThat's it! Start consuming your configuration.\n\n### Advanced use: change name of command line override array\n\nBy default JSONConf allows to override the configuration at runtime via a command line parameter called `json`.\nThis parameter is interpreted as an array and values are expected in the form `-Djson[0]=... -Djson[1]=... -Djson[2]=...`.\nAn example use:\n\n```bash\njava -jar my.jar -Djson[0]=json.path.to.key=value -Djson[1]=json.path.to.another.key=value\n```\n\nIt's possible to change the name of the array when using the `JSONConfBuilder` though:\n\n```java\nJSONConf c = new JSONConfBuilder(\"my-default-config.json\")\n                .withUserConfFilePath(\"my-user-or-environment-config.json\")\n                .withCLIPropsArray(\"myjson\")\n                .build();\n```\n\nand so your command line will look like:\n\n```bash\njava -jar my.jar -Dmyjson[0]=json.path.to.key=value -Dmyjson[1]=json.path.to.another.key=value\n```\n\n### Advanced use: inject alternative `SystemProperties`\n\nBy default the `JSONConfBuilder` will pick the command line parameters from `System.getProperties()`.\nYou can change that doing the following:\n\n```java\nProperties sysProps = new Properties();\nString cliPropsArrayName = \"myarray\";\n\nsysProps.setProperty(cliPropsArrayName + \"[0]\", \"name=\\\"cli config\\\"\");\nsysProps.setProperty(cliPropsArrayName + \"[1]\", \"shared.shared_field_num=3\");\nsysProps.setProperty(cliPropsArrayName + \"[2]\", \"['annoyingly long string'].browsers=\\\"firefox\\\"\");\nsysProps.setProperty(cliPropsArrayName + \"[3]\", \"array_of_nums=[1, 2, 3]\");\nsysProps.setProperty(cliPropsArrayName + \"[4]\", \"array_of_strings=[\\\"string1\\\", \\\"string2\\\", \\\"string3\\\"]\");\n\nJSONConf c = new JSONConfBuilder(\"default-config.json\")\n        .withSystemProperties(sysProps)\n        .withCLIPropsArray(cliPropsArrayName)\n        .build();\n```\n\n## Documentation\n\nPlease check out the [JavaDoc](https://cdn.rawgit.com/detro/jsonconf/master/docs/javadoc/index.html)\nor the [source](https://github.com/detro/jsonconf/blob/master/src/main/java/com/github/detro/jsonconf/JSONConfBuilder.java) itself\nto see the different options offered by the `JSONConfBuilder` to help you tailor the configuration to your needs.\n\n## Dependencies\n\nJSONConf builds upon:\n\n```groovy\ncompile \"com.google.code.gson:gson:$gsonVersion\"\ncompile \"com.jayway.jsonpath:json-path:$jsonPathVersion\"\n```\n\n## Include in your project (via Maven Central)\n\n### Maven\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.github.detro\u003c/groupId\u003e\n    \u003cartifactId\u003ejsonconf\u003c/artifactId\u003e\n    \u003cversion\u003eLATEST_VERSION\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### Grails / Gradle\n```grails\ncompile 'com.github.detro:jsonconf:LATEST_VERSION'\n```\n\n### Others / Latest Version\nSee [search.maven.org](http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22jsonconf%22).\n\n## License (BSD)\n\nSee [LICENSE.BSD](./LICENSE.BSD) located in the project source root.\n\n## Setup in Intellij in Windows\n\nAfter cloning the project, enter the directory and change the permission of gradle.bat.\n```bash\nchmod +x ./gradlew.bat\n```\nUse gradle to generate an Intellij project.\n```bash\n./gradlew.bat idea\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdetro%2Fjsonconf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdetro%2Fjsonconf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdetro%2Fjsonconf/lists"}