Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Recommend linkage checker enforcer rule instead of dependency convergence #6399

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chingor13 merged 3 commits into from
Oct 2, 2019
Merged

Recommend linkage checker enforcer rule instead of dependency convergence #6399

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d465c6f
Recommend linkage checker enforcer rule instead of dependency converg…
Oct 1, 2019
a780b48
use linkage checker enforcer rule
Oct 2, 2019
3d855c5
simplify
Oct 2, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 59 additions & 31 deletions TROUBLESHOOTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ Caused by: java.lang.IllegalArgumentException: ALPN is not configured properly.
```

Please use the [compatibility checker](https://github.com/googleapis/google-cloud-java/tree/master/google-cloud-util/google-cloud-compat-checker) to see if your environment is compatible with grpc-based clients. The incompatibility can mean that:
- You are not on a [supported platform](https://github.com/googleapis/google-cloud-java/#supported-platforms)
- There are classpath conflicts with `netty`
- You are not on a [supported platform](https://github.com/googleapis/google-cloud-java/#supported-platforms).
- There are classpath conflicts with `netty`.
- Or, you are seeing any of the conflicts specified in [gRPC Troubleshooting guide](https://github.com/grpc/grpc-java/blob/master/SECURITY.md#troubleshooting).

If you are using `google-cloud-java` packages prior to version 0.35.0, then consider upgrading to gRPC 1.9.0 or newer and use `grpc-netty-shaded` dependency, for example:
Expand Down Expand Up @@ -39,7 +39,10 @@ If you are using `google-cloud-java` packages prior to version 0.35.0, then cons

The `grpc-netty-shaded` dependency avoids conflicts with other `netty` dependencies that may also be in the classpath.

If you are using `google-cloud-java` version 0.35.0 or above, then it already uses `grpc-netty-shaded`. If you are still running into `ALPN` related problems, please see [gRPC Troubleshooting guide](https://github.com/grpc/grpc-java/blob/master/SECURITY.md#troubleshooting) for other causes.
If you are using `google-cloud-java` version 0.35.0 or above, then it already uses `grpc-netty-shaded`.
If you are still running into `ALPN` related problems, please see
[gRPC Troubleshooting guide](https://github.com/grpc/grpc-java/blob/master/SECURITY.md#troubleshooting)
for other causes.

## ClassNotFoundException, NoSuchMethodError, NoClassDefFoundError

Expand All @@ -48,11 +51,16 @@ Usually these dependency conflicts occur with `guava` or `protobuf-java`.

There may be multiple sources for classpath conflicts:
- Multiple versions of the same transitive dependency in the dependency tree
- Your runtime classpath has different versions of dependences than what you specified in the build
- Your runtime classpath has different versions of dependencies than what you specified in the build

For example, if you have a direct or a transitive dependency on Guava version 10.0, and also `google-cloud-java` uses Guava version 20.0, then `google-cloud-java` could be using Guava methods that don't exist in Guava 10.0, and could cause `NoSuchMethodError`.
For example, if you have a direct or a transitive dependency on Guava version 19.0,
and `google-cloud-java` uses Guava version 28.1,
then `google-cloud-java` could be using Guava methods that don't exist in Guava 19.0,
and cause `NoSuchMethodError`.

Similarily, if your classpath has an older version of `protobuf-java`, but `google-cloud-java` requires a newer version, then you may see `NoClassDefFoundError` that fails to initialize `google-cloud-java` classes, e.g.:
Similarily, if your classpath has an older version of `protobuf-java`,
but `google-cloud-java` requires a newer version,
then you may see `NoClassDefFoundError` that fails to initialize `google-cloud-java` classes, e.g.:

```
java.lang.NoClassDefFoundError: Could not initialize class com.google.pubsub.v1.PubsubMessage$AttributesDefaultEntryHolder
Expand All @@ -68,40 +76,61 @@ $ mvn dependency:tree

Look for versions of potentially conflicting dependencies like `guava`, `protobuf-java`, etc.

If you experience the error only during runtime, then it means that your runtime environment may be introducing conflicting JARs into your runtime classpath. A typical example of this is that Hadoop, Spark, or other server software that your application runs on may have conflicting versions `netty`, `guava`, or `protobuf-java` JARs in the classpath.
If you experience the error only during runtime, then your runtime environment
might be introducing conflicting JARs into your runtime classpath. A typical case
is that Hadoop, Spark, or other server software that your application runs on
has conflicting versions `netty`, `guava`, or `protobuf-java` JARs in the classpath.

### Detecting the conflict early during build
### Detecting conflicts during build

To detect dependency version conflicts early, use the [Enforcer Plugin](https://maven.apache.org/enforcer/maven-enforcer-plugin/index.html) in your Maven configuration to enforce dependency convergence:
To detect dependency linkage errors at compile time, add the
[Linkage Checker Enforcer Rule](https://github.com/GoogleCloudPlatform/cloud-opensource-java/tree/master/enforcer-rules)
in your pom.xml:

```
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-enforcer-plugin</artifactId>
<version>...</version>
<executions>
<execution>
<id>enforce</id>
<configuration>
<rules>
<dependencyConvergence/>
</rules>
</configuration>
<goals>
<goal>enforce</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-enforcer-plugin</artifactId>
<version>3.0.0-M2</version>
<dependencies>
<dependency>
<groupId>com.google.cloud.tools</groupId>
<artifactId>linkage-checker-enforcer-rules</artifactId>
<version>1.0.0</version>
</dependency>
</dependencies>
<executions>
<execution>
<id>enforce-linkage-checker</id>
<!-- Important! Should run after compile -->
<phase>verify</phase>
<goals>
<goal>enforce</goal>
</goals>
<configuration>
<rules>
<LinkageCheckerRule
implementation="com.google.cloud.tools.dependencies.enforcer.LinkageCheckerRule"/>
</rules>
</configuration>
</execution>
</executions>
</plugin>
```

There is no way to detect runtime classpath conflicts though. You'll need to be fully aware of what JARs/classes are included in the runtime classpath as every server environment is different.
There is no way to detect runtime classpath conflicts though. You need to be fully
aware of which JARs/classes are included in the runtime classpath
as every server environment is different.

### Resolving the conflict

There are different strategies to resolve conflicts, but you must understand the root cause of the conflicts, e.g.:
- If you have the control over the dependency tree, runtime classpath, and you have the option to upgrade offending dependencies (e.g., upgrading Guava version), then this is the easiest route.
- If you don't have control over the dependency tree, nor runtime classpath, or changing dependency versions causes other failures, then you should consider [shading dependencies](https://maven.apache.org/plugins/maven-shade-plugin/) of `google-cloud-java`.
- If you have control over the dependency tree and you have the option to upgrade
offending dependencies (e.g., upgrading Guava version), then this is the easiest route.
- If you don't have control over the dependency tree
or changing dependency versions causes other failures,
consider [shading dependencies](https://maven.apache.org/plugins/maven-shade-plugin/)
that conflict with `google-cloud-java`.

For example, to shade `guava` and `protobuf-java`:

Expand Down Expand Up @@ -135,4 +164,3 @@ For example, to shade `guava` and `protobuf-java`:
</executions>
</plugin>
```