aws-sdk 1.3.4 → 1.3.5

data/lib/aws/simple_workflow/decision_task_collection.rb

@@ -0,0 +1,213 @@
+require 'uuidtools'
+
+# Copyright 2011-2012 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file 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.
+
+module AWS
+  class SimpleWorkflow
+
+    # Provides an interface to count, and receive decision tasks
+    # ({DecisionTask} objects) from the service.
+    #
+    # == Counting
+    #
+    # To get a count of decision tasks needing attention, call {#count}
+    # with a task list name:
+    #
+    #   domain.decision_tasks.count('my-task-list') #=> 7
+    #
+    # == Getting a single decision task
+    #
+    # To process a single task use {#poll_for_single_task}:
+    #
+    #   domain.decision_tasks.poll_for_single_task('my-task-list') do |task|
+    #     # this block is yielded to only if a task is found
+    #     # within 60 seconds.
+    #   end
+    #
+    # At the end of the block, the decision task is auto-completed.
+    # If you prefer you can omit the block and +nil+ or a {DecisionTask}
+    # will be returned.
+    #
+    #   if task = domain.decision_tasks.poll_for_single_task('my-task-list')
+    #     # you need to call complete! or the decision task will time out
+    #     task.complete!
+    #   end
+    #
+    # == Polling for Tasks in a Loop
+    #
+    # You can poll indefinetly for tasks in a loop with {#poll}:
+    #
+    #   domain.decision_tasks.poll('my-task-list') do |task|
+    #     # yields once for every decision task found 
+    #   end
+    #
+    # Just like the block form above, the decision task is auto completed at
+    # the end of the block.  Please note, if you call +break+ or +return+ 
+    # from inside the block, you *MUST* call {DecisionTask#complete!} or
+    # the task will timeout.
+    #
+    # == Events and Decisions
+    #
+    # Each decision task provides an enumerable collection of both
+    # new events ({DecisionTask#new_events}) and all events 
+    # ({DecisionTask#events}).  
+    # 
+    # Based on the events in the workflow execution history, you should
+    # call methods on the decision task.  See {DecisionTask} for
+    # a complete list of decision methods.
+    #
+    class DecisionTaskCollection
+
+      include Core::Model
+      include OptionFormatters
+
+      # @private
+      def initialize domain, options = {}
+        @domain = domain
+        super
+      end
+
+      # @return [Domain]
+      attr_reader :domain
+
+      # Returns the number of decision tasks in the specified +task_list+. 
+      #
+      # @note This operation is eventually consistent. The results are best 
+      #   effort and may not exactly reflect recent updates and changes.
+      #
+      # @param [String] task_list Name of the task list to count 
+      #   decision tasks for.
+      #
+      # @return [Integer] Returns the number of descision tasks for the 
+      #   given +task_list+.
+      #
+      def count task_list
+        options = {}
+        options[:domain] = domain.name
+        options[:task_list] = { :name => task_list }
+        response = client.count_pending_decision_tasks(options)
+        Count.new(response.data['count'], response.data['truncated'])
+      end
+
+      # Polls the service for a single decision task.  The service may
+      # hold the request for up to 60 seconds before responding.  
+      #
+      #   # try to get a single task, may return nil when no tasks available
+      #   task = domain.decision_tasks.poll_for_single_task('task-list')
+      #   if task
+      #     # make decisions ...
+      #     task.complete!
+      #   end
+      #
+      # You can optionally pass a block and that will only be yielded
+      # to when a decision task is available within the 60 seconds.
+      #
+      #   domain.decision_tasks.poll_for_single_task('task-list') do |task|
+      #      # make decisions
+      #      # task.complete! is called for you at the end of the block
+      #   end
+      #
+      # With the block form you do not need to call #complete! on the 
+      # decision task.  It will be called when the block exists.
+      #
+      # @note If you are not using the block form you must call 
+      #   {DecisionTask#complete!} yourself or your decision task will
+      #   timeout.
+      #
+      # @param [String] task_list Specifies the task list to poll for 
+      #   decision tasks.
+      #
+      # @param [Hash] options
+      #
+      # @option options [String] :identity The identity of the decider 
+      #   requesting a decision task.  This will be recorded in the
+      #   DecisionTaskStarted event in the workflow history. 
+      #   If +:identity+ is not passed, a random UUID will be generated.
+      #
+      # @option options [Boolean] :reverse_event_order (false)  When true, 
+      #   the history events on the decision task will enumerate in 
+      #   reverse chronological order (newest events first).  By default 
+      #   the events are enumerated in chronological order (oldest first).
+      #
+      # @option options [Integer] :event_batch_size (1000) When enumerating
+      #   events on the decision task, multiple requests may be required
+      #   to fetch all of the events.  You can specify the maximum number
+      #   of events to request each time (must not be greater than 1000).
+      #
+      # @yieldparam [DecisionTask] decision_task
+      # 
+      # @return [DecisionTask,nil] Returns a decision task or +nil+.  If
+      #   a block was passed then +nil+ is always returned.  If a block
+      #   is not passed, then +nil+ or a {DecisionTask} will be returned.
+      #
+      def poll_for_single_task task_list, options = {}, &block
+
+        client_opts = {}
+        client_opts[:domain] = domain.name
+        client_opts[:identity] = options[:identity] if options[:identity]
+        client_opts[:task_list] = { :name => task_list }
+        client_opts[:maximum_page_size] = options[:event_batch_size] || 1000
+        client_opts[:reverse_order] = options.key?(:reverse_event_order) ?
+          options[:reverse_event_order] : false
+
+        response = client.poll_for_decision_task(client_opts)
+
+        if response.data['taskToken']
+          decision_task = DecisionTask.new(domain, client_opts, response.data)
+          if block_given?
+            yield(decision_task)
+            decision_task.complete! unless decision_task.responded?
+            nil
+          else
+            decision_task
+          end
+        else
+          nil
+        end
+
+      end
+
+      # Polls indefinetly for decision tasks.  Each deicsion task found is
+      # yielded to the block.  At the end of the block the decision task
+      # is auto-completed ({DecisionTask#complete!} is called).
+      #
+      #   # yields once for each decision task found, indefinetly
+      #   domain.decision_tasks.poll do |decision_task|
+      #     # make decisions here
+      #   end
+      #
+      # @note If you to terminate the block (by calling +break+ or +return+)
+      #   then it is your responsibility to call #complete! on the decision 
+      #   task.
+      #
+      # @param (see #poll_for_single_task)
+      #
+      # @option (see #poll_for_single_task)
+      # 
+      # @yieldparam [DecisionTask] decision_task
+      #
+      # @return [nil]
+      #
+      def poll task_list, options = {}, &block
+        loop do 
+          poll_for_single_task(task_list, options) do |decision_task|
+            yield(decision_task)
+          end
+        end
+        nil
+      end
+
+    end
+  end
+end

data/lib/aws/simple_workflow/domain.rb

@@ -0,0 +1,122 @@
+# Copyright 2011-2012 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file 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.
+
+module AWS
+  class SimpleWorkflow
+
+    # Domains are used to organize workflows types and activities for 
+    # an account.
+    #
+    # @attr_reader [String,nil] description Returns 
+    #
+    # @attr_reader [Integer,Symbol] retention_period Returns the retention
+    #   period for this domain. The return value may be an integer (number
+    #   of days history is kept around) or the symbol +:none+, implying
+    #   no expiry of closed workflow executions.
+    #
+    # @attr_reader [Symbol] status Returns the domain's status.  Status will
+    #   be either +:registered+ or +:deprecated+.
+    #
+    class Domain < Resource
+
+      include OptionFormatters
+
+      # @private
+      def initialize name, options = {}
+        @name = name.to_s
+        super(options)
+      end
+
+      # @return [String] Returns the name of this domain.
+      attr_reader :name
+
+      info_attribute :description, :static => true
+
+      info_attribute :status, :to_sym => true
+
+      config_attribute :retention_period, 
+        :as => 'workflowExecutionRetentionPeriodInDays',
+        :duration => true,
+        :static => true
+
+      # @return [WorkflowTypeCollection]
+      def workflow_types
+        WorkflowTypeCollection.new(self)
+      end
+
+      # @return [ActivityTypeCollection]
+      def activity_types
+        ActivityTypeCollection.new(self)
+      end
+
+      # @return [WorkflowExecutionCollection]
+      def workflow_executions
+        WorkflowExecutionCollection.new(self)
+      end
+
+      # @return [DecisionTaskCollection]
+      def decision_tasks
+        DecisionTaskCollection.new(self)
+      end
+
+      # @return [ActivityTaskCollection]
+      def activity_tasks
+        ActivityTaskCollection.new(self)
+      end
+
+      # @return [Boolean] Returns true if this domain has been deprecated.
+      def deprecated?
+        self.status == :deprecated
+      end
+
+      # Deprecates the domain. After a domain has been deprecated it cannot 
+      # be used to create new workflow executions or register new types. 
+      # However, you can still use visibility actions on this domain. 
+      #
+      # Deprecating a domain also deprecates all activity and workflow 
+      # types registered in the domain. Executions that were started 
+      # before the domain was deprecated will continue to run.
+      #
+      # @return [nil] 
+      #
+      def deprecate
+        client.deprecate_domain(:name => name)
+        nil
+      end
+      alias_method :delete, :deprecate
+
+      provider(:describe_domain) do |provider|
+        provider.provides *info_attributes.keys
+        provider.provides *config_attributes.keys
+        provider.find do |resp|
+          if resp.data['domainInfo']['name'] == name
+            resp.data['domainInfo'].merge(resp.data['configuration'])
+          end
+        end
+      end
+
+      provider(:list_domains) do |provider|
+        provider.provides *info_attributes.keys
+        provider.find do |resp|
+          resp.data['domainInfos'].find{|d| d['name'] == name }
+        end
+      end
+
+      protected
+      def resource_identifiers
+        [[:name,name]]
+      end
+
+    end
+  end
+end

data/lib/aws/simple_workflow/domain_collection.rb

@@ -0,0 +1,169 @@
+# Copyright 2011-2012 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file 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.
+
+module AWS
+  class SimpleWorkflow
+
+    # The primary interface for registerign, listing and deprecating
+    # domains.
+    #
+    # == Creating a Domain
+    #
+    # To create a domain you need to pass a unique name to #create.
+    #
+    #   domain = simple_workflow.domains.create('my-domain', :none)
+    #   #=> #<AWS::SimpleWorkflow::Domain name:my-domain>
+    #
+    # == Gettin a Domain
+    #
+    # Domains are indexed by their name.
+    #
+    #   domain = simple_workflow.domains['my-domain']
+    #
+    # == Enumerating Domains
+    #
+    # You can call Enumerable methods on a domain collection to iterate
+    # the domains controlled by your account.
+    #
+    #   simple_workflow.domains.each {|domain| ... }
+    #
+    # By default only registered domains are enumerated.  If you would like
+    # to enumerate deprecated (deleted) domains you need to pass the
+    # +:deprecated+ option.
+    #
+    #   # returns an array of names for all deprecated domains
+    #   simple_workflow.domains.deprecated.map(&:name)
+    #
+    # See {AWS::Core::Collection} to see other useful methods you can 
+    # call against a domain collection (e.g. #enum, #page, #each_batch).
+    #
+    class DomainCollection
+
+      include OptionFormatters
+      include Core::Collection::Limitable
+
+      def initialize options = {}
+        
+        @registration_status = options[:registration_status] ? 
+          options[:registration_status].to_s.upcase : 'REGISTERED'
+
+        @reverse_order = options.key?(:reverse_order) ?
+          !!options[:reverse_order] : false
+
+        super(options)
+
+      end
+
+      # Registers a new domain.
+      #
+      #   # register a domain named 'domain' that has no expiry on workflow
+      #   # execution history
+      #   domain = AWS::SimpleWorkflow.new.domains.register('domain', :none)
+      #
+      # @param [String] name Name of the domain to register. The name must 
+      #   be unique.  
+      #
+      # @param [Integer,:none] retention_period A duration (in days) 
+      #   for which the record (including the history) of workflow 
+      #   executions in this domain should be kept by the service. 
+      #   After the retention period, the workflow execution will not be 
+      #   available in the results of visibility calls.
+      #
+      #   If you pass the symbol +:none+ then there is no expiration for
+      #   workflow execution history (effectively an infinite rention
+      #   period).
+      # 
+      # @param [Hash] options
+      #
+      # @option [String] :description (nil) Textual description of the domain.
+      #
+      # @return [Domain] Returns the newly created {Domain} object.
+      #
+      def register name, retention_period, options = {}
+
+        client_opts = {}
+        client_opts[:name] = name
+        client_opts[:workflow_execution_retention_period_in_days] = retention_period
+        client_opts[:description] = options[:description] if options[:description]
+
+        duration_opts(client_opts, :workflow_execution_retention_period_in_days)
+        client.register_domain(client_opts)
+
+        client_opts[:retention_period] = retention_period.to_s =~ /^\d+$/ ?
+          retention_period.to_i : retention_period.to_s.downcase.to_sym
+
+        Domain.new(name, client_opts.merge(:config => config))
+
+      end
+      alias_method :create, :register
+
+      # @return [Domain] Returns the domain with the given name.
+      def [] name
+        Domain.new(name, :config => config)
+      end
+
+      # @return [DomainCollection] Returns a domain collection that
+      #   will only enumerate registered domains.
+      def registered
+        collection_with(:registration_status => 'REGISTERED')
+      end
+
+      # @return [DomainCollection] Returns a domain collection that
+      #   will only enumerate deprecated (deleted) domains.
+      def deprecated
+        collection_with(:registration_status => 'DEPRECATED')
+      end
+
+      # @return [DomainCollection] Returns a domain collection that
+      #   enumerates domains in reverse alphabetical order.  Default
+      #   ordering is ascending alphabetical.
+      def reverse_order
+        collection_with(:reverse_order => true)
+      end
+
+      protected
+      def collection_with options = {}
+        self.class.new({
+          :registration_status => @registration_status,
+          :reverse_order => @reverse_order,
+          :config => config,
+        }.merge(options))
+      end
+
+      protected
+      def _each_item next_token, limit, options = {}, &block
+
+        options[:maximum_page_size] = limit if limit
+        options[:next_page_token] = next_token if next_token
+        options[:registration_status] ||= @registration_status
+        options[:reverse_order] = @reverse_order unless 
+          options.has_key?(:reverse_order)
+
+        response = client.list_domains(options)
+        response.data['domainInfos'].each do |desc|
+
+          domain = Domain.new_from(:list_domains, desc,
+            desc['name'], :config => config)
+
+          yield(domain)
+          
+        end
+
+        response.data['nextPageToken']
+
+      end
+
+    end
+
+  end
+end