feat: add support for tailLogEntry API

Implements tailLogEntries API to stream new log entries.
Provides unit and system/integration tests for the new API.

Fixes #592

[![WhiteSource Renovate](https://app.renovatebot.com/images/banner.svg)](https://renovatebot.com)

This PR contains the following updates:

| Package | Change | Age | Adoption | Passing | Confidence |
|---|---|---|---|---|---|
| [com.google.cloud:libraries-bom](https://togithub.com/GoogleCloudPlatform/cloud-opensource-java) | `22.0.0` -> `23.0.0` | [![age](https://badges.renovateapi.com/packages/maven/com.google.cloud:libraries-bom/23.0.0/age-slim)](https://docs.renovatebot.com/merge-confidence/) | [![adoption](https://badges.renovateapi.com/packages/maven/com.google.cloud:libraries-bom/23.0.0/adoption-slim)](https://docs.renovatebot.com/merge-confidence/) | [![passing](https://badges.renovateapi.com/packages/maven/com.google.cloud:libraries-bom/23.0.0/compatibility-slim/22.0.0)](https://docs.renovatebot.com/merge-confidence/) | [![confidence](https://badges.renovateapi.com/packages/maven/com.google.cloud:libraries-bom/23.0.0/confidence-slim/22.0.0)](https://docs.renovatebot.com/merge-confidence/) |

---

### Configuration

📅 **Schedule**: At any time (no schedule defined).

🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.

♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 **Ignore**: Close this PR and you won't be reminded about this update again.

---

 - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box.

---

This PR has been generated by [WhiteSource Renovate](https://renovate.whitesourcesoftware.com). View repository job log [here](https://app.renovatebot.com/dashboard#github/googleapis/java-logging).

* build(deps): update dependency com.google.cloud:google-cloud-shared-config to v1.0.2 (#668)

[![WhiteSource Renovate](https://app.renovatebot.com/images/banner.svg)](https://renovatebot.com)

This PR contains the following updates:

| Package | Change | Age | Adoption | Passing | Confidence |
|---|---|---|---|---|---|
| [com.google.cloud:google-cloud-shared-config](https://togithub.com/googleapis/java-shared-config) | `1.0.1` -> `1.0.2` | [![age](https://badges.renovateapi.com/packages/maven/com.google.cloud:google-cloud-shared-config/1.0.2/age-slim)](https://docs.renovatebot.com/merge-confidence/) | [![adoption](https://badges.renovateapi.com/packages/maven/com.google.cloud:google-cloud-shared-config/1.0.2/adoption-slim)](https://docs.renovatebot.com/merge-confidence/) | [![passing](https://badges.renovateapi.com/packages/maven/com.google.cloud:google-cloud-shared-config/1.0.2/compatibility-slim/1.0.1)](https://docs.renovatebot.com/merge-confidence/) | [![confidence](https://badges.renovateapi.com/packages/maven/com.google.cloud:google-cloud-shared-config/1.0.2/confidence-slim/1.0.1)](https://docs.renovatebot.com/merge-confidence/) |

---

### Release Notes

<details>
<summary>googleapis/java-shared-config</summary>

### [`v1.0.2`](https://togithub.com/googleapis/java-shared-config/blob/master/CHANGELOG.md#&#8203;102-httpswwwgithubcomgoogleapisjava-shared-configcomparev101v102-2021-09-13)

[Compare Source](https://togithub.com/googleapis/java-shared-config/compare/v1.0.1...v1.0.2)

</details>

---

### Configuration

📅 **Schedule**: At any time (no schedule defined).

🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.

♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 **Ignore**: Close this PR and you won't be reminded about this update again.

---

 - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box.

---

This PR has been generated by [WhiteSource Renovate](https://renovate.whitesourcesoftware.com). View repository job log [here](https://app.renovatebot.com/dashboard#github/googleapis/java-logging).

* deps: update dependency com.google.cloud:google-cloud-shared-dependencies to v2.2.1 (#667)

[![WhiteSource Renovate](https://app.renovatebot.com/images/banner.svg)](https://renovatebot.com)

This PR contains the following updates:

| Package | Change | Age | Adoption | Passing | Confidence |
|---|---|---|---|---|---|
| [com.google.cloud:google-cloud-shared-dependencies](https://togithub.com/googleapis/java-shared-dependencies) | `2.2.0` -> `2.2.1` | [![age](https://badges.renovateapi.com/packages/maven/com.google.cloud:google-cloud-shared-dependencies/2.2.1/age-slim)](https://docs.renovatebot.com/merge-confidence/) | [![adoption](https://badges.renovateapi.com/packages/maven/com.google.cloud:google-cloud-shared-dependencies/2.2.1/adoption-slim)](https://docs.renovatebot.com/merge-confidence/) | [![passing](https://badges.renovateapi.com/packages/maven/com.google.cloud:google-cloud-shared-dependencies/2.2.1/compatibility-slim/2.2.0)](https://docs.renovatebot.com/merge-confidence/) | [![confidence](https://badges.renovateapi.com/packages/maven/com.google.cloud:google-cloud-shared-dependencies/2.2.1/confidence-slim/2.2.0)](https://docs.renovatebot.com/merge-confidence/) |

---

### Release Notes

<details>
<summary>googleapis/java-shared-dependencies</summary>

### [`v2.2.1`](https://togithub.com/googleapis/java-shared-dependencies/blob/master/CHANGELOG.md#&#8203;221-httpswwwgithubcomgoogleapisjava-shared-dependenciescompare220v221-2021-09-13)

[Compare Source](https://togithub.com/googleapis/java-shared-dependencies/compare/v2.2.0...v2.2.1)

</details>

---

### Configuration

📅 **Schedule**: At any time (no schedule defined).

🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.

♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 **Ignore**: Close this PR and you won't be reminded about this update again.

---

 - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box.

---

This PR has been Co-authored-by [WhiteSource Renovate](https://renovate.whitesourcesoftware.com). View repository job log [here](https://app.renovatebot.com/dashboard#github/googleapis/java-logging).

google-cloud-logging/clirr-ignored-differences.xml

@@ -8,10 +8,20 @@
         <className>com/google/cloud/logging/Logging</className>
         <method>* listLogs*(com.google.cloud.logging.Logging$ListOption[])</method>
     </difference>
+    <difference>
+        <differenceType>7012</differenceType>
+        <className>com/google/cloud/logging/Logging</className>
+        <method>com.google.cloud.logging.LogEntryServerStream tailLogEntries(com.google.cloud.logging.Logging$TailOption[])</method>
+    </difference>
     <!-- Added methods to com.google.cloud.logging.spi.v2.LoggingRpc interface with implementation in GrpcLoggingRpc is always okay -->
     <difference>
         <differenceType>7012</differenceType>
         <className>com/google/cloud/logging/spi/v2/LoggingRpc</className>
         <method>* listLogs(com.google.logging.v2.ListLogsRequest)</method>
     </difference>
+    <difference>
+        <differenceType>7012</differenceType>
+        <className>com/google/cloud/logging/spi/v2/LoggingRpc</className>
+        <method>com.google.api.gax.rpc.BidiStream getTailLogEntriesStream()</method>
+    </difference>
 </differences>

google-cloud-logging/src/main/java/com/google/cloud/logging/LogEntryIterator.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2021 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.logging;
+
+import com.google.common.collect.Lists;
+import com.google.logging.v2.TailLogEntriesResponse;
+import java.util.Iterator;
+import java.util.LinkedList;
+
+public class LogEntryIterator implements Iterator<LogEntry> {
+  private final Iterator<TailLogEntriesResponse> streamIterator;
+  private final LinkedList<LogEntry> buffer = new LinkedList<>();
+
+  LogEntryIterator(Iterator<TailLogEntriesResponse> streamIterator) {
+    this.streamIterator = streamIterator;
+  }
+
+  /** {@inheritDoc} */
+  @Override
+  public boolean hasNext() {
+    return !buffer.isEmpty() || streamIterator.hasNext();
+  }
+
+  /** {@inheritDoc} */
+  @Override
+  public LogEntry next() {
+    if (buffer.isEmpty()) {
+      TailLogEntriesResponse response = streamIterator.next();
+      buffer.addAll(Lists.transform(response.getEntriesList(), LogEntry.FROM_PB_FUNCTION));
+    }
+    return buffer.pop();
+  }
+}

google-cloud-logging/src/main/java/com/google/cloud/logging/LogEntryServerStream.java

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2021 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.logging;
+
+import com.google.api.gax.rpc.BidiStream;
+import com.google.common.collect.Lists;
+import com.google.logging.v2.TailLogEntriesRequest;
+import com.google.logging.v2.TailLogEntriesResponse;
+import java.util.Iterator;
+
+public class LogEntryServerStream implements Iterable<LogEntry> {
+  private final BidiStream<TailLogEntriesRequest, TailLogEntriesResponse> serverStream;
+
+  LogEntryServerStream(BidiStream<TailLogEntriesRequest, TailLogEntriesResponse> serverStream) {
+    this.serverStream = serverStream;
+  }
+
+  /** {@inheritDoc} */
+  @Override
+  public Iterator<LogEntry> iterator() {
+    return new LogEntryIterator(serverStream.iterator());
+  }
+
+  public BidiStream<TailLogEntriesRequest, TailLogEntriesResponse> getInternalStream() {
+    return serverStream;
+  }
+
+  public java.util.List<LogEntry> convert(TailLogEntriesResponse resp) {
+    return Lists.transform(resp.getEntriesList(), LogEntry.FROM_PB_FUNCTION);
+  }
+
+  /**
+   * Returns true if the next call to the iterator's hasNext() or next() is guaranteed to be
+   * nonblocking.
+   *
+   * @return If the call on any of the iterator's methods is guaranteed to be nonblocking.
+   */
+  public boolean isReceiveReady() {
+    return serverStream.isReceiveReady();
+  }
+
+  /**
+   * Cleanly cancels a partially consumed stream. The associated iterator will return false for the
+   * hasNext() in the next iteration. This maintains the contract that an observed true from
+   * hasNext() will yield an item in next(), but afterwards will return false.
+   */
+  public void cancel() {
+    serverStream.cancel();
+  }
+}