{"id":15046079,"url":"https://github.com/microbean/microbean-configuration","last_synced_at":"2026-02-19T00:31:56.916Z","repository":{"id":57745175,"uuid":"80768259","full_name":"microbean/microbean-configuration","owner":"microbean","description":"A Java library for accessing configuration values, taking configuration coordinates into account.","archived":false,"fork":false,"pushed_at":"2019-09-10T21:23:51.000Z","size":1464,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-20T13:23:49.277Z","etag":null,"topics":["configuration","java","java-library","java-se"],"latest_commit_sha":null,"homepage":"https://microbean.github.io/microbean-configuration/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/microbean.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-02-02T21:00:37.000Z","updated_at":"2019-09-10T21:05:01.000Z","dependencies_parsed_at":"2022-08-28T05:31:45.004Z","dependency_job_id":null,"html_url":"https://github.com/microbean/microbean-configuration","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbean%2Fmicrobean-configuration","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbean%2Fmicrobean-configuration/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbean%2Fmicrobean-configuration/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microbean%2Fmicrobean-configuration/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microbean","download_url":"https://codeload.github.com/microbean/microbean-configuration/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243451605,"owners_count":20293168,"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":["configuration","java","java-library","java-se"],"created_at":"2024-09-24T20:52:40.796Z","updated_at":"2025-10-15T08:54:59.862Z","avatar_url":"https://github.com/microbean.png","language":"Java","readme":"# microBean™ Configuration\n\n[![Build Status](https://travis-ci.org/microbean/microbean-configuration.svg?branch=master)](https://travis-ci.org/microbean/microbean-configuration)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.microbean/microbean-configuration/badge.svg)](https://maven-badges.herokuapp.com/maven-central/org.microbean/microbean-configuration)\n\nThe microBean™ Configuration project provides yet another framework\nfor acquiring configuration values from within a Java SE application,\nimplementing the [microBean™ Configuration API project][10].\n\nThere are many configuration frameworks for Java SE.  All focus on\nmaking it easy for application developers to ask for configuration\nvalues without having to know what systems provide those values.\n\nmicroBean™ Configuration takes a slightly different approach.  The\napplication's full configuration is considered to be located by its\n_configuration coordinates_ within _configuration space_.  Within that\nspace reside its actual configuration properties.  This terminology is\nimportant for understanding how microBean™ Configuration works.\n\nTerminology\n===========\n\nConfiguration Space\n-------------------\n\n_Configuration space_ is defined as the unbounded universe of\nconfiguration properties and their values, for all applications,\nregardless of which system or systems might define or house them.\nDimensions within this space might include locale, region, data center\nidentifier, tenant identifier\u0026mdash;these are only examples.  Of note\nis that these are dimensions, not nodes within a hierarchy.\n\nConfiguration Coordinates\n-------------------------\n\n_Configuration coordinates_ are those which semantically locate an\napplication in configuration space.  So an application run in the US\nlocale, in the test environment, located in the Western region of a\ncloud provider, in the Nevada data center and run on behalf of tenant\nnumber 34 (to use the examples from the Configuration Space section\nabove) is located in configuration space with, perhaps, the following\nlogical configuration coordinates:\n\n    locale=en_US\n    environment=test\n    region=west\n    dataCenter=Nevada\n    tenantId=34\n    \nWhile these coordinates look like configuration values themselves,\nthey are configuration values for locating the application in\nconfiguration space, not (normally) the values that the application\nwill be looking up during the course of its execution.\n\nConfiguration Properties\n------------------------\n\n_Configuration properties_ are the names for which (non-hard-coded)\nvalues are sought by an application.  `portNumber`,\n`timeoutInSeconds`, `databaseUrl` and `userEmail` are arbitrary\nexamles of configuration properties.  These are, by definition,\nnon-specific identifiers.  They gain specificity only when further\npinpointed in configuration space by a set of configuration\ncoordinates.  That is, `databaseUrl` is a configuration property that\nmight have many different possible values for many different possible\napplications.  The configuration property `databaseUrl` used by a\nparticular application is only relevant when it is interpreted in the\ncontext of the appropriate set of configuration coordinates.  For\nexample, a configuration author may only be able to write a value for\nthe `databaseUrl` configuration property when she knows that the value\nis supposed to be for the test environment in the Nevada data center\non behalf of tenant 34.  Or she may also be able to write a value for\nthe `databaseUrl` configuration property when she knows that the value\nis supposed to be for the test environment and the Western region.  As\nyou can see, configuration coordinates are not hierarchical, and\nneither (necessarily) are configuration properties.\n\nConfiguration Values\n--------------------\n\n_Configuration values_ are two things: the _values received by an\napplication_ situated in configuration space by its configuration\ncoordinates when that application asks for a value for a configuration\nproperty, and _values that are written_ in such a way that they may be\nfound by one or more such applications.\n\nFor example, a configuration author might write a value, `red`, for a\nhypothetical `color` configuration property, into a system somewhere,\nonce.  The author may decide (let's say) that this value is suited for\nany application possessing any configuration coordinates.  In this\ncase, the value received by an instance of application _A_ identified\nby one set of configuration coordinates, asking for a value for the\n`color` configuration property will be the same as the value received\nby another instance of _A_ identified by a different set of\nconfiguration coordinates asking for a value for the `color`\nconfiguration property.  The author thus wrote one configuration\nvalue, but from the standpoint of the querying application instances,\nthere are two values in play.\n\n(_Configuration value_ may also refer to the [`ConfigurationValue`][9]\nservice provider class returned by [`Configuration`][2] instances.)\n\nConfiguration\n-------------\n\nA _configuration_ is simply a collection of some configuration\nproperties and their values designated for one or more\npoints\u0026mdash;identified by configuration coordinates\u0026mdash;in\nconfiguration space.\n\n(_Configuration_ can also mean the actual [`Configuration`][2] object\nin the framework.)\n\nUsage Patterns\n==============\n\nApplication\n-----------\n\nApplications wishing to use the microBean™ Configuration project create\na [`Configurations`][0] object and then call its [`getValue()`][1]\nmethods.  The [`Configurations`][0] object is the centerpiece of the\nmicroBean™ Configuration framework.\n\nDeployment and Integration\n--------------------------\n\nIndividual configurations are represented by implementations of\nthe [`Configuration`][2] service provider interface.  These\nimplementations are loaded at [`Configurations`][0] [creation time][3]\nby the standard Java SE [`ServiceLoader` infrastructure][4].  To\nactivate a given [`Configuration`][2] implementation, put the name of\nits class on one line in a file named\n`META-INF/services/org.microbean.configuration.spi.Configuration`\nlocated on the classpath of the application.\n\nA [`Configuration`][2] implementation is responsible for determining\nwhether it contains a configuration value that is suitable for a\nsupplied set of configuration coordinates and a configuration\nproperty.  If it does not contain such a value, then it returns\n`null`.  If it _does_ contain such a value, then it must not only\nreturn the `String` value it houses, but also a set of configuration\ncoordinates for which that value is suitable.\n\nThe set of configuration coordinates returned is either exactly the\nset supplied to the [`Configuration`][2], or a subset of it.  This\ncauses the returned value to be seen as an _exact match_ or a merely\n_suitable match_.  You can think of matches in terms of specificity:\na configuration value that is said to exactly match a configuration\nproperty and a set of configuration coordinates is maximally specific;\na configuration value that is said to suitable match a configuration\nproperty and a set of configuration coordinates is less specific.\n\nConversion\n----------\n\nConfiguration values are, at their root, always `String`s.  They are\nconverted to other types by [`Converter`s][5].\nLike [`Configuration`][2] instances, [`Converter`s][5] are loaded by\nthe standard Java SE [`ServiceLoader` infrastructure][4].  To activate\na given [`Converter`][5] implementation, put the name of\nits class on one line in a file named\n`META-INF/services/org.microbean.configuration.spi.Converter`\nlocated on the classpath of the application.\n\nClients who wish to understand what [`Type`s][7] exist to which\n`String` configuration values may be converted may call\nthe [`Configurations#getConversionTypes()`][8] method.\n\nDispute Arbitration\n-------------------\n\nFrom time to time, a configuration property may have several values\nthat are suitable for it.  For example, for a hypothetical\nconfiguration property named `databaseUrl`, there may be a configuration\nvalue assigned to it for the configuration coordinates represented by\nthis listing:\n\n    environment=test\n    tenantId=34\n    \n...and a different value assigned to it suitable for this listing:\n\n    environment=test\n    dataCenter=Nevada\n    \nBoth sets of configuration coordinates represent suitable matches for application\nlocated in configuration space by the following coordinates:\n\n    locale=en_US\n    environment=test\n    region=west\n    dataCenter=Nevada\n    tenantId=34\n    \n...but neither is maximally specific.  So should the application use\nthe value suitable for the first listing, or the value suitable for\nthe second listing?\n\nThis is a _configuration dispute_.  Configuration disputes may be\nresolved by [`Arbiter`][6] instances.  Like [`Configuration`][2]\ninstances, [`Arbiter`s][6] are loaded by the standard Java\nSE [`ServiceLoader` infrastructure][4].  To activate a\ngiven [`Arbiter`][6] implementation, put the name of its class on\none line in a file named\n`META-INF/services/org.microbean.configuration.spi.Arbiter` located\non the classpath of the application.\n\n[0]: apidocs/org/microbean/configuration/Configurations.html\n[1]: apidocs/org/microbean/configuration/Configurations.html#getValue-java.util.Map-java.lang.String-\n[2]: apidocs/org/microbean/configuration/spi/Configuration.html\n[3]: apidocs/org/microbean/configuration/Configurations.html#Configurations--\n[4]: https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html\n[5]: apidocs/org/microbean/configuration/spi/Converter.html\n[6]: apidocs/org/microbean/configuration/spi/Arbiter.html\n[7]: https://docs.oracle.com/javase/8/docs/api/java/lang/reflect/Type.html\n[8]: apidocs/org/microbean/configuration/Configurations.html#getConversionTypes--\n[9]: apidocs/org/microbean/configuration/spi/ConfigurationValue.html\n[10]: https://microbean.github.io/microbean-configuration-api/\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrobean%2Fmicrobean-configuration","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrobean%2Fmicrobean-configuration","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrobean%2Fmicrobean-configuration/lists"}