The Client Libraries Group
Introduction
The Client LibrariesGroup iscomprised of developers who participate in the design,implementation, and maintenence of the Java client libraries. It isaconsolidation of the former2D,AWT,Sound,andSwing Groups.
Archived documentation for each of the consolidated Groups maybe found in the original Group pages:
These currently need some updates to remove obsolete informationbut there's still a lot of valid material there.
Community
Source code
The Client Libraries Group is responsible for the JDK source in thefollowing modules
Together these modules enable
- AWT applications - supporting integration with the desktop,display management, input events etc
- Swing applications, using Java and platformLook&Feels.
- creation of applications which conform to government andindustry standards for ATs
- Java Sound applications
- Java Beans
- Accelerated 2D rendering via OpenGL/D3D/Metal
- Imaging, color management, sophisticated text APIs,geometry
- Printing - both user interactive and API controlled.
- Headless server support for software rendering of Java 2D toand from image formats
Like much of the rest of the JDK as much as possible of theimplementation is written using Java, but because of the nature ofplatform integration there is still a vast amount of native code,much of it platform-specific. The majority of shared(cross-platform) native code is widely used open source librarieswritten in C or C++ for specialised functions such as fontrasterisation and color management.
Demos
Additionally the Client Libraries Group maintains several demoapplications. Not meant as an example of modern standard codingpractice, but principally meant as named, to "demo" thefunctionality of the APIs :
https://github.com/openjdk/jdk/tree/master/src/demo/share/jfc.They are also useful for manual testing of this functionality andit is not unusual for a reviewer to suggest running them to verifya fix.
Tests
The jtreg tests for the Client Libraries Group code are somewhatscattered around, since the tests tend to be organised by packagename and there are plenty of those. Many of the tests areautomated, but also many are manual. An incomplete list ofdirectories for these tests is
The ongoing work of the Client Libraries Group
There's no plan to do "large new features' for Swing, Java2D etcbut
- keeping it working well on all the new platform versions andAPI stacks is keeping us busy
- Enhancements (ie smaller features) are still happening
- JEPs that aren't just "maintenance" JEPs are not absolutelyruled out, but they do need to represent something that will be along term benefit.
Recent, Current and Upcoming Projects/JEPs etc
- Test stabilisation (JDK11->ongoing) - we have put a lot ofeffort into improving tests which fail for random reasons such asbeing timing sensitive and overall making tests more robust. Thishas enabled us to rely on automated tests much more than before toverify fixes. There's still a lot to do since many tests remainProblem Listed because they fail for such reasons - or in somecases product bugs we need to fix.
- Applet deprecation (JDK 17) - with the demise of Java Pluginthe java.applet package is obsolete for most purposes. So allreferneces to Applets in the Java API have been deprecated forremoval. There are however lots of valuable tests written asApplets so we need to find an answer to that first.
- MacOS ARM (JDK 17) - internally the Apple JNF framework wasused extensively and since this was not available on Apple Siliconwe had to replace it.
- MacOS A11Y (ongoing) - the current macOS APIs used for A11Yhave been deprecated for years and we need to migrate to the newones before they are removed
- Metal for macOS (JDK17) - this was a 2 year effort that is nowmostly complete to replace the OpenGL 2D rendering pipeline onmacOS with a new one using Apple's Metal API
- Wayland (TBD) - a replacement for the X11 implementaton ofAWT/2D on Linux
- Windows 11 (TBD) - not yet scoped - hopefully it is mostly acase of verification
Some client contributors also contribute to the OpenJFX Project- there's a more or less 100% overlap in the skill set !
Group Policies.
First, refer to the
OpenJDKDeveloper's Guide for JDK-wide policies, processes andpractices. However there are some extra considerations for theclient area.
Proposing a change
Like most other groups in OpenJDK for anything that is more than alocalised bug fix, we prefer to see issues raised and discussedbefore we see a PR which may reflect a different direction thanwe'd want. This is especially true if you are a new contributor.The client-libs-dev@openjdk.org list is the place to go for thesediscussions
"Drive-by" contributions - will get a hard look because weprefer folks who contribute to stick around and maintain thosecontributions.
There are additional challenges of contributing to the ClientLibraries Group area compared to some other areas since so much ofwhat we do is platform-specific that you may need access tomultiple platforms and be prepared to do a lot of cross-platformand manual testing. Depending on your reviewers for that isn'tlikely to speed along your contribution.
Guidelines on what kinds of changes we would like to see - ornot see.
Preamble
Every change in JDK code carries risk of changes in behaviourwhich adversely affect applications. Generally we are looking toimprove the functionality and capability and sometimes performanceof the platform without that negative consequence. We do have manythousands of tests, but they are inevitably incomplete in coverage.So we need to ask ourselves, whether each change is worthwhile andsome may not be no matter how well intentioned.
A lot of proposed changes may be broadly categorised as"internal code only" changes. This includes more than moving filesand functions around. If a change being proposed is just a "codeclean up", or "optimization" it may be of low value relative to thecosts and risks. It is perhaps most succinctly characterised as anychange that changes the JDK product source code without makingthings perceptibly better for applications. There isn't an agreedon single term for all of this, "refactoring" covers some of it,and all of the abovall of the above is the intended reading of thatterm when used in this doc.
So the guidelines that follow are something that should be readby developers before spending a lot of time on a proposed fix.
And is important to ensure that even a "cleanup" code change hasbeen exercised by a test, so seeTesting a Change
Guidelines and criteria that relate to changes we DO want
These do not automatically guarantee a change will be accepted, butif one of these is the focus of a change, it is much more likely tobe accepted.
- Correctness changes are welcome.
If there's something that affects program correctness, that'simportant. And to broaden this, what is most valuable is fixing ofall kinds bugs that really make things better for applications inways they can detect. i.e functional bugs - Making the JDK code "more robust" for applications.
Such changes are probably good, where "more robust" means say usingsome new platform API which is newer. - Changes which make the platform more secure.
Changes which are intended to increase the overall security of theplatform following secure coding practices and using appropriateplatform APIs for that are usually welcome. The exception might beif it is a potentially destabilising change in code where there isonly a theoretical problem. NOTE: if you think you found a realsecurity bug that might compromise the platform, then you shouldfollow the processhere
Guidelines and criteria that might cause changes to be lesslikely to be accepted
These do not automatically disqualify a change, but if any of thesecharacterise a proposed change without some benefit from the abovelist, you should think twice, and be ready to justify it, andperhaps for it ultimately not to be accepted.
- Stable code is not a good candidate for refactoring.
Much of the code in java.desktop has been stable for a long time,and if it is stable, perhaps it has few bugs or need for change. Sochanges in stable code naturally have a higher risk to rewardratio. - Performance changes need to really matter
Can you demonstrate a user perceptible change ?
If you can't measure the change, or you measure it and is small andperhaps once per VM then maybe it isn't worth it.
Some API may be more performant than another but in UI applicationsthe CPU is often just waiting for the user. Collection class "A"may be faster than class "B" as demonstrated in some benchmarks,but if that's when there are 10,000 entries and client code neverhas more than 100 and the CPU can traverse the collection fasterthan the user can move a mouse one pixel .. what have you added? - Modernising API usage needs to be more than for its ownsake.
"There's a cool new feature in JDK 17/C++ 20/etc", is not enough ifyou need to update stable code to use it, and there's no otherbenefit. - Be a subject matter expert, not just a language expert.
Fixes that say "this is a better way of writing this code" are notguaranteed to be safe, no matter how much the submitter writesclaims like "safe, simple, more clear". A change of behaviour isalways possible and unless you understand the code you are changingat more than the core language/API level, and have looked intoappropriate tests and can speak to the risks, then you should firstfind a subject matter expert to discuss it with. - Large changes - whether by complexity or volume - are morerisky.
For volume, you may think of this as no different than proposing 10individual small unrelated changes but what happens in practice isthere's a focus on say 5-6 of these and no one really looks hard atthe other 4-5. For complexity, even small changes that are hard tounderstand and test may be risky. - Backports may be more costly in refactored code.
This is perhaps less a guideline than a warning. If some file inmainline has been refactored and there's then an importantfunctional bug found that needs to be fixed and backported, thenthe more similar the code across releases then the morestraightforward the backport. Refactoring means a backport may bealmost a new bug fix. So this is another added cost to weighagainst the benefit of the change. - There is no such thing as a zero risk change.
Once you start changing product code, its very hard to proveotherwise. Supposedly equivalent APIs may not be the drop inreplacement you thought. Even removing dead code (!) hasmysteriously caused performance regressions - but yes in generalremoving dead code is a good thing.
Finally
The area lead will always have discretion to evolve theseguidelines, and if there's a PR that falls between the lines, todecide which side it falls. Amendments to these guidelines mayfollow such cases.
Source code conventions
All source code should follow the standard Java source codeconventions as well as jcheck rules. Some of the most common onesto remember are :
- All lines <= 80 chars
- No tabs, indents are always 4 spaces.
- if blocks should use { .. } even for one line
Consult
CodeConventions for the Java(TM) Programming Language for the fulllist.
Testing a change
Do not overlook testing. Test before even submitting yourPR.
- Run all available tests on all applicable platforms.
- For client this means the jtreg "jdk_desktop" test group - at aminimum.
- Do NOT rely on github actions for testing.
- Do NOT think that "tier1 + tier2 + tier3" gives you the neededcoverage of client tests.
- Make sure your changes are touched by some test.
- If you can, write a test that directly passes or fails based onthe changes (seeRegression tests below).
- This is often not possible for "cleanup" fixes without digginginto JDK internals So if not possible try to write a new test thatat least exercises this code.
Regression tests
Tests should be provided unless clearly infeasible. Automatedtests are desirable. SQE rarely run manual tests. Nor will otherdevelopers. Don't give up easily. There are tests that render to aBufferedImage and analyse the resulting contents to see if theybehaved correctly, so writing automated tests is possible in morecases than immediately apparent.
Code Reviews
Code reviews are one of the most important mechanisms we havefor integrating and shipping good, solid, compatible code. Reviewsare also an invaluable source of education for all of us, and agreat mechanism for ensuring consistent code quality, as we allread and learn from reading each other's code.
The standard requirement in the JDK project is for one reviewerto approve the fix. The Java Client Library Group has alwaysstandardized on two approvals - where at least one must have theReviewer role. Historically this was addressed entirely by socialconventions but today the tooling plays a role - and the JDKproject is set up to mark a PR as ready for integration after asingle approval by a person with the Reviewer role - which is notconsistent with the Client Libraries policy. The tooling cannotautomatically enforce this on a per-module basis and it is notreasonable to expect others to add "/reviewers 2" to every PR. Thefixer therefore needs to understand the policies and wait for asecond approval.
Note that there may sometimes be confusion between the terms"reviewers" and "approvers". The tooling tends to use the wordreview/reviewer where it really means "Approval by someone with theReviewer role". Anyone with an OpenJDK github role can "review" afix - meaning make comments, and even add an Approval. And indeedwe encourage non-Reviewers to actively review PRs. So really youonly have two "reviews" when you have two "approvals". If more thanone person has expressed a viewpoint on a fix, and say one hasapproved and the other made substantive comments, without expresslyapproving, then they are active in reviewing that fix. So you needto take the nature of their comments into consideration, and allowthem reasonable time (let's say 24 hrs during the work week fornon-urgent fixes) to respond to any written answers or code updatesand add their approval before pushing. This is both for courtesy,and so that someone who has spent time on the review may becredited in the commit, and to ensure that they have at least achance to agree you've addressed their concerns. . Fixers who arenot also Reviewers for the client area should consult a clientReviewer to determine if one reviewer is enough. Potential reasonsfor granting that exception are enumerated below.
The choice of which people review the code is not usually up tothe fixing engineer and and who should review it depends upon eachspecific situation, but some general guidelines are:
- At least one reviewer should have some familiarity with thistechnology and/or area of the code
- Two reviewers should be looking at everything, so if onereviewer is chosen for only a segment of any particular change, youshould get other reviewers to review the sections that are leftwith only one reviewer.
It is the responsibility of the implementing engineer to respondto the reviewers, and their concerns, and make the final codeadhere to changes agreed upon by the engineer and thereviewers.
It is the responsibility of the reviewers to provide timelyreviews, and understand (to the extent possible) and agree to thechanges that the engineer has implemented; when the code is putbackto the repository,the reviewers are also takingresponsibility for these changes. We can only have goodreviews, and good resulting code, if the reviewers take their jobsseriously and review the changes thoroughly. Given the costs andhassles of maintaining backward-compatible code indefinitely, wecannot risk code going in that is only cursorily reviewed; it isfar easier and cheaper to catch flaws in the review process than itis to fix them in bugs and escalations later on.
The most common exceptions to the two reviewer policy would befor
- Documentation updates that do not affect the specification
- Identical backports previously reviewed by two reviewers
- Trivial test only changes.
- Time critical, simple changes such as backing out a buildbreakage.
- Extra discretion is granted to the most experienced reviewersin the area to say if one reviewer is enough or even that threereviewers are needed.
