diff --git a/.github/blunderbuss.yml b/.github/blunderbuss.yml new file mode 100644 index 000000000..1a23ea42b --- /dev/null +++ b/.github/blunderbuss.yml @@ -0,0 +1,7 @@ +# Configuration for the Blunderbuss GitHub app. For more info see +# https://github.com/googleapis/repo-automation-bots/tree/master/packages/blunderbuss +assign_prs_by: +- labels: + - samples + to: + - googleapis/java-samples-reviewers \ No newline at end of file diff --git a/.github/readme/synth.metadata/synth.metadata b/.github/readme/synth.metadata/synth.metadata index 97da865ea..909cfa560 100644 --- a/.github/readme/synth.metadata/synth.metadata +++ b/.github/readme/synth.metadata/synth.metadata @@ -4,14 +4,14 @@ "git": { "name": ".", "remote": "https://github.com/googleapis/java-storage-nio.git", - "sha": "2d0c406f12c37651374c5d51d4bd927110de5711" + "sha": "e88e3f0ba2b847edd52b271063184af2dbafae9b" } }, { "git": { "name": "synthtool", "remote": "https://github.com/googleapis/synthtool.git", - "sha": "7fcc405a579d5d53a726ff3da1b7c8c08f0f2d58" + "sha": "f94318521f63085b9ccb43d42af89f153fb39f15" } } ] diff --git a/.readme-partials.yaml b/.readme-partials.yaml new file mode 100644 index 000000000..ab46aaa34 --- /dev/null +++ b/.readme-partials.yaml @@ -0,0 +1,81 @@ +custom_content: | + #### About Google Cloud Storage + + [Google Cloud Storage](https://cloud.google.com/storage/) is a durable and highly available + object storage service. Google Cloud Storage is almost infinitely scalable + and guarantees consistency: when a write succeeds, the latest copy of the + object will be returned to any GET, globally. + + See the [Google Cloud Storage docs](https://cloud.google.com/storage/docs/signup?hl=en) for more details + on how to activate Cloud Storage for your project. + + #### About Java NIO Providers + + Java NIO Providers is an extension mechanism that is part of Java and allows + third parties to extend Java's [normal File API](https://docs.oracle.com/javase/7/docs/api/java/nio/file/Files.html) to support + additional filesystems. + + #### Accessing files + + The simplest way to get started is with `Paths` and `Files`: + + ```java + Path path = Paths.get(URI.create("gs://bucket/lolcat.csv")); + List lines = Files.readAllLines(path, StandardCharsets.UTF_8); + ``` + + If you know the paths will point to Google Cloud Storage, you can also use the + direct formulation: + + ```java + try (CloudStorageFileSystem fs = CloudStorageFileSystem.forBucket("bucket")) { + Path path = fs.getPath("lolcat.csv"); + List lines = Files.readAllLines(path, StandardCharsets.UTF_8); + } + ``` + + Once you have a `Path` you can use it as you would a normal file. For example + you can use `InputStream` and `OutputStream` for streaming: + + ```java + try (InputStream input = Files.openInputStream(path)) { + // ... + } + ``` + + You can also set various attributes using CloudStorageOptions static helpers: + + ```java + Files.write(csvPath, csvLines, StandardCharsets.UTF_8, + withMimeType(MediaType.CSV_UTF8), + withoutCaching()); + ``` + + #### Limitations + + This library is usable, but not yet complete. The following features are not + yet implemented: + * Resuming upload or download + * Generations + * File attributes + * (more - list is not exhaustive) + + Some features are not on the roadmap: this library would be a poor choice to + mirror a local filesystem onto the cloud because Google Cloud Storage has a + different set of features from your local disk. This library, by design, + does not mask those differences. Rather, it aims to expose the common + subset via a familiar interface. + + **NOTE:** Cloud Storage uses a flat namespace and therefore doesn't support real + directories. So this library supports what's known as "pseudo-directories". Any + path that includes a trailing slash, will be considered a directory. It will + always be assumed to exist, without performing any I/O. Paths without the trailing + slash will result in an I/O operation to check a file is present in that "directory". + This allows you to do path manipulation in the same manner as you would with the normal UNIX file + system implementation. You can disable this feature with + `CloudStorageConfiguration.usePseudoDirectories()`. + + #### Complete source code + + There are examples in [google-cloud-nio-examples](google-cloud-nio-examples/src/main/java/com/google/cloud/examples/nio/) + for your perusal. diff --git a/.repo-metadata.json b/.repo-metadata.json index f5590311d..383186253 100644 --- a/.repo-metadata.json +++ b/.repo-metadata.json @@ -1,11 +1,13 @@ { - "name": "google-cloud-nio", + "name": "storage_nio", "name_pretty": "NIO Filesystem Provider for Google Cloud Storage", + "api_description": "provides a Google Cloud Storage extension for Java's NIO Filesystem.", "product_documentation": "https://cloud.google.com/storage/docs", "client_documentation": "https://googleapis.dev/java/google-cloud-nio/latest", - "release_level": "alpha", + "release_level": "beta", "language": "java", "repo": "googleapis/java-storage-nio", "repo_short": "java-storage-nio", - "distribution_name": "com.google.cloud:google-cloud-nio" + "distribution_name": "com.google.cloud:google-cloud-nio", + "api_id": "storage.googleapis.com" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 741f81a40..a139037e0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +### [0.122.3](https://www.github.com/googleapis/java-storage-nio/compare/v0.122.2...v0.122.3) (2020-12-03) + + +### Dependencies + +* update dependency com.google.cloud:google-cloud-shared-dependencies to v0.16.0 ([#305](https://www.github.com/googleapis/java-storage-nio/issues/305)) ([79245ae](https://www.github.com/googleapis/java-storage-nio/commit/79245ae5ded370d310f31939aa36572563437bb3)) + ### [0.122.2](https://www.github.com/googleapis/java-storage-nio/compare/v0.122.1...v0.122.2) (2020-11-23) diff --git a/README.md b/README.md index 583d08afd..21b18488a 100644 --- a/README.md +++ b/README.md @@ -13,24 +13,47 @@ Java idiomatic client for [NIO Filesystem Provider for Google Cloud Storage][pro ## Quickstart +If you are using Maven with [BOM][libraries-bom], add this to your pom.xml file +```xml + + + + com.google.cloud + libraries-bom + 15.0.0 + pom + import + + + + + + + com.google.cloud + google-cloud-nio + + + +``` -If you are using Maven, add this to your pom.xml file: +If you are using Maven without BOM, add this to your dependencies: ```xml com.google.cloud google-cloud-nio - 0.122.1 + 0.122.2 + ``` If you are using Gradle, add this to your dependencies ```Groovy -compile 'com.google.cloud:google-cloud-nio:0.122.1' +compile 'com.google.cloud:google-cloud-nio:0.122.2' ``` If you are using SBT, add this to your dependencies ```Scala -libraryDependencies += "com.google.cloud" % "google-cloud-nio" % "0.122.1" +libraryDependencies += "com.google.cloud" % "google-cloud-nio" % "0.122.2" ``` ## Authentication @@ -55,12 +78,93 @@ to add `google-cloud-nio` as a dependency in your code. ## About NIO Filesystem Provider for Google Cloud Storage -[NIO Filesystem Provider for Google Cloud Storage][product-docs] +[NIO Filesystem Provider for Google Cloud Storage][product-docs] provides a Google Cloud Storage extension for Java's NIO Filesystem. See the [NIO Filesystem Provider for Google Cloud Storage client library docs][javadocs] to learn how to use this NIO Filesystem Provider for Google Cloud Storage Client Library. +#### About Google Cloud Storage + +[Google Cloud Storage](https://cloud.google.com/storage/) is a durable and highly available +object storage service. Google Cloud Storage is almost infinitely scalable +and guarantees consistency: when a write succeeds, the latest copy of the +object will be returned to any GET, globally. + +See the [Google Cloud Storage docs](https://cloud.google.com/storage/docs/signup?hl=en) for more details +on how to activate Cloud Storage for your project. + +#### About Java NIO Providers + +Java NIO Providers is an extension mechanism that is part of Java and allows +third parties to extend Java's [normal File API](https://docs.oracle.com/javase/7/docs/api/java/nio/file/Files.html) to support +additional filesystems. + +#### Accessing files + +The simplest way to get started is with `Paths` and `Files`: + +```java +Path path = Paths.get(URI.create("gs://bucket/lolcat.csv")); +List lines = Files.readAllLines(path, StandardCharsets.UTF_8); +``` + +If you know the paths will point to Google Cloud Storage, you can also use the +direct formulation: + +```java +try (CloudStorageFileSystem fs = CloudStorageFileSystem.forBucket("bucket")) { + Path path = fs.getPath("lolcat.csv"); + List lines = Files.readAllLines(path, StandardCharsets.UTF_8); +} +``` + +Once you have a `Path` you can use it as you would a normal file. For example +you can use `InputStream` and `OutputStream` for streaming: + +```java +try (InputStream input = Files.openInputStream(path)) { + // ... +} +``` + +You can also set various attributes using CloudStorageOptions static helpers: + +```java +Files.write(csvPath, csvLines, StandardCharsets.UTF_8, + withMimeType(MediaType.CSV_UTF8), + withoutCaching()); +``` + +#### Limitations + +This library is usable, but not yet complete. The following features are not +yet implemented: + * Resuming upload or download + * Generations + * File attributes + * (more - list is not exhaustive) + +Some features are not on the roadmap: this library would be a poor choice to +mirror a local filesystem onto the cloud because Google Cloud Storage has a +different set of features from your local disk. This library, by design, +does not mask those differences. Rather, it aims to expose the common +subset via a familiar interface. + +**NOTE:** Cloud Storage uses a flat namespace and therefore doesn't support real +directories. So this library supports what's known as "pseudo-directories". Any +path that includes a trailing slash, will be considered a directory. It will +always be assumed to exist, without performing any I/O. Paths without the trailing +slash will result in an I/O operation to check a file is present in that "directory". +This allows you to do path manipulation in the same manner as you would with the normal UNIX file +system implementation. You can disable this feature with +`CloudStorageConfiguration.usePseudoDirectories()`. + +#### Complete source code + +There are examples in [google-cloud-nio-examples](google-cloud-nio-examples/src/main/java/com/google/cloud/examples/nio/) +for your perusal. + @@ -119,7 +223,7 @@ Java 11 | [![Kokoro CI][kokoro-badge-image-5]][kokoro-badge-link-5] [kokoro-badge-link-4]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-storage-nio/java8-win.html [kokoro-badge-image-5]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-storage-nio/java11.svg [kokoro-badge-link-5]: http://storage.googleapis.com/cloud-devrel-public/java/badges/java-storage-nio/java11.html -[stability-image]: https://img.shields.io/badge/stability-alpha-orange +[stability-image]: https://img.shields.io/badge/stability-beta-yellow [maven-version-image]: https://img.shields.io/maven-central/v/com.google.cloud/google-cloud-nio.svg [maven-version-link]: https://search.maven.org/search?q=g:com.google.cloud%20AND%20a:google-cloud-nio&core=gav [authentication]: https://github.com/googleapis/google-cloud-java#authentication @@ -131,6 +235,6 @@ Java 11 | [![Kokoro CI][kokoro-badge-image-5]][kokoro-badge-link-5] [code-of-conduct]: https://github.com/googleapis/java-storage-nio/blob/master/CODE_OF_CONDUCT.md#contributor-code-of-conduct [license]: https://github.com/googleapis/java-storage-nio/blob/master/LICENSE - +[enable-api]: https://console.cloud.google.com/flows/enableapi?apiid=storage.googleapis.com [libraries-bom]: https://github.com/GoogleCloudPlatform/cloud-opensource-java/wiki/The-Google-Cloud-Platform-Libraries-BOM [shell_img]: https://gstatic.com/cloudssh/images/open-btn.png diff --git a/google-cloud-nio-examples/pom.xml b/google-cloud-nio-examples/pom.xml index ec7b32a93..aacb33cf7 100644 --- a/google-cloud-nio-examples/pom.xml +++ b/google-cloud-nio-examples/pom.xml @@ -2,7 +2,7 @@ 4.0.0 google-cloud-nio-examples - 0.122.2 + 0.122.3 jar Google Cloud NIO Examples https://github.com/googleapis/java-storage-nio @@ -13,7 +13,7 @@ com.google.cloud google-cloud-nio-parent - 0.122.2 + 0.122.3 diff --git a/google-cloud-nio-retrofit/pom.xml b/google-cloud-nio-retrofit/pom.xml index 9464dd893..102e37b52 100644 --- a/google-cloud-nio-retrofit/pom.xml +++ b/google-cloud-nio-retrofit/pom.xml @@ -2,7 +2,7 @@ 4.0.0 google-cloud-nio-retrofit - 0.122.2 + 0.122.3 jar Google Cloud NIO Retrofit Example https://github.com/googleapis/java-storage-nio @@ -12,7 +12,7 @@ com.google.cloud google-cloud-nio-parent - 0.122.2 + 0.122.3 google-cloud-nio-retrofit diff --git a/google-cloud-nio/pom.xml b/google-cloud-nio/pom.xml index a2120c01b..1fc602830 100644 --- a/google-cloud-nio/pom.xml +++ b/google-cloud-nio/pom.xml @@ -2,7 +2,7 @@ 4.0.0 google-cloud-nio - 0.122.2 + 0.122.3 jar Google Cloud NIO https://github.com/googleapis/java-storage-nio @@ -12,7 +12,7 @@ com.google.cloud google-cloud-nio-parent - 0.122.2 + 0.122.3 google-cloud-nio diff --git a/pom.xml b/pom.xml index 709c98875..ace353fb8 100644 --- a/pom.xml +++ b/pom.xml @@ -4,7 +4,7 @@ com.google.cloud google-cloud-nio-parent pom - 0.122.2 + 0.122.3 Storage Parent https://github.com/googleapis/java-storage-nio @@ -79,7 +79,7 @@ com.google.cloud google-cloud-shared-dependencies - 0.15.0 + 0.16.0 pom import diff --git a/samples/install-without-bom/pom.xml b/samples/install-without-bom/pom.xml index fa2ddd808..aa881cfae 100644 --- a/samples/install-without-bom/pom.xml +++ b/samples/install-without-bom/pom.xml @@ -25,13 +25,13 @@ - + com.google.cloud google-cloud-nio - 0.122.1 + 0.122.2 - + junit diff --git a/samples/snapshot/pom.xml b/samples/snapshot/pom.xml index 09bbff613..6c2cc676e 100644 --- a/samples/snapshot/pom.xml +++ b/samples/snapshot/pom.xml @@ -23,13 +23,14 @@ UTF-8 - + com.google.cloud google-cloud-nio - 0.122.1 + 0.122.3 + junit @@ -44,7 +45,6 @@ test - diff --git a/samples/snippets/pom.xml b/samples/snippets/pom.xml index 49a4b41bb..52472f82e 100644 --- a/samples/snippets/pom.xml +++ b/samples/snippets/pom.xml @@ -24,7 +24,7 @@ - + @@ -42,8 +42,7 @@ com.google.cloud google-cloud-nio - - + junit junit @@ -56,5 +55,7 @@ 1.1 test + + diff --git a/synth.metadata b/synth.metadata index 2aaa8b9ed..80ab5dcda 100644 --- a/synth.metadata +++ b/synth.metadata @@ -4,14 +4,14 @@ "git": { "name": ".", "remote": "https://github.com/googleapis/java-storage-nio.git", - "sha": "5d4d2662f40456991c485522a3fd65bbb031afff" + "sha": "42db13794a782a7c6b05239159db33ad0c4d74f4" } }, { "git": { "name": "synthtool", "remote": "https://github.com/googleapis/synthtool.git", - "sha": "68742c6016bf0d16948a572633d17955a8737414" + "sha": "943bb78606d035001123030067dffcc34f4645f2" } } ], @@ -21,6 +21,7 @@ ".github/ISSUE_TEMPLATE/feature_request.md", ".github/ISSUE_TEMPLATE/support_request.md", ".github/PULL_REQUEST_TEMPLATE.md", + ".github/blunderbuss.yml", ".github/generated-files-bot.yml", ".github/readme/synth.py", ".github/release-please.yml", diff --git a/versions.txt b/versions.txt index 759386f2c..4b553ed2c 100644 --- a/versions.txt +++ b/versions.txt @@ -1,4 +1,4 @@ # Format: # module:released-version:current-version -google-cloud-nio:0.122.2:0.122.2 \ No newline at end of file +google-cloud-nio:0.122.3:0.122.3 \ No newline at end of file