Skip to content

Commit ed1eff1

Browse files
dypcoderdypcoder
authored
Merge branch 'google:master' into master
2 parents e8750e8 + 1566940 commit ed1eff1

File tree

2,222 files changed

+82529
-73842
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

2,222 files changed

+82529
-73842
lines changed

‎.github/dependabot.yml

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
version: 2
2+
updates:
3+
# TODO(b/170636568): Enable Maven updates? Perhaps wait until we can more
4+
# easily import the generated PRs into our internal repo.
5+
# - package-ecosystem: "maven"
6+
# directory: "/"
7+
# schedule:
8+
# interval: "daily"
9+
# - package-ecosystem: "maven"
10+
# directory: "/android"
11+
# schedule:
12+
# interval: "daily"
13+
- package-ecosystem: "github-actions"
14+
directory: "/"
15+
schedule:
16+
interval: "daily"

‎.github/workflows/ci.yml

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
pull_request:
8+
branches:
9+
- master
10+
11+
jobs:
12+
test:
13+
name: "${{ matrix.root-pom }} on JDK ${{ matrix.java }}"
14+
strategy:
15+
matrix:
16+
java: [ 8, 11 ]
17+
root-pom: [ 'pom.xml', 'android/pom.xml' ]
18+
runs-on: ubuntu-latest
19+
env:
20+
ROOT_POM: ${{ matrix.root-pom }}
21+
steps:
22+
# Cancel any previous runs for the same branch that are still running.
23+
- name: 'Cancel previous runs'
24+
uses: styfle/cancel-workflow-action@0.9.1
25+
with:
26+
access_token: ${{ github.token }}
27+
- name: 'Check out repository'
28+
uses: actions/checkout@v2.4.0
29+
- name: 'Cache local Maven repository'
30+
uses: actions/cache@v2.1.7
31+
with:
32+
path: ~/.m2/repository
33+
key: maven-${{ hashFiles('**/pom.xml') }}
34+
restore-keys: |
35+
maven-
36+
- name: 'Set up JDK ${{ matrix.java }}'
37+
uses: actions/setup-java@v2
38+
with:
39+
java-version: ${{ matrix.java }}
40+
distribution: 'zulu'
41+
- name: 'Install'
42+
shell: bash
43+
run: mvn -B -Dorg.slf4j.simpleLogger.log.org.apache.maven.cli.transfer.Slf4jMavenTransferListener=warn install -U -DskipTests=true -f $ROOT_POM
44+
- name: 'Test'
45+
shell: bash
46+
run: mvn -B -P!standard-with-extra-repos verify -U -Dmaven.javadoc.skip=true -f $ROOT_POM
47+
- name: 'Print Surefire reports'
48+
# Note: Normally a step won't run if the job has failed, but this causes it to
49+
if: ${{ failure() }}
50+
shell: bash
51+
run: ./util/print_surefire_reports.sh
52+
53+
publish_snapshot:
54+
name: 'Publish snapshot'
55+
needs: test
56+
if: github.event_name == 'push' && github.repository == 'google/guava'
57+
runs-on: ubuntu-latest
58+
steps:
59+
- name: 'Check out repository'
60+
uses: actions/checkout@v2.4.0
61+
- name: 'Cache local Maven repository'
62+
uses: actions/cache@v2.1.7
63+
with:
64+
path: ~/.m2/repository
65+
key: maven-${{ hashFiles('**/pom.xml') }}
66+
restore-keys: |
67+
maven-
68+
- name: 'Set up JDK 11'
69+
uses: actions/setup-java@v2
70+
with:
71+
java-version: 11
72+
distribution: 'zulu'
73+
server-id: sonatype-nexus-snapshots
74+
server-username: CI_DEPLOY_USERNAME
75+
server-password: CI_DEPLOY_PASSWORD
76+
- name: 'Publish'
77+
env:
78+
CI_DEPLOY_USERNAME: ${{ secrets.CI_DEPLOY_USERNAME }}
79+
CI_DEPLOY_PASSWORD: ${{ secrets.CI_DEPLOY_PASSWORD }}
80+
run: ./util/deploy_snapshot.sh
81+
82+
generate_docs:
83+
name: 'Generate latest docs'
84+
needs: test
85+
if: github.event_name == 'push' && github.repository == 'google/guava'
86+
runs-on: ubuntu-latest
87+
steps:
88+
- name: 'Check out repository'
89+
uses: actions/checkout@v2.4.0
90+
- name: 'Cache local Maven repository'
91+
uses: actions/cache@v2.1.7
92+
with:
93+
path: ~/.m2/repository
94+
key: maven-${{ hashFiles('**/pom.xml') }}
95+
restore-keys: |
96+
maven-
97+
- name: 'Set up JDK 11'
98+
uses: actions/setup-java@v2
99+
with:
100+
java-version: 11
101+
distribution: 'zulu'
102+
- name: 'Generate latest docs'
103+
env:
104+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
105+
run: ./util/update_snapshot_docs.sh

‎.travis.yml

Lines changed: 0 additions & 42 deletions
This file was deleted.

‎CONTRIBUTING.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,8 +42,8 @@ Some examples of types of pull requests that are immediately helpful:
4242
Guidelines for any code contributions:
4343

4444
1. Any significant changes should be accompanied by tests. The project already
45-
has good test coverage, so look at some of the existing tests if you're
46-
unsure how to go about it.
45+
has good test coverage, so look at some existing tests if you're unsure
46+
how to go about it.
4747
2. All contributions must be licensed Apache 2.0 and all files must have a
4848
copy of the boilerplate license comment (can be copied from an existing
4949
file).

‎README.md

Lines changed: 79 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,110 +1,130 @@
11
# Guava: Google Core Libraries for Java
22

33
[![Latest release](https://img.shields.io/github/release/google/guava.svg)](https://github.com/google/guava/releases/latest)
4-
[![Build Status](https://travis-ci.org/google/guava.svg?branch=master)](https://travis-ci.org/google/guava)
4+
[![Build Status](https://github.com/google/guava/workflows/CI/badge.svg?branch=master)](https://github.com/google/guava/actions)
55

6-
Guava is a set of core libraries that includes new collection types (such as
7-
multimap and multiset), immutable collections, a graph library, functional
8-
types, an in-memory cache, and APIs/utilities for concurrency, I/O, hashing,
9-
primitives, reflection, string processing, and much more!
6+
Guava is a set of core Java libraries from Google that includes new collection types
7+
(such as multimap and multiset), immutable collections, a graph library, and
8+
utilities for concurrency, I/O, hashing, caching, primitives, strings, and more! It
9+
is widely used on most Java projects within Google, and widely used by many
10+
other companies as well.
1011

11-
Guava comes in two flavors.
12+
Guava comes in two flavors:
1213

1314
* The JRE flavor requires JDK 1.8 or higher.
14-
* If you need support for JDK 1.7 or Android, use the Android flavor. You can
15-
find the Android Guava source in the [`android` directory].
15+
* If you need support for Android, use the Android flavor. You can find the
16+
Android Guava source in the [`android` directory].
1617

1718
[`android` directory]: https://github.com/google/guava/tree/master/android
1819

1920
## Adding Guava to your build
2021

21-
Guava's Maven group ID is `com.google.guava` and its artifact ID is `guava`.
22+
Guava's Maven group ID is `com.google.guava`, and its artifact ID is `guava`.
2223
Guava provides two different "flavors": one for use on a (Java 8+) JRE and one
23-
for use on Android or Java 7 or by any library that wants to be compatible with
24-
either of those. These flavors are specified in the Maven version field as
25-
either `25.1-jre` or `25.1-android`. For more about depending on
26-
Guava, see [using Guava in your build].
24+
for use on Android or by any library that wants to be compatible with Android.
25+
These flavors are specified in the Maven version field as either `31.0.1-jre` or
26+
`31.0.1-android`. For more about depending on Guava, see
27+
[using Guava in your build].
2728

2829
To add a dependency on Guava using Maven, use the following:
2930

3031
```xml
3132
<dependency>
3233
<groupId>com.google.guava</groupId>
3334
<artifactId>guava</artifactId>
34-
<version>25.1-jre</version>
35+
<version>31.0.1-jre</version>
3536
<!-- or, for Android: -->
36-
<version>25.1-android</version>
37+
<version>31.0.1-android</version>
3738
</dependency>
3839
```
3940

4041
To add a dependency using Gradle:
4142

42-
```
43+
```gradle
4344
dependencies {
44-
compile 'com.google.guava:guava:25.1-jre'
45-
// or, for Android:
46-
api 'com.google.guava:guava:25.1-android'
45+
// Pick one:
46+
47+
// 1. Use Guava in your implementation only:
48+
implementation("com.google.guava:guava:31.0.1-jre")
49+
50+
// 2. Use Guava types in your public API:
51+
api("com.google.guava:guava:31.0.1-jre")
52+
53+
// 3. Android - Use Guava in your implementation only:
54+
implementation("com.google.guava:guava:31.0.1-android")
55+
56+
// 4. Android - Use Guava types in your public API:
57+
api("com.google.guava:guava:31.0.1-android")
4758
}
4859
```
4960

50-
## Snapshots
61+
For more information on when to use `api` and when to use `implementation`,
62+
consult the
63+
[Gradle documentation on API and implementation separation](https://docs.gradle.org/current/userguide/java_library_plugin.html#sec:java_library_separation).
64+
65+
## Snapshots and Documentation
5166

5267
Snapshots of Guava built from the `master` branch are available through Maven
5368
using version `HEAD-jre-SNAPSHOT`, or `HEAD-android-SNAPSHOT` for the Android
5469
flavor.
5570

56-
- Snapshot API Docs: [guava][guava-snapshot-api-docs]
57-
- Snapshot API Diffs: [guava][guava-snapshot-api-diffs]
71+
- Snapshot API Docs: [guava][guava-snapshot-api-docs]
72+
- Snapshot API Diffs: [guava][guava-snapshot-api-diffs]
5873

5974
## Learn about Guava
6075

61-
- Our users' guide, [Guava Explained]
62-
- [A nice collection](http://www.tfnico.com/presentations/google-guava) of other helpful links
76+
- Our users' guide, [Guava Explained]
77+
- [A nice collection](http://www.tfnico.com/presentations/google-guava) of
78+
other helpful links
6379

6480
## Links
6581

66-
- [GitHub project](https://github.com/google/guava)
67-
- [Issue tracker: Report a defect or feature request](https://github.com/google/guava/issues/new)
68-
- [StackOverflow: Ask "how-to" and "why-didn't-it-work" questions](https://stackoverflow.com/questions/ask?tags=guava+java)
69-
- [guava-discuss: For open-ended questions and discussion](http://groups.google.com/group/guava-discuss)
82+
- [GitHub project](https://github.com/google/guava)
83+
- [Issue tracker: Report a defect or feature request](https://github.com/google/guava/issues/new)
84+
- [StackOverflow: Ask "how-to" and "why-didn't-it-work" questions](https://stackoverflow.com/questions/ask?tags=guava+java)
85+
- [guava-announce: Announcements of releases and upcoming significant changes](http://groups.google.com/group/guava-announce)
86+
- [guava-discuss: For open-ended questions and discussion](http://groups.google.com/group/guava-discuss)
7087

7188
## IMPORTANT WARNINGS
7289

73-
1. APIs marked with the `@Beta` annotation at the class or method level
74-
are subject to change. They can be modified in any way, or even
75-
removed, at any time. If your code is a library itself (i.e. it is
76-
used on the CLASSPATH of users outside your own control), you should
77-
not use beta APIs, unless you [repackage] them. **If your
78-
code is a library, we strongly recommend using the [Guava Beta Checker] to
79-
ensure that you do not use any `@Beta` APIs!**
80-
81-
2. APIs without `@Beta` will remain binary-compatible for the indefinite
82-
future. (Previously, we sometimes removed such APIs after a deprecation period.
83-
The last release to remove non-`@Beta` APIs was Guava 21.0.) Even `@Deprecated`
84-
APIs will remain (again, unless they are `@Beta`). We have no plans to start
85-
removing things again, but officially, we're leaving our options open in case
86-
of surprises (like, say, a serious security problem).
87-
88-
3. Serialized forms of ALL objects are subject to change unless noted
89-
otherwise. Do not persist these and assume they can be read by a
90-
future version of the library.
91-
92-
4. Our classes are not designed to protect against a malicious caller.
93-
You should not use them for communication between trusted and
94-
untrusted code.
95-
96-
5. For the mainline flavor, we unit-test the libraries using only OpenJDK 1.8 on
97-
Linux. Some features, especially in `com.google.common.io`, may not work
98-
correctly in other environments. For the Android flavor, our unit tests run on
99-
API level 15 (Ice Cream Sandwich).
100-
101-
[guava-snapshot-api-docs]: https://google.github.io/guava/releases/snapshot-jre/api/docs/
102-
[guava-snapshot-api-diffs]: https://google.github.io/guava/releases/snapshot-jre/api/diffs/
90+
1. APIs marked with the `@Beta` annotation at the class or method level are
91+
subject to change. They can be modified in any way, or even removed, at any
92+
time. If your code is a library itself (i.e., it is used on the CLASSPATH of
93+
users outside your own control), you should not use beta APIs unless you
94+
[repackage] them. **If your code is a library, we strongly recommend using
95+
the [Guava Beta Checker] to ensure that you do not use any `@Beta` APIs!**
96+
97+
2. APIs without `@Beta` will remain binary-compatible for the indefinite
98+
future. (Previously, we sometimes removed such APIs after a deprecation
99+
period. The last release to remove non-`@Beta` APIs was Guava 21.0.) Even
100+
`@Deprecated` APIs will remain (again, unless they are `@Beta`). We have no
101+
plans to start removing things again, but officially, we're leaving our
102+
options open in case of surprises (like, say, a serious security problem).
103+
104+
3. Guava has one dependency that is needed for linkage at runtime:
105+
`com.google.guava:failureaccess:1.0.1`. It also has
106+
[some annotation-only dependencies][guava-deps], which we discuss in more
107+
detail at that link.
108+
109+
4. Serialized forms of ALL objects are subject to change unless noted
110+
otherwise. Do not persist these and assume they can be read by a future
111+
version of the library.
112+
113+
5. Our classes are not designed to protect against a malicious caller. You
114+
should not use them for communication between trusted and untrusted code.
115+
116+
6. For the mainline flavor, we test the libraries using only OpenJDK 8 and
117+
OpenJDK 11 on Linux. Some features, especially in `com.google.common.io`,
118+
may not work correctly in other environments. For the Android flavor, our
119+
unit tests also run on API level 15 (Ice Cream Sandwich).
120+
121+
[guava-snapshot-api-docs]: https://guava.dev/releases/snapshot-jre/api/docs/
122+
[guava-snapshot-api-diffs]: https://guava.dev/releases/snapshot-jre/api/diffs/
103123
[Guava Explained]: https://github.com/google/guava/wiki/Home
104124
[Guava Beta Checker]: https://github.com/google/guava-beta-checker
105125

106126
<!-- References -->
107127

108128
[using Guava in your build]: https://github.com/google/guava/wiki/UseGuavaInYourBuild
109129
[repackage]: https://github.com/google/guava/wiki/UseGuavaInYourBuild#what-if-i-want-to-use-beta-apis-from-a-library-that-people-use-as-a-dependency
110-
130+
[guava-deps]: https://github.com/google/guava/wiki/UseGuavaInYourBuild#what-about-guavas-own-dependencies

0 commit comments

Comments
 (0)