Find JSRs
Submit this Search


Ad Banner
 
 
 
 

Summary  |  Proposal  |  Detail (Summary & Proposal)  |  Nominations
JSRs: Java Specification Requests
JSR 382: Configuration API 1.0

Stage Access Start Finish
JSR Review Ballot   26 Sep, 2017 09 Oct, 2017
JSR Review   12 Sep, 2017 25 Sep, 2017
Status: Active
JCP version in use: 2.10
Java Specification Participation Agreement version in use: 2.0


Description:
Provide applications and microservices means to obtain configuration properties through several environment-aware sources both internal and external to the application and made available through dependency injection or lookup.

Expert Group Transparency:
  Public Project Page
  Public Communications
  Issue Tracking

Team

Specification Leads
  Emily JIANG Eclipse Foundation, Inc
  Mark Struberg Eclipse Foundation, Inc
Expert Group
  Sebastian Daschner Eclipse Foundation, Inc
: Emily JIANG
Eclipse Foundation, Inc
: Mark Struberg
  Sparta Systems
: John Ament
Tomitribe
: David Blevins
Tomitribe
: Jean-Louis Monteiro
  Trivadis AG
: Anatole Tresch
Contributors
  Mitsubishi UFJ Information Technology, Ltd.
: Hiromi Takahashi
   

Original Java Specification Request (JSR)

Identification | Request | Contributions | Additional Information

Section 1. Identification

Submitting Member: Eclipse Foundation

Name of Contact Person: Mike Milinkovich

E-Mail Address: mike.milinkovich@eclipse.org

Telephone Number: +1 613 224 9461

Fax Number: +1 613 224 5172


Specification Lead Member: Eclipse Foundation

Specification Leads: Emily Jiang, Mark Struberg

E-Mail Addresses: emijian6@googlemail.com, markstruberg@gmail.com

Telephone Numbers: +44 1962 816278, +43 664 608 444 12 44

Fax Number: -


Initial Expert Group Membership:

Eclipse Foundation, IBM, Red Hat, Tomitribe, Mark Struberg, London Java Community, Ivar Grimstad, Adam Bien, John Ament

Supporting this JSR:

Eclipse Foundation, IBM, Red Hat, Tomitribe, Mark Struberg, London Java Community, Ivar Grimstad, Adam Bien, John Ament



Section 2: Request

2.1 Please describe the proposed Specification:

The Configuration API JSR is based on innovation in the Eclipse MicroProfile Config project carried out by several contributors both corporate and individual with the goal of identifying the minimum viable solution for application and microservice configuration data and with the hope of future standardization via the JCP. This JSR should be viewed as being submitted by all members of the Eclipse MicroProfile community.

The majority of applications need to be configured based on a running environment. It must be possible to modify configuration data from outside an application so that the application itself does not need to be repackaged. Further, sources of configuration must take into account today's microservice architectures and container environments.

- Sources of Configuration -

We propose an API that allows configuration data to come from different locations and in different formats. Anticipated sources may include:
* Properties files in the application
* Java System properties
* Java environment variables
* YAML, XML or similar files coerced to properties format
* Database or NoSQL storage
* REST calls to external systems
* Containerized environments, such as Kubernetes, that support environment variables

These sources are abstracted behind a ConfigSource interface that allows for composition of several sources and means to register and order sources for precedence. If the same property is defined in multiple ConfigSources, we apply a policy to specify which one of the values will effectively be used.

Under some circumstances, some data sources may change dynamically. The changed values should be immediately fed into the client without the need for restarting the application. This requirement is particularly important for microservices running in a cloud environment.

- Third-Party ConfigSources -

A minimum number of ConfigSources will be required by Configuration API implementations. It is the expectation of the JSR that many of the anticipated ConfigSources listed above will not be provided by Configuration API implementations and will instead be provided by third-party ConfigSource implementations. A goal of the JSR is to enable that ecosystem as much as possible. The JSR may explore means for configuration sources to be tested for compliance, however this should be considered nice-to-have and not considered a strict requirement of the JSR.

- Exposing Configuration to the Application -

We propose an @ConfigProperty annotation that allows for properties supplied by ConfigSources to be named and injected into the code via CDI with default values. Injected values are not limited to String and may be strongly-typed, such as URI, URL, File, InetAddress. The JSR will provide well-defined rules for String-to-Java conversion and means for application developers to support their own custom types.

We propose a Config object as the center of the API to represent a composite and canonical view of all ConfigSources that supports property lookup by the application. This portion of the API is explicitly designed to function without dependency on CDI or other non-Java SE dependencies and intended for use in plain Java applications or bootstrapping server environments.

- Influences and History -

There are a number of Config projects which inspired this API, such as:
* DeltaSpike Config (http://deltaspike.apache.org/documentation/configuration.html)
* Extracted parts of DeltaSpike Config (https://github.com/struberg/javaConfig/)
* Apache Tamaya (http://tamaya.incubator.apache.org/)
* Tomitribe Sabot (https://tomitribe.io/p/sabot)
* Apache Geronimo Config (https://svn.apache.org/repos/asf/geronimo/components/config/trunk) * WebSphere Liberty 2017 Betas (https://developer.ibm.com/wasdev/)

2.2 What is the target Java platform? (i.e., desktop, server, personal, embedded, card, etc.)

Java EE and Java SE are the target platforms.

2.3 The Executive Committees would like to ensure JSR submitters think about how their proposed technology relates to all of the Java platform editions. Please provide details here for which platform editions are being targeted by this JSR, and how this JSR has considered the relationship with the other platform editions.

The Configuration API is designed for both the Java EE and Java SE platform environments. It is expected that Configuration 1.0 will be considered for inclusion in the Java Platform, Enterprise Edition 9.

2.4 What need of the Java community will be addressed by the proposed specification?

Currently, application developers store and pull configuration information from multiple sources using the APIs supported by those sources. This directly couples the application to configuration sources, making applications less flexible. In addition, handling dynamic configuration changes needs to be managed by developers for each source. This Configuration API provides a configuration mechanism external to the application using a consistent API, and allows for a more dynamic access and updates to the runtime environment.

2.5 Why isn't this need met by existing specifications?

See 2.4.

2.6 Please give a short description of the underlying technology or technologies:

See 2.1.

2.7 Is there a proposed package name for the API Specification? (i.e., javapi.something, org.something, etc.)

javax.config.*

2.8 Does the proposed specification have any dependencies on specific operating systems, CPUs, or I/O devices that you know of?

No.

2.9 Are there any security issues that cannot be addressed by the current security model?

No.

2.10 Are there any internationalization or localization issues?

No.

2.11 Are there any existing specifications that might be rendered obsolete, deprecated, or in need of revision as a result of this work?

No.

2.12 Please describe the anticipated schedule for the development of this specification.

Q4 2017 Expert Group formed
Q1 2018 Early Draft
Q2 2018 Public Review
Q3 2018 Final Release (in time for Java EE 9)

2.13 Please describe the anticipated working model for the Expert Group working on developing this specification.

Primary means of communication will be via email and/or the groups.io forum facilities. Conference calls or hangouts are also good for communication. Face-to-face meetings are not anticipated, but may be arranged, if necessary.

2.14 Provide detailed answers to the transparency checklist, making sure to include URLs as appropriate:

Q: Is the schedule for the JSR publicly available, current, and updated regularly?
A: Yes, this will be available on the JSR Update page.

Q: Can the public read and/or write to a wiki for the JSR?
A: Yes, the public can read/write to the wiki for the JSR.

Q: Is there a publicly accessible discussion board for the JSR that you read and respond to regularly?
A: Yes, the use of groups.io will be used for these discussions.

Q: Have you spoken at conferences and events about the JSR recently?
A: Yes, as part of the Eclipse MicroProfile project.

Q: Are you using open-source processes for the development of the RI and/or the TCK?
A: Yes, currently all of the code and spec development is performed under the Eclipse Foundation governance model.

Q: What are the Terms of Use required to use the collaboration tools you have prepared to use with the Expert Group, so that prospective EG members can judge whether they are compatible with the JSPA?
A: We will use the collaboration tools specified for the other Java EE projects (github and groups.io). In addition, we may use mailing lists, Google Groups and Hangouts as necessary.

Q: What is the location of your publicly-accessible Issue list? In order to enable EC members to judge whether Issues have been adequately addressed, the list must make a clear distinction between Issues that are still open, Issues that have been deferred, and those that are closed, and must indicate the reason for any change of state.
A: All issues will be tracked via the github repository created for this Configuration API project.

Q: What is the mechanism for the public to provide feedback on your JSR?
A: The groups.io forum will be used to gather input from both the Expert Group as well as other interested parties.

Q: Where is the publicly-accessible document archive for your Expert Group?
A: A new git repository dedicated to the JSR will be created in Github under the Eclipse organization.

Q: Does the Community tab for my JSR have links to and information about all public communication mechanisms and sites for the development of my JSR?
A: It will once we get approval for this Configuration API JSR.

Q: Do you have a Twitter account or other social networking feed which people can follow for updates on your JSR?
A: We currently use @MicroProfileIO for anything related to MicroProfile. And, there is the @JavaEE twitter account. Many of us also have individual Twitter accounts where we can feed information about the Configuration API.

Q: Which specific areas of feedback should interested community members (such as the Adopt-a-JSR program) provide to improve the JSR (please also post this to your Community tab)?
A: Since this is a new JSR, we would welcome feedback on all aspects of the JSR. We would like to call out that the value of this JSR dramatically increases the more ConfigSources it gains from people in the community. We encourage Adopt-a-JSR programs to have hackathons and help lead efforts to create and share ConfigSources. The JSR will provide means for these to be listed and creators to be credited, tweeted, and celebrated.

2.15 Please describe how the RI and TCK will de delivered, i.e. as part of a profile or platform edition, or stand-alone, or both. Include version information for the profile or platform in your answer.

The RI and TCK will be delivered as standalone entities. But, we would expect these to be incorporated into Java EE 9 RI (Glassfish) and the overall CTS bucket.

2.16 Please state the rationale if previous versions are available stand-alone and you are now proposing in 2.13 to only deliver RI and TCK as part of a profile or platform edition (See sections 1.1.5 and 1.1.6 of the JCP 2 document).

N/A

2.17 Please provide a description of the business terms for the Specification, RI and TCK that will apply when this JSR is final.

The specification will be licensed using the standard specification license (see http://jcp.org/aboutJava/communityprocess/speclead/final-license.txt).

The RI and TCK will be licensed via the Apache license (see http://www.apache.org/licenses/LICENSE-2.0.html)

2.18 Please describe the communications channel you have established for the public to observe Expert Group deliberations, provide feedback, and view archives of all Expert Group communications.

Groups.io

2.19 What is the URL of the Issue Tracker that the public can read, and how does the public log issues in the Issue Tracker?

Github Issues when our individual repo is created in the Eclipse organization of Github.

2.20 Please provide the location of the publicly accessible document archive you have created for the Expert Group.

See 2.19





Section 3: Contributions

3.1 Please list any existing documents, specifications, or implementations that describe the technology. Please include links to the documents if they are publicly available.

MicroProfile Config 1.0
Proposal: https://github.com/eclipse/microprofile-evolution-process/blob/master/proposals/0001-config.md
Specification: https://github.com/eclipse/microprofile-config/blob/master/spec/src/main/asciidoc/microprofile-config-spec.asciidoc
Code: https://github.com/eclipse/microprofile-config

3.2 Explanation of how these items might be used as a starting point for the work.

The MicroProfile community is dedicated to provide an innovative sandbox for the development of specifications and APIs that would eventually find their way into JCP JSRs.

We consider these materials a starting point to spur discussion and demonstrate the ideas while still leaving the JSR EG room for input, API changes, new perspectives, and new features.





Section 4: Additional Information

4.1 This section contains any additional information that the submitting Member wishes to include in the JSR.

The Eclipse MicroProfile project is excited to submit our first JSR as a community and follow through on our mission to incubate ideas and fuel the standards process through involvement in the JCP.

We'd like to thank the following people for preparing this proposal: * Kevin Sutter, IBM
* David Blevins, Tomitribe
* John Clingan, Red Hat