Add integration test and example jar.

[jean-philippe-martin]

The integration tests exercise the actual GCS and make sure we can read and write. They use environment variables so we should be able to set them up for Travis.

This also includes an example that illustrates how we can add a jar to an existing project to give it the ability to read/write GCS files.

This example relies on making a "fat" jar. We have multiple options there:

• option A: no fat jar at all.
  pro: you can still add GCS support via recompiling code and adding gcloud-nio as a maven dependency
  con: adding GCS support without recompiling is now super-annoying because you need to add a ton of jars. This greatly diminishes NIO's magic.
• option B: the example jar is fat (so contains gcloud)
  pro: you can run it with a simple command line, and adding the nio jar gets you GCS support. No change to the other jars, the ones you're likely to actually use.
  con: this isn't representative of adding GCS support to legacy binaries, because they won't link those dependencies already.
• option C: the NIO jar is fat.
  pro: by adding this jar to the classpath you can super-easily add GCS support to legacy code. You can still also use a maven dependency if you prefer.
  con: if you're trying to add GCS NIO to something that already has some gcloud support, you get redundant jars (unless use the maven deps).

[jean-philippe-martin]

I'm leaning towards option C. This makes it easy to add GCS support to legacy code ("just add this jar!"). For new code I'd recommend just pointing maven to gcloud-nio, so it does the right thing.

[aozarov]

I think we should go only with option (1) which is the maven way.

Also, see existing examples of how to run an example using Maven (so all dependencies are pulled).
bundling third-party jars is typically a bad idea and can cause lots of headache when collision happen with different versions.

[jean-philippe-martin]

@aozarov with all due respect, using only option (A) kills one of the uses cases for NIO. That is why I am proposing that we use options A and C together.

NIO allows two things:
1: Write new code that uses our library to access GCS as normal files.
2: Add GCS capabilities to legacy Java 7 code without recompiling it, just by adding jars to CLASSPATH.

Use case (1) is done in the traditional way ("A"), using Maven.

Use case (2) isn't a good fit for Maven. Ideally the user wants a small number of jar files to add to CLASSPATH. For this case we would follow option C.

The unit tests illustrate use case (1). The code in the example project is meant to illustrate use case (2) and that is why I choose to run it with jar files instead of Maven. In use case (2) the user may not even have source code available on which to call mvn exec:java ....

We are avoiding the collision headaches you mention by using shadowing in the fat jar. This may use a bit more memory but I think that's an acceptable trade-off for the ability to add features to existing programs for which source may not be available (case 2). And again, in the case of new code (case 1) there are no headaches because we'd be using Maven and the fat jar isn't used.

I hope you'll agree that use case (2) is useful and something we want to support.

[jean-philippe-martin]

(merged in the other changes to nio, so this branch can now merge without conflicts when I get the thumbs up)

[aozarov]

I hope you'll agree that use case (2) is useful and something we want to support.

Honestly, I think this option should be avoided, even when using a shaded jar, and for various reasons including:

• This actually is more likely to put more code in your classpath (though less "jar" files).
• Common libraries (shadowed and ones in the user classpath) may not play with each other nicely (e.g. guava when it avoids redundant copying based on instanceof or injections via Guice).

Also, I think most people in the Java world are using IDEs that support maven/ant-ivy/gradle/... which makes pulling the dependencies from maven and including it in your project transparent (or very simple). For the ones that don't the mvn command line tool can do the same.

However, I don't mind including in our POMs a shaded far jar option and it should be fine to use it
in our samples (indeed it does make it simpler). If we do so, I would like to change the other examples, so build/running style would be consistent (do you mind to create a PR or an issue for it?).

In use case (2) the user may not even have source code available on which to call mvn exec:java ....

I am not sure I understand this argument. How do you suggest the user get far jar without building it via mvn package?

[jean-philippe-martin]

Merged. Points raised in the process but left for later PRs:

• Check whether we need to tell people to enable both"Google Cloud Storage" and "Google Cloud Storage JSON API" (issue Update example documentation with correct APIs to enable (if necessary) #790)
• Adding another example that uses the normal dependency path (which may require us to move the Stats example to a different project) (issue Decide whether to add another NIO example and split into two example jars #791)
• Possibly changing the existing examples to also use a jar file (issue Consider running all examples from a jar file #778) (though we may not want to do this anymore if the Stat example is moved to another project).

[jean-philippe-martin]

Thanks everyone for the reviews and help with this code!