google-cloud-pubsub 0.20.1 → 0.21.0

data/lib/google/cloud/pubsub/subscription.rb

@@ -27,10 +27,9 @@ module Google
       # specific {Topic}, to be delivered to the subscribing application.
       #
       # @example
-      #   require "google/cloud"
+      #   require "google/cloud/pubsub"
       #
-      #   gcloud = Google::Cloud.new
-      #   pubsub = gcloud.pubsub
+      #   pubsub = Google::Cloud::Pubsub.new
       #
       #   sub = pubsub.subscription "my-topic-sub"
       #   msgs = sub.pull
@@ -38,7 +37,7 @@ module Google
       #
       class Subscription
         ##
-        # @private The gRPC Service object.
+        # @private The Service object.
         attr_accessor :service
 
         ##
@@ -77,10 +76,9 @@ module Google
         # @return [Topic]
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   sub = pubsub.subscription "my-topic-sub"
         #   sub.topic.name #=> "projects/my-project/topics/my-topic"
@@ -122,10 +120,9 @@ module Google
         # Determines whether the subscription exists in the Pub/Sub service.
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   sub = pubsub.subscription "my-topic-sub"
         #   sub.exists? #=> true
@@ -147,10 +144,9 @@ module Google
         # HTTP call.
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   sub = pubsub.get_subscription "my-topic-sub"
         #   sub.lazy? #=> false
@@ -166,10 +162,9 @@ module Google
         # @return [Boolean] Returns `true` if the subscription was deleted.
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   sub = pubsub.subscription "my-topic-sub"
         #   sub.delete
@@ -200,28 +195,25 @@ module Google
         # @return [Array<Google::Cloud::Pubsub::ReceivedMessage>]
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   sub = pubsub.subscription "my-topic-sub"
         #   sub.pull.each { |msg| msg.acknowledge! }
         #
         # @example A maximum number of messages returned can also be specified:
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   sub = pubsub.subscription "my-topic-sub", max: 10
         #   sub.pull.each { |msg| msg.acknowledge! }
         #
         # @example The call can block until messages are available:
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   sub = pubsub.subscription "my-topic-sub"
         #   msgs = sub.pull immediate: false
@@ -255,10 +247,9 @@ module Google
         # @return [Array<Google::Cloud::Pubsub::ReceivedMessage>]
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   sub = pubsub.subscription "my-topic-sub"
         #   msgs = sub.wait_for_messages
@@ -285,10 +276,9 @@ module Google
         # @yieldparam [ReceivedMessage] msg the newly received message
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   sub = pubsub.subscription "my-topic-sub"
         #   sub.listen do |msg|
@@ -296,10 +286,9 @@ module Google
         #   end
         #
         # @example Limit number of messages pulled per API request with `max`:
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   sub = pubsub.subscription "my-topic-sub"
         #   sub.listen max: 20 do |msg|
@@ -307,10 +296,9 @@ module Google
         #   end
         #
         # @example Automatically acknowledge messages with `autoack`:
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   sub = pubsub.subscription "my-topic-sub"
         #   sub.listen autoack: true do |msg|
@@ -340,10 +328,9 @@ module Google
         #   {ReceivedMessage} objects or ack_id values.
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   sub = pubsub.subscription "my-topic-sub"
         #   messages = sub.pull
@@ -374,10 +361,9 @@ module Google
         #   {ReceivedMessage} objects or ack_id values.
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   sub = pubsub.subscription "my-topic-sub"
         #   messages = sub.pull
@@ -394,7 +380,7 @@ module Google
         # Gets the [Cloud IAM](https://cloud.google.com/iam/) access control
         # policy for this subscription.
         #
-        # @see https://cloud.google.com/pubsub/reference/rpc/google.iam.v1#iampolicy
+        # @see https://cloud.google.com/pubsub/docs/reference/rpc/google.iam.v1#iampolicy
         #   google.iam.v1.IAMPolicy
         #
         # @param [Boolean] force Force the latest policy to be retrieved from
@@ -412,30 +398,27 @@ module Google
         # @return [Policy] the current Cloud IAM Policy for this subscription
         #
         # @example Policy values are memoized to reduce the number of API calls:
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #   sub = pubsub.subscription "my-subscription"
         #
         #   policy = sub.policy # API call
         #   policy_2 = sub.policy # No API call
         #
         # @example Use `force` to retrieve the latest policy from the service:
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #   sub = pubsub.subscription "my-subscription"
         #
         #   policy = sub.policy force: true # API call
         #   policy_2 = sub.policy force: true # API call
         #
         # @example Update the policy by passing a block:
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #   sub = pubsub.subscription "my-subscription"
         #
         #   policy = sub.policy do |p|
@@ -464,17 +447,16 @@ module Google
         # You can also update the policy by passing a block to {#policy}, which
         # will call this method internally after the block completes.
         #
-        # @see https://cloud.google.com/pubsub/reference/rpc/google.iam.v1#iampolicy
+        # @see https://cloud.google.com/pubsub/docs/reference/rpc/google.iam.v1#iampolicy
         #   google.iam.v1.IAMPolicy
         #
         # @param [Policy] new_policy a new or modified Cloud IAM Policy for this
         #   subscription
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #   sub = pubsub.subscription "my-subscription"
         #
         #   policy = sub.policy # API call
@@ -512,10 +494,9 @@ module Google
         # @return [Array<String>] The permissions that have access.
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #   sub = pubsub.subscription "my-subscription"
         #   perms = sub.test_permissions "pubsub.subscriptions.get",
         #                                "pubsub.subscriptions.consume"

data/lib/google/cloud/pubsub/subscription/list.rb

@@ -44,10 +44,9 @@ module Google
           # @return [Boolean]
           #
           # @example
-          #   require "google/cloud"
+          #   require "google/cloud/pubsub"
           #
-          #   gcloud = Google::Cloud.new
-          #   pubsub = gcloud.pubsub
+          #   pubsub = Google::Cloud::Pubsub.new
           #
           #   subscriptions = pubsub.subscriptions
           #   if subscriptions.next?
@@ -64,10 +63,9 @@ module Google
           # @return [Subscription::List]
           #
           # @example
-          #   require "google/cloud"
+          #   require "google/cloud/pubsub"
           #
-          #   gcloud = Google::Cloud.new
-          #   pubsub = gcloud.pubsub
+          #   pubsub = Google::Cloud::Pubsub.new
           #
           #   subscriptions = pubsub.subscriptions
           #   if subscriptions.next?
@@ -103,10 +101,9 @@ module Google
           # @return [Enumerator]
           #
           # @example Iterating each subscription by passing a block:
-          #   require "google/cloud"
+          #   require "google/cloud/pubsub"
           #
-          #   gcloud = Google::Cloud.new
-          #   pubsub = gcloud.pubsub
+          #   pubsub = Google::Cloud::Pubsub.new
           #
           #   subscriptions = pubsub.subscriptions
           #   subscriptions.all do |subscription|
@@ -114,10 +111,9 @@ module Google
           #   end
           #
           # @example Using the enumerator by not passing a block:
-          #   require "google/cloud"
+          #   require "google/cloud/pubsub"
           #
-          #   gcloud = Google::Cloud.new
-          #   pubsub = gcloud.pubsub
+          #   pubsub = Google::Cloud::Pubsub.new
           #
           #   subscriptions = pubsub.subscriptions
           #   all_names = subscriptions.all.map do |subscription|
@@ -125,10 +121,9 @@ module Google
           #   end
           #
           # @example Limit the number of API calls made:
-          #   require "google/cloud"
+          #   require "google/cloud/pubsub"
           #
-          #   gcloud = Google::Cloud.new
-          #   pubsub = gcloud.pubsub
+          #   pubsub = Google::Cloud::Pubsub.new
           #
           #   subscriptions = pubsub.subscriptions
           #   subscriptions.all(request_limit: 10) do |subscription|

data/lib/google/cloud/pubsub/topic.rb

@@ -28,21 +28,20 @@ module Google
       # A named resource to which messages are published.
       #
       # @example
-      #   require "google/cloud"
+      #   require "google/cloud/pubsub"
       #
-      #   gcloud = Google::Cloud.new
-      #   pubsub = gcloud.pubsub
+      #   pubsub = Google::Cloud::Pubsub.new
       #
       #   topic = pubsub.topic "my-topic"
       #   topic.publish "task completed"
       #
       class Topic
         ##
-        # @private The gRPC Service object.
+        # @private The Service object.
         attr_accessor :service
 
         ##
-        # @private The gRPC Google::Pubsub::V1::Topic object.
+        # @private The Google::Pubsub::V1::Topic object.
         attr_accessor :grpc
 
         ##
@@ -77,10 +76,9 @@ module Google
         # @return [Boolean] Returns `true` if the topic was deleted.
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   topic = pubsub.topic "my-topic"
         #   topic.delete
@@ -108,30 +106,27 @@ module Google
         # @return [Google::Cloud::Pubsub::Subscription]
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   topic = pubsub.topic "my-topic"
         #   sub = topic.subscribe "my-topic-sub"
         #   puts sub.name # => "my-topic-sub"
         #
         # @example The name is optional, and will be generated if not given:
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   topic = pubsub.topic "my-topic"
         #   sub = topic.subscribe "my-topic-sub"
         #   puts sub.name # => "generated-sub-name"
         #
         # @example Wait 2 minutes for acknowledgement and push all to endpoint:
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   topic = pubsub.topic "my-topic"
         #   sub = topic.subscribe "my-topic-sub",
@@ -160,20 +155,18 @@ module Google
         #   the subscription does not exist.
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   topic = pubsub.topic "my-topic"
         #   subscription = topic.subscription "my-topic-subscription"
         #   puts subscription.name
         #
         # @example Skip the lookup against the service with `skip_lookup`:
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   # No API call is made to retrieve the subscription information.
         #   subscription = pubsub.subscription "my-sub", skip_lookup: true
@@ -201,10 +194,9 @@ module Google
         # @return [Array<Subscription>] (See {Subscription::List})
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   topic = pubsub.topic "my-topic"
         #   subscription = topic.subscriptions
@@ -213,10 +205,9 @@ module Google
         #   end
         #
         # @example Retrieve all subscriptions: (See {Subscription::List#all})
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   topic = pubsub.topic "my-topic"
         #   subscription = topic.subscriptions
@@ -247,28 +238,25 @@ module Google
         #   block.
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   topic = pubsub.topic "my-topic"
         #   msg = topic.publish "new-message"
         #
         # @example A message can be published using a File object:
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   topic = pubsub.topic "my-topic"
         #   msg = topic.publish File.open("message.txt")
         #
         # @example Additionally, a message can be published with attributes:
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   topic = pubsub.topic "my-topic"
         #   msg = topic.publish "new-message",
@@ -276,10 +264,9 @@ module Google
         #                       this: :that
         #
         # @example Multiple messages can be sent at the same time using a block:
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   topic = pubsub.topic "my-topic"
         #   msgs = topic.publish do |t|
@@ -300,7 +287,7 @@ module Google
         # Gets the [Cloud IAM](https://cloud.google.com/iam/) access control
         # policy for this topic.
         #
-        # @see https://cloud.google.com/pubsub/reference/rpc/google.iam.v1#iampolicy
+        # @see https://cloud.google.com/pubsub/docs/reference/rpc/google.iam.v1#iampolicy
         #   google.iam.v1.IAMPolicy
         #
         # @param [Boolean] force Force the latest policy to be retrieved from
@@ -318,30 +305,27 @@ module Google
         # @return [Policy] the current Cloud IAM Policy for this topic
         #
         # @example Policy values are memoized to reduce the number of API calls:
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #   topic = pubsub.topic "my-topic"
         #
         #   policy = topic.policy # API call
         #   policy_2 = topic.policy # No API call
         #
         # @example Use `force` to retrieve the latest policy from the service:
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #   topic = pubsub.topic "my-topic"
         #
         #   policy = topic.policy force: true # API call
         #   policy_2 = topic.policy force: true # API call
         #
         # @example Update the policy by passing a block:
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #   topic = pubsub.topic "my-topic"
         #
         #   policy = topic.policy do |p|
@@ -370,17 +354,16 @@ module Google
         # You can also update the policy by passing a block to {#policy}, which
         # will call this method internally after the block completes.
         #
-        # @see https://cloud.google.com/pubsub/reference/rpc/google.iam.v1#iampolicy
+        # @see https://cloud.google.com/pubsub/docs/reference/rpc/google.iam.v1#iampolicy
         #   google.iam.v1.IAMPolicy
         #
         # @param [Policy] new_policy a new or modified Cloud IAM Policy for this
         #   topic
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #   topic = pubsub.topic "my-topic"
         #
         #   policy = topic.policy # API call
@@ -419,10 +402,9 @@ module Google
         # @return [Array<Strings>] The permissions that have access.
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #   topic = pubsub.topic "my-topic"
         #   perms = topic.test_permissions "pubsub.topics.get",
         #                                  "pubsub.topics.publish"
@@ -441,10 +423,9 @@ module Google
         # Determines whether the topic exists in the Pub/Sub service.
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   topic = pubsub.topic "my-topic"
         #   topic.exists? #=> true
@@ -463,10 +444,9 @@ module Google
         # Determines whether the topic object was created with an HTTP call.
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/pubsub"
         #
-        #   gcloud = Google::Cloud.new
-        #   pubsub = gcloud.pubsub
+        #   pubsub = Google::Cloud::Pubsub.new
         #
         #   topic = pubsub.topic "my-topic"
         #   topic.lazy? #=> false