This section takes you through how you can help apply StringBuffer to StringBuilder replacements in the OpenJDK and submit patches, improving the code quality in Java itself! Any questions, comments, feedback etc please send to the '''[mailto:firstname.lastname@example.org Adopt OpenJDK group]''' (if you have no luck there, try posting to the '''[mailto:email@example.com JUG leaders list]''').
The Adopt OpenJDK reviewers will liaise with the following sponsors to get patches into the right groups.
* Stuart Marks --> core-libs.
* Artem Ananiev --> swing and awt (client)
=Instructions for instructors=
See [[GeneralInstructionsForSmallChanges#Instructions_for_instructors|Instructions for instructors]]
=What fixes are accepted (The barrier for patches)=
The barrier for the OpenJDK committers to accept a patch (even one as seemingly simple as a StringBuffer to StringBuilder conversion) is exceptionally high. The instructors will be checking a wide variety of conditions before your patch can be accepted. Please survey the list below and try to ensure your patch meets the quality bar. This information was provided by Joel Borggren-Franck, Tobias Frech, Mike Duigou and Alan Bateman
* StringBuffers should not be assigned to an instance or static field of the class in this method or any other method which is called from within that method.
** Theoretically you risk concurrent access from another Thread then. That's a quite unusual design if a StringBuffer is used that way, but there you have it.
* If you assign a StringBuffer to a field then it is escaping. In this context escaping means getting out of the method it is a local variable in.
==Extra StringBuffer escaping analysis==
There are many ways the StringBuffer can escape
* By assignment to a field
* By using it as a parameter to a method/constructor
* With an exception that gets thrown
* By assign it to an array that isn't local and provably non-escaping
* By returning it
There may be other ways we haven't thought of...
In some of this cases the StringBuffer could be proven to not escape by further analysis but this is very easy to get wrong. So for this purpose, if it has a chance of leaving the method the StringBuffer is a local variable in, consider it as escaping.
Expanding a bit on this, you have two cases:
# The StringBuffer provably doesn't escape. In this case as others have said, the conversion will be safe. Beware of aliasing, in general there can be many references to the same StringBuffer, none of them can escape.
# Given that the StringBuffer can escape, the transformation isn't automatically safe, but neither automatically unsafe. But in this case the analysis gets much more complicated. It might not be worth the effort. The VM is very good at reducing cost for locks used only by one thread. So if your escaping StringBuffer doesn't require the synchronization then you won't loose that much by having it synchronize (but if you actually need it well then the conversion wasn't safe to begin with).
See [[GeneralInstructionsForSmallChanges#Hardware_Requirements|Hardware Requirements]]
See [[GeneralInstructionsForSmallChanges#Attendee_Instructions|Attendee Instructions]]
==Run the jdk library build==
See [[GeneralInstructionsForSmallChanges#Run_the_jdk_library_build|Run the JDK build]]
==Look for StringBuffers to convert==
# Instances of StringBuffers that are created in a method, and which don't escape out of their scope.
## There are a few instances where fields are converted, but they are in classes that are not serializable, for example in LogStream.
## A lot of the changes are in the toString() methods, but there are more frequently used methods in RandomAccessFile (for example, readLine()) and Double that use StringBuffer.
## Instances where there really is no synchronization that is going on (to the best of your ability)
Remember not to overlap with other efforts that are going on. If you're part of a global hack day, your instructor(s) will be co-ordinating with other teams. Fix some warnings in the source code (these are mainly under ''$SOURCE_CODE/jdk8_tl/jdk/src/share/classes''). Depending on whether you're using the new or old build system, you'll then want to execute a build.
=== New Build ===
tail -f build.log
=== Old Build ===
tail -f build.log
== Check the log ==
When the build is done you should see something in the build.log file like:
Done Processing SUBDIRS: tools java javax sun com org sunw jpda mkdemo mksample launchers
linux i586 1.8.0-internal build finished: 12-04-21 19:08
Check in the ''build.log'' file that the warnings you fixed are gone
'''NOTE:''' The build will be much faster the 2nd time around, it only compiles in and around the area that you have changed.<br />
'''NOTE:''' You should see a much smaller set of warnings as the ''build.log'' only shows the results of the smaller build (i.e. What you've changed).
==Run jtreg tests==
See [[GeneralInstructionsForSmallChanges#Run_jtreg_tests|Run jtreg tests]]
==Repeat the Process==
See [[GeneralInstructionsForSmallChanges#Repeat_the_Process|Repeat the process]]
See [[GeneralInstructionsForSmallChanges#Create_Patches|Create Patches]]
See [[GeneralInstructionsForSmallChanges#Submit_Patches|Submit Patches]]
Back to [[Adopt OpenJDK]]