| 6975f84c2ed72e1e26d20190b6f318718c849008 |
|
01-Mar-2017 |
Tobias Thierer <tobiast@google.com> |
Make Android patch docs in ojluni more consistent with style guide
This CL consists of an automated and a manual part (originally
reviewed as separate CLs, then squashed together before submitting
in order to minimize the number of times each Android-changed line
is touch, since that makes future git archaeology on these simpler).
Automated part: Run the following command (performs regex replacements):
find ojluni -name \*\.java | xargs sed -i \
-e 's/Android[- ]changed/Android-changed/ig' \
-e 's/Android-changed :/Android-changed:/g' \
-e 's/Android-changed \(BEGIN\|END\)/\1 Android-changed/g' \
-e 's/Android-changed - /Android-changed: /g' \
-e 's/Android[- ]removed/Android-removed/ig' \
-e 's/Android-removed :/Android-removed:/g' \
-e 's/Android-removed \(BEGIN\|END\)/\1 Android-removed/g' \
-e 's/Android-removed - /Android-removed: /g' \
-e 's/Android[- ]added/Android-added/ig' \
-e 's/Android-added :/Android-added:/g' \
-e 's/Android-added \(BEGIN\|END\)/\1 Android-added/g' \
-e 's/Android-added - /Android-added: /g' \
-e 's/----- \(BEGIN\|END\) android\( -----\)\?/\1 Android-changed/g' \
-e 's/\/\* \(BEGIN\|END\) Android-changed \*\//\/\/ \1 Android-changed/g'
Manual part: Move BEGIN Android-* lines out of block comments
Some Android-{changed,removed,added} lines occurred inside block comments.
This CL targets places in ojluni that contained the String "* BEGIN Android-"
Changes made by this CL include:
- Move the "BEGIN Android-" line into a line comment (the style guide
mandates that "Android-" lines are always in line comments). In many
cases, that line comment is immediately followed by a block comment
holding commented-out upstream code.
- Add corresponding "// END Android-" line comments, where missing.
- Drop documented import changes altogether. These create noise for
little benefit:
(1.) Most import problems will be found at compile time
(2.) They generally correspond to documented changes elsewhere in
the file.
- In most cases, the phrasing of comments and the decision whether to
keep commented out upstream code was not changed by this CL.
- Some additional tweaks were made in line with the style guide.
No attempt was made to:
- Verify that commented-out upstream code actually matches the
current upstream.
- Make any fixes (eg. to comments) that would have required
git archaeology (looking up historic commits).
Bug: 35841464
Test: make droid cts update-api
Change-Id: Ibc60979cb6061cfb0e9c7096cc9dcab30ddfa733
|
| 29957558cf0db700bfaae360a80c42dc3871d0e5 |
|
19-Oct-2016 |
Tobias Thierer <tobiast@google.com> |
Move java.util.concurrent from JSR-166 to an OpenJDK upstream
Apply diff between JSR-166 and OpenJDK to java.util.concurrent.*
This affects
- all classes from java.util.concurrent
- all classes from java.util.concurrent.atomic
- all classes from java.util.concurrent.locks
This makes the license of these classes (GPLv2 with classpathi
exception) consistent with the other files taken from OpenJDK.
Previously, they were in the public domain (from JSR-166), with one
exception: CopyOnWriteArrayList.java (COWAL) was previously Android's
own implementation under Apache 2.0 license. This CL switches that
file to the same upstream OpenJDK revision as the other files touched
by this CL; it is therefore now under the same GPLv2+CE license.
For files other than COWAL, this CL applies the difference between
the old (JSR-166) and new (OpenJDK) upstream. That difference is:
- OpenJDK adds an additional license header (GPLv2+CE) to each file;
this CL adds those license headers.
- The JSR-166 backport of AbstractQueuedSynchronizer and ReentrantLock
commented out use of @ReservedStackAccess with a // OPENJDK-9
comment. In Android, this CL drops these lines entirely instead
- OpenJDK and JSR-166 use a slightly different paths in doc links to
Collection.html#optional-restrictions
For these, Android was already using a third variant so this CL
doesn't affect those.
- Flow and SubmissionPublisher are not available in OpenJDK 8 nor in
Android so they are missing from JSR-166's OpenJDK 8 backport and
are also omitted here.
Because the new upstream is based on OpenJDK, all of the files now
live in the ojluni/ source directory.
=== Upstream OpenJDK 9 revision that this code corresponds to
This corresponds to upstream revision 14076 with the changes from
revision 13050 reverted ("hg backout"). Revision 14076 is between
upstream mercurial tags jdk-9+113 (revision 13993) and jdk-9+114
(revision 14115). Backing out of revision 13050 was necessary in
order for the code to use sun.misc.Unsafe like it did before this
CL, rather than jdk.internal.misc.Unsafe which is not available
on Android.
This revision was obtained by running the following steps:
hg clone http://hg.openjdk.java.net/jdk9/jdk9 jdk9-tmp
cd jdk9-tmp
sh ./get_source.sh
cd jdk/src/java.base/share/classes/java/util/concurrent
hg update -r 14076
hg backout -r 13050 # arbitrarily resolved merge conflicts
rm Flow.java SubmissionPublisher.java # OpenJDK 9 specific
zip -r ~/juc.zip .
The merge conflicts in the backout step were resolved arbitrarily
since they involved files from outside of java.util.concurrent.*
=== Android changes (difference between Android and upstream OpenJDK)
The following changes are Android specific (they are not part of the
difference between JSR-166 and OpenJDK) so they were all kept /
(same as re-applying them on top of the new OpenJDK upstream). In
the case of links to Collection.html#optional in documentation, note
that JSR-166, OpenJDK and Android use three different paths, so
Android's version was kept. Generally these changes come with
Android-changed comments. When the changes are in documentation,
those comments are sometimes omitted since they don't fit in
documentation. To ensure that all of the below changes were
authored by AOSP authors, I have manually verified that each of
them either
(a) is a removal without comment, or
(b) there is an existing Android-changed, android-note or
similar comment that explains the change, or
(c) can be traced to the AOSP commit that introduced it
I'm specifying for each change below whether it falls into categories
(a), (b) or (c). For (c), I am listing the AOSP commit's SHA below.
The only new Android-changed block introduced by this CL is in
CopyOnWriteArrayList.
-ArrayBlockingQueue
(b): removed link to collections framework docs
- BlockingDeque:
(b) fixed framework docs link to "Collection#optional"
- BlockingQueue:
(b) removed link to collections framework docs
(b) fixed framework docs link to "Collection#optional"
- CompletableFuture:
(b) @hide several methods
(b) Removed sentences in toplevel documentation referring to
the methods defaultExecutor(), minimalCompletionStage() and
newIncompleteFuture() (explained by the @hide per above).
This includes removal of a paragraph around CompletionStage's
methods returning CompleteableFuture; that paragraph had been
referring to the @hide methods minimalCompletionStage() and
copy().
- ConcurrentHashMap:
(b) removed link to collections framework docs
(c) changes around keySet()'s return type from libcore commit
0ee1606ffb8586014fb3ea6e540c07d7180d9e9e
- changed compile time type of keySet() return value to be Set
rather than KeySetView, but add documentation guaranteeing
that the value will be a KeySetView.
- remove the reference to {@link #keySet()} from the links in
the documentation for KeySetView
(a) Remove use of annotation @jdk.internal.vm.annotation.Contended
(not available on Android).
- ConcurrentLinkedDeque:
(b) removed link to collections framework docs
- ConcurrentLinkedQueue:
(b) removed link to collections framework docs
- ConcurrentMap:
(b) removed link to collections framework docs
(b) fixed framework docs link to "Collection#optional"
- ConcurrentNavigableMap:
(b) removed link to collections framework docs
- ConcurrentSkipListMap:
(b) removed link to collections framework docs
- ConcurrentSkipListSet:
(b) removed link to collections framework docs
(b) fixed framework docs link to "Collection#optional"
- CopyOnWriteArraySet:
(b) removed link to collections framework docs
(b) fixed framework docs link to "Collection#optional"
- CountedCompleter:
(a) removed snippet
"(such as {@link java.nio.channels.CompletionHandler})"
from documentation (line ~ 45).
- DelayQueue:
(b) removed link to collections framework docs
- Exchanger:
(b) removed use of annotation
@jdk.internal.vm.annotation.Contended
(not available on Android)
- ExecutorService:
(b) removed security manager docs
- Executors:
(b) removed security manager docs & logic
- ForkJoinPool:
(b) removed use of annotation
@jdk.internal.vm.annotation.Contended
(not available on Android)
- ForkJoinTask:
(b) @hide pollSubmission() method (OpenJDK 9 API)
- LinkedBlockingDeque:
(b) removed link to collections framework docs
- LinkedBlockingQueue:
(b) removed link to collections framework docs
- LinkedTransferQueue:
(b) removed link to collections framework docs
- PriorityBlockingQueue:
(b) removed link to collections framework docs
- ScheduledThreadPoolExecutor:
(b) omit class-level docs on setRemoveOnCancelPolicy()
(b) Remove security manager docs from shutdown(), shutdownNow()
- SynchronousQueue:
(b) removed link to collections framework docs
- ThreadLocalRandom:
(a) One empty line dropped around line ~ 465
- ThreadPoolExecutor:
(b) removed security manager docs from shutdown(), shutdownNow()
(b) change setCorePoolSize() to not throw if
maximumPoolSize < corePoolSize
- TimeUnit:
(b) removed java 9 ChronoUnit related code
- TransferQueue:
(b) removed link to collections framework docs
- atomic/AtomicIntegerFieldUpdater,
atomic/AtomicLongFieldUpdater,
atomic/AtomicReferenceFieldUpdater:
(b) use of VMStack.getStackTrace1() in constructor
(b) commented out legacy security code
(b) commented out isAncestor()
- (b) atomic/Striped64: Commented out use of annotation
@jdk.internal.vm.annotation.Contended (not available on Android)
For CopyOnWriteArrayList, added the following two new Android changes:
- removed link to collections framework docs
- fixed framework docs link to "Collection#optional"
Bug: 30860904
Bug: 31028793
Test: CtsLibcoreJsr166TestCases (includes CopyOnWriteArrayListTest)
Test: CtsLibcoreJavaUtilCollectionsTestCases
Change-Id: I41e666d9825f6624e678b6c568326b1155b7adaf
|