The Client Libraries Group
Introduction
The Client Libraries Group is comprised of developers who participate in the design, implementation, and maintenence of the Java client libraries. It is a consolidation of the former 2D, AWT, Sound, and Swing Groups.
Archived documentation for each of the consolidated Groups may be found in the original Group pages:
These currently need some updates to remove obsolete information but there's still a lot of valid material there.Community
- Mailing Lists
- Members
Like all "areas" the members of the group are not the entireity of those contributing.We hope to be able to invite additional long time contributors to the group on an ongoing basis, reflecting people who have had continual involvement and expect to remain involved in the future.
Source code
The Client Libraries Group is responsible for the JDK source in the following modules- java.desktop https://github.com/openjdk/jdk/tree/master/src/java.desktop
and
https://github.com/openjdk/jdk/tree/master/make/modules/java.desktop
this is the vast majority of the code for creating desktop clients as well as headless rendering support - java.datatransfer https://github.com/openjdk/jdk/tree/master/src/java.datatransfer
and
https://github.com/openjdk/jdk/tree/master/make/modules/java.datatransfer
separated for use by code that does not need the entire desktop module - jdk.accessibility https://github.com/openjdk/jdk/tree/master/src/jdk.accessibility
and
https://github.com/openjdk/jdk/tree/master/make/modules/jdk.accessibility
support for the JavaAccessBridge for Windows used by Assistive Technologies (ATs) - jdk.unsupported.desktop
https://github.com/openjdk/jdk/tree/master/src/jdk.unsupported.desktop
and
https://github.com/openjdk/jdk/tree/master/make/modules/jdk.unsupported.desktop
a small number of non-standard APIs mostly for interop with OpenJFX
Together these modules enable
- AWT applications - supporting integration with the desktop, display management, input events etc
- Swing applications, using Java and platform Look&Feels.
- creation of applications which conform to government and industry 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 to and from image formats
Like much of the rest of the JDK as much as possible of the implementation is written using Java, but because of the nature of platform 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 libraries written in C or C++ for specialised functions such as font rasterisation and color management.
Demos
Additionally the Client Libraries Group maintains several demo applications. Not meant as an example of modern standard coding practice, but principally meant as named, to "demo" the functionality of the APIs : https://github.com/openjdk/jdk/tree/master/src/demo/share/jfc. They are also useful for manual testing of this functionality and it is not unusual for a reviewer to suggest running them to verify a fix.Tests
The jtreg tests for the Client Libraries Group code are somewhat scattered around, since the tests tend to be organised by package name and there are plenty of those. Many of the tests are automated, but also many are manual. An incomplete list of directories for these tests is- https://github.com/openjdk/jdk/tree/master/test/jdk/com/sun/java
- https://github.com/openjdk/jdk/tree/master/test/jdk/demo/jfc
- https://github.com/openjdk/jdk/tree/master/test/jdk/java/awt
- https://github.com/openjdk/jdk/tree/master/test/jdk/java/beans
- https://github.com/openjdk/jdk/tree/master/test/jdk/javax/accessibility
- https://github.com/openjdk/jdk/tree/master/test/jdk/javax/print
- https://github.com/openjdk/jdk/tree/master/test/jdk/javax/sound
- https://github.com/openjdk/jdk/tree/master/test/jdk/javax/swing
- https://github.com/openjdk/jdk/tree/master/test/jdk/sanity/client
- https://github.com/openjdk/jdk/tree/master/test/jdk/sun/awt
- https://github.com/openjdk/jdk/tree/master/test/jdk/sun/java2d
The ongoing work of the Client Libraries Group
There's no plan to do "large new features' for Swing, Java2D etc but- keeping it working well on all the new platform versions and API stacks is keeping us busy
- Enhancements (ie smaller features) are still happening
- JEPs that aren't just "maintenance" JEPs are not absolutely ruled out, but they do need to represent something that will be a long term benefit.
Recent, Current and Upcoming Projects/JEPs etc
- Test stabilisation (JDK11->ongoing) - we have put a lot of effort into improving tests which fail for random reasons such as being timing sensitive and overall making tests more robust. This has enabled us to rely on automated tests much more than before to verify fixes. There's still a lot to do since many tests remain Problem Listed because they fail for such reasons - or in some cases product bugs we need to fix.
- Applet deprecation (JDK 17) - with the demise of Java Plugin the java.applet package is obsolete for most purposes. So all referneces to Applets in the Java API have been deprecated for removal. There are however lots of valuable tests written as Applets so we need to find an answer to that first.
- MacOS ARM (JDK 17) - internally the Apple JNF framework was used extensively and since this was not available on Apple Silicon we had to replace it.
- MacOS A11Y (ongoing) - the current macOS APIs used for A11Y have been deprecated for years and we need to migrate to the new ones before they are removed
- Metal for macOS (JDK17) - this was a 2 year effort that is now mostly complete to replace the OpenGL 2D rendering pipeline on macOS with a new one using Apple's Metal API
- Wayland (TBD) - a replacement for the X11 implementaton of AWT/2D on Linux
- Windows 11 (TBD) - not yet scoped - hopefully it is mostly a case 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 OpenJDK Developer's Guide for
JDK-wide policies, processes and practices. However there are some
extra considerations for the client area.
Proposing a change
Like most other groups in OpenJDK for anything that is more than a localised bug fix, we prefer to see issues raised and discussed before we see a PR which may reflect a different direction than we'd want. This is especially true if you are a new contributor. The client-libs-dev@openjdk.java.net list is the place to go for these discussions"Drive-by" contributions - will get a hard look because we prefer folks who contribute to stick around and maintain those contributions.
There are additional challenges of contributing to the Client Libraries Group area compared to some other areas since so much of what we do is platform-specific that you may need access to multiple platforms and be prepared to do a lot of cross-platform and manual testing. Depending on your reviewers for that isn't likely to speed along your contribution.
Source code conventions
All source code should follow the standard Java source code conventions as well as jcheck rules. Some of the most common ones to remember are :- All lines <= 80 chars
- No tabs, indents are always 4 spaces.
- if blocks should use { .. } even for one line
Regression tests
Tests should be provided unless clearly infeasible. Automated tests are desirable. SQE rarely run manual tests. Nor will other developers. Don't give up easily. There are tests that render to a BufferedImage and analyse the resulting contents to see if they behaved correctly, so writing automated tests is possible in more cases than immediately apparent.
Code Reviews
Code reviews are one of the most important mechanisms we have for integrating and shipping good, solid, compatible code. Reviews are also an invaluable source of education for all of us, and a great mechanism for ensuring consistent code quality, as we all read and learn from reading each other's code.
The standard requirement in the JDK project is for one reviewer to approve the fix. The Java Client Library Group has always standardized on two approvals - where at least one must have the Reviewer role. Historically this was addressed entirely by social conventions but today the tooling plays a role - and the JDK project is set up to mark a PR as ready for integration after a single approval by a person with the Reviewer role - which is not consistent with the Client Libraries policy. The tooling cannot automatically enforce this on a per-module basis and it is not reasonable to expect others to add "/reviewers 2" to every PR. The fixer therefore needs to understand the policies and wait for a second approval.
Note that there may sometimes be confusion between the terms "reviewers" and "approvers". The tooling tends to use the word review/reviewer where it really means "Approval by someone with the Reviewer role". Anyone with an OpenJDK github role can "review" a fix - meaning make comments, and even add an Approval. And indeed we encourage non-Reviewers to actively review PRs. So really you only have two "reviews" when you have two "approvals". If more than one person has expressed a viewpoint on a fix, and say one has approved and the other made substantive comments, without expressly approving, then they are active in reviewing that fix. So you need to take the nature of their comments into consideration, and allow them reasonable time (let's say 24 hrs during the work week for non-urgent fixes) to respond to any written answers or code updates and add their approval before pushing. This is both for courtesy, and so that someone who has spent time on the review may be credited in the commit, and to ensure that they have at least a chance to agree you've addressed their concerns. . Fixers who are not also Reviewers for the client area should consult a client Reviewer to determine if one reviewer is enough. Potential reasons for granting that exception are enumerated below.
The choice of which people review the code is not usually up to the fixing engineer and and who should review it depends upon each specific situation, but some general guidelines are:
- At least one reviewer should have some familiarity with this technology and/or area of the code
- Two reviewers should be looking at everything, so if one reviewer is chosen for only a segment of any particular change, you should get other reviewers to review the sections that are left with only one reviewer.
It is the responsibility of the implementing engineer to respond to the reviewers, and their concerns, and make the final code adhere to changes agreed upon by the engineer and the reviewers.
It is the responsibility of the reviewers to provide timely reviews, and understand (to the extent possible) and agree to the changes that the engineer has implemented; when the code is putback to the repository, the reviewers are also taking responsibility for these changes. We can only have good reviews, and good resulting code, if the reviewers take their jobs seriously and review the changes thoroughly. Given the costs and hassles of maintaining backward-compatible code indefinitely, we cannot risk code going in that is only cursorily reviewed; it is far easier and cheaper to catch flaws in the review process than it is to fix them in bugs and escalations later on.
The most common exceptions to the two reviewer policy would be for
- 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 build breakage.
- Extra discretion is granted to the most experienced reviewers in the area to say if one reviewer is enough or even that three reviewers are needed.