operaton-bpm-client 0.1.0

data/lib/operaton/bpm/client/topic/impl/topic_subscription_impl.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "../topic_subscription"
+
+module Operaton
+  module Bpm
+    module Client
+      module Topic
+        module Impl
+          # Mirrors org.operaton.bpm.client.topic.impl.TopicSubscriptionImpl
+          class TopicSubscriptionImpl
+            include TopicSubscription
+
+            attr_reader :topic_name, :lock_duration, :external_task_handler, :variable_names, :business_key
+            attr_accessor :process_definition_id, :process_definition_id_in,
+                          :process_definition_key, :process_definition_key_in,
+                          :process_definition_version_tag, :tenant_id_in
+
+            def initialize(topic_name, lock_duration, external_task_handler,
+                           topic_subscription_manager, variable_names, business_key)
+              @topic_name = topic_name
+              @lock_duration = lock_duration
+              @external_task_handler = external_task_handler
+              @topic_subscription_manager = topic_subscription_manager
+              @variable_names = variable_names
+              @business_key = business_key
+              @local_variables = false
+              @without_tenant_id = false
+              @include_extension_properties = false
+              @process_variables = nil
+            end
+
+            def close
+              @topic_subscription_manager.unsubscribe(self)
+            end
+
+            def local_variables?
+              @local_variables
+            end
+
+            attr_writer :local_variables
+
+            attr_reader :process_variables
+
+            def process_variables=(process_variables)
+              @process_variables ||= {}
+              @process_variables.merge!(process_variables)
+            end
+
+            def without_tenant_id?
+              @without_tenant_id
+            end
+
+            attr_writer :without_tenant_id
+
+            def include_extension_properties?
+              @include_extension_properties
+            end
+
+            attr_writer :include_extension_properties
+
+            # Java equality is based on class and topic name only.
+            def ==(other)
+              other.instance_of?(self.class) && topic_name == other.topic_name
+            end
+            alias eql? ==
+
+            def hash
+              [self.class, topic_name].hash
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/operaton/bpm/client/topic/impl/topic_subscription_manager.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require_relative "topic_subscription_manager_logger"
+require_relative "dto/topic_request_dto"
+require_relative "dto/fetch_and_lock_response_dto"
+require_relative "../../task/impl/external_task_service_impl"
+require_relative "../../task/external_task_handler"
+require_relative "../../backoff/error_aware_backoff_strategy"
+require_relative "../../impl/engine_client_exception"
+require_relative "../../impl/external_task_client_logger"
+require_relative "../../exceptions"
+
+module Operaton
+  module Bpm
+    module Client
+      module Topic
+        module Impl
+          # Mirrors org.operaton.bpm.client.topic.impl.TopicSubscriptionManager.
+          # Runs the fetch-and-lock loop on a dedicated thread.
+          class TopicSubscriptionManager
+            attr_reader :engine_client
+
+            def initialize(engine_client, typed_values, client_lock_duration)
+              @engine_client = engine_client
+              @subscriptions = []
+              @subscriptions_mutex = Mutex.new
+              @task_topic_requests = []
+              @external_task_handlers = {}
+              @client_lock_duration = client_lock_duration
+              @typed_values = typed_values
+              @external_task_service = Task::Impl::ExternalTaskServiceImpl.new(engine_client)
+              @is_backoff_strategy_disabled = false
+              @backoff_strategy = nil
+
+              @is_running = false
+              @state_mutex = Mutex.new
+              @acquisition_monitor = Mutex.new
+              @is_waiting = ConditionVariable.new
+              @resume_signaled = false
+              @thread = nil
+            end
+
+            def run
+              while running?
+                begin
+                  acquire
+                rescue StandardError => e
+                  logger.exception_while_acquiring_tasks(e)
+                end
+              end
+            end
+
+            def stop
+              @state_mutex.synchronize do
+                return unless @is_running
+
+                @is_running = false
+              end
+              resume
+              begin
+                @thread&.join
+              rescue StandardError => e
+                logger.exception_while_shutting_down(e)
+              end
+            end
+
+            def start
+              @state_mutex.synchronize do
+                return if @is_running
+
+                @is_running = true
+                @thread = Thread.new { run }
+                @thread.name = "TopicSubscriptionManager"
+              end
+            end
+
+            def subscribe(subscription)
+              @subscriptions_mutex.synchronize do
+                if @subscriptions.include?(subscription)
+                  raise logger.topic_name_already_subscribed_exception(subscription.topic_name)
+                end
+
+                @subscriptions << subscription
+              end
+              resume
+            end
+
+            def unsubscribe(subscription)
+              @subscriptions_mutex.synchronize { @subscriptions.delete(subscription) }
+            end
+
+            def subscriptions
+              @subscriptions_mutex.synchronize { @subscriptions.dup }
+            end
+
+            def running?
+              @state_mutex.synchronize { @is_running }
+            end
+            alias is_running? running?
+
+            def backoff_strategy=(backoff_strategy)
+              @backoff_strategy = backoff_strategy
+            end
+
+            def disable_backoff_strategy
+              @is_backoff_strategy_disabled = true
+            end
+
+            protected
+
+            def acquire
+              @task_topic_requests.clear
+              @external_task_handlers.clear
+              subscriptions.each { |subscription| prepare_acquisition(subscription) }
+
+              return if @task_topic_requests.empty?
+
+              fetch_and_lock_response = fetch_and_lock(@task_topic_requests)
+
+              fetch_and_lock_response.external_tasks.each do |external_task|
+                topic_name = external_task.topic_name
+                task_handler = @external_task_handlers[topic_name]
+
+                if task_handler
+                  handle_external_task(external_task, task_handler)
+                else
+                  logger.task_handler_is_null(topic_name)
+                end
+              end
+
+              run_backoff_strategy(fetch_and_lock_response) unless @is_backoff_strategy_disabled
+            end
+
+            def prepare_acquisition(subscription)
+              @task_topic_requests << Dto::TopicRequestDto.from_topic_subscription(subscription, @client_lock_duration)
+              @external_task_handlers[subscription.topic_name] = subscription.external_task_handler
+            end
+
+            def fetch_and_lock(task_topic_requests)
+              logger.fetch_and_lock(task_topic_requests)
+              external_tasks = @engine_client.fetch_and_lock(task_topic_requests)
+              Dto::FetchAndLockResponseDto.new(external_tasks)
+            rescue Client::Impl::EngineClientException => e
+              logger.exception_while_performing_fetch_and_lock(e)
+              Dto::FetchAndLockResponseDto.new(
+                client_logger.handled_engine_client_exception("fetching and locking task", e)
+              )
+            end
+
+            def handle_external_task(external_task, task_handler)
+              variables = external_task.variables
+              external_task.received_variable_map = @typed_values.wrap_variables(external_task, variables)
+
+              begin
+                Task::ExternalTaskHandler.invoke(task_handler, external_task, @external_task_service)
+              rescue ExternalTaskClientException => e
+                logger.exception_on_external_task_service_method_invocation(external_task.topic_name, e)
+              rescue StandardError => e
+                logger.exception_while_executing_external_task_handler(external_task.topic_name, e)
+              end
+            end
+
+            def run_backoff_strategy(fetch_and_lock_response)
+              external_tasks = fetch_and_lock_response.external_tasks
+
+              if @backoff_strategy.is_a?(Backoff::ErrorAwareBackoffStrategy) ||
+                 @backoff_strategy.method(:reconfigure).arity != 1
+                @backoff_strategy.reconfigure(external_tasks, fetch_and_lock_response.error)
+              else
+                @backoff_strategy.reconfigure(external_tasks)
+              end
+
+              suspend(@backoff_strategy.calculate_backoff_time)
+            rescue StandardError => e
+              logger.exception_while_executing_backoff_strategy_method(e)
+            end
+
+            def suspend(wait_time_ms)
+              return unless wait_time_ms.positive? && running?
+
+              @acquisition_monitor.synchronize do
+                end_time = monotonic_ms + wait_time_ms
+                remaining = wait_time_ms
+
+                while remaining.positive? && running?
+                  break if @resume_signaled
+
+                  @is_waiting.wait(@acquisition_monitor, remaining / 1000.0)
+                  break if @resume_signaled
+
+                  remaining = end_time - monotonic_ms
+                end
+
+                logger.timeout(wait_time_ms) if remaining <= 0 && running? && !@resume_signaled
+                @resume_signaled = false
+              end
+            end
+
+            def resume
+              @acquisition_monitor.synchronize do
+                @resume_signaled = true
+                @is_waiting.signal
+              end
+            end
+
+            def monotonic_ms
+              Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+            end
+
+            def logger
+              Client::Impl::ExternalTaskClientLogger.topic_subscription_manager_logger
+            end
+
+            def client_logger
+              Client::Impl::ExternalTaskClientLogger.client_logger
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/operaton/bpm/client/topic/impl/topic_subscription_manager_logger.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "../../impl/external_task_client_logger"
+
+module Operaton
+  module Bpm
+    module Client
+      module Topic
+        module Impl
+          # Mirrors org.operaton.bpm.client.topic.impl.TopicSubscriptionManagerLogger
+          class TopicSubscriptionManagerLogger < Client::Impl::ExternalTaskClientLogger
+            def exception_while_performing_fetch_and_lock(error)
+              log_error("001", "Exception while fetching and locking task.", error)
+            end
+
+            def exception_while_executing_external_task_handler(topic_name, error)
+              log_error("002", "Exception while executing external task handler '#{topic_name}'.", error)
+            end
+
+            def exception_while_shutting_down(error)
+              log_error("003", "Exception while shutting down:", error)
+            end
+
+            def exception_on_external_task_service_method_invocation(topic_name, error)
+              log_error("004", "Exception on external task service method invocation for topic '#{topic_name}':", error)
+            end
+
+            def exception_while_executing_backoff_strategy_method(error)
+              log_error("005", "Exception while executing back off strategy method.", error)
+            end
+
+            def exception_while_acquiring_tasks(error)
+              log_error("006", "Exception while acquiring tasks.", error)
+            end
+
+            def task_handler_is_null(topic_name)
+              log_error("007", "Task handler is null for topic '#{topic_name}'.")
+            end
+
+            def fetch_and_lock(subscriptions)
+              log_debug("008", "Fetch and lock new external tasks for #{subscriptions.size} topics")
+            end
+
+            def timeout(wait_time)
+              log_debug("009", "Timed out after #{wait_time} ms without a signal.")
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/operaton/bpm/client/topic/topic_subscription.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Operaton
+  module Bpm
+    module Client
+      module Topic
+        # Mirrors org.operaton.bpm.client.topic.TopicSubscription. Documents
+        # the contract implemented by Topic::Impl::TopicSubscriptionImpl.
+        module TopicSubscription
+          INTERFACE_METHODS = %i[
+            close topic_name lock_duration external_task_handler variable_names
+            local_variables? business_key process_definition_id process_definition_id_in
+            process_definition_key process_definition_key_in process_definition_version_tag
+            process_variables without_tenant_id? tenant_id_in include_extension_properties?
+          ].freeze
+        end
+      end
+    end
+  end
+end

data/lib/operaton/bpm/client/topic/topic_subscription_builder.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Operaton
+  module Bpm
+    module Client
+      module Topic
+        # Mirrors org.operaton.bpm.client.topic.TopicSubscriptionBuilder.
+        # Documents the fluent contract implemented by
+        # Topic::Impl::TopicSubscriptionBuilderImpl.
+        module TopicSubscriptionBuilder
+          INTERFACE_METHODS = %i[
+            lock_duration handler variables local_variables business_key
+            process_definition_id process_definition_id_in process_definition_key
+            process_definition_key_in process_definition_version_tag
+            process_variables_equals_in process_variable_equals without_tenant_id
+            tenant_id_in include_extension_properties open
+          ].freeze
+        end
+      end
+    end
+  end
+end

data/lib/operaton/bpm/client/url_resolver.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Operaton
+  module Bpm
+    module Client
+      # Mirrors org.operaton.bpm.client.UrlResolver. Any object responding to
+      # #base_url can act as a URL resolver.
+      module UrlResolver
+        def base_url
+          raise NotImplementedError, "#{self.class} must implement #base_url"
+        end
+      end
+    end
+  end
+end

data/lib/operaton/bpm/client/variable/client_values.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "../../engine/variable/variables"
+require_relative "impl/type/json_type_impl"
+require_relative "impl/type/xml_type_impl"
+
+module Operaton
+  module Bpm
+    module Client
+      module Variable
+        # Mirrors org.operaton.bpm.client.variable.ClientValues, which extends
+        # the engine Variables factory with json and xml typed values.
+        module ClientValues
+          extend Engine::Variable::VariablesFactory
+
+          JSON = Impl::Type::JsonTypeImpl.new
+          XML = Impl::Type::XmlTypeImpl.new
+
+          def self.json_value(json_value, is_transient = false)
+            Impl::Value::JsonValueImpl.new(json_value, is_transient)
+          end
+
+          def self.xml_value(xml_value, is_transient = false)
+            Impl::Value::XmlValueImpl.new(xml_value, is_transient)
+          end
+        end
+      end
+    end
+  end
+end
+
+require_relative "impl/value/json_value_impl"
+require_relative "impl/value/xml_value_impl"

data/lib/operaton/bpm/client/variable/impl/abstract_typed_value_mapper.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "value_mapper"
+
+module Operaton
+  module Bpm
+    module Client
+      module Variable
+        module Impl
+          # Mirrors org.operaton.bpm.client.variable.impl.AbstractTypedValueMapper
+          class AbstractTypedValueMapper
+            include ValueMapper
+
+            attr_reader :value_type
+
+            def initialize(value_type)
+              @value_type = value_type
+            end
+
+            def type
+              value_type
+            end
+
+            def serialization_dataformat
+              nil
+            end
+
+            def can_handle_typed_value(typed_value)
+              type = typed_value.type
+              (type.nil? || type_matches?(type)) && can_write_value(typed_value)
+            end
+
+            def can_handle_typed_value_field(typed_value_field)
+              type = typed_value_field.type
+              !type.nil? && type == value_type.name && can_read_value(typed_value_field)
+            end
+
+            protected
+
+            # In Java this is valueType.getClass().isAssignableFrom(type.getClass()),
+            # where every value type has its own class. Ruby value types are
+            # singleton instances, so identity comparison is the equivalent.
+            def type_matches?(type)
+              type.equal?(value_type)
+            end
+
+            def can_write_value(typed_value)
+              raise NotImplementedError
+            end
+
+            def can_read_value(typed_value_field)
+              raise NotImplementedError
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/operaton/bpm/client/variable/impl/default_value_mappers.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "value_mappers"
+require_relative "../../impl/external_task_client_logger"
+
+module Operaton
+  module Bpm
+    module Client
+      module Variable
+        module Impl
+          # Mirrors org.operaton.bpm.client.variable.impl.DefaultValueMappers
+          class DefaultValueMappers
+            include ValueMappers
+
+            def initialize(default_serialization_format)
+              @serializer_list = []
+              @default_serialization_format = default_serialization_format
+            end
+
+            def find_mapper_for_typed_value(typed_value)
+              type = typed_value.type
+              raise logger.value_mapper_exception_while_serializing_abstract_value(type.name) if type&.abstract?
+
+              matched_serializers = []
+              @serializer_list.each do |serializer|
+                next unless serializer.can_handle_typed_value(typed_value)
+
+                matched_serializers << serializer
+                break if serializer.type.primitive_value_type?
+              end
+
+              case matched_serializers.size
+              when 1
+                matched_serializers.first
+              when 0
+                raise logger.value_mapper_exception_due_to_serializer_not_found_for_typed_value(typed_value)
+              else
+                # ambiguous match, use default serializer
+                matched_serializers.find { |s| s.serialization_dataformat == @default_serialization_format } ||
+                  matched_serializers.first
+              end
+            end
+
+            def find_mapper_for_typed_value_field(typed_value_field)
+              matched_serializer = @serializer_list.find { |s| s.can_handle_typed_value_field(typed_value_field) }
+
+              if matched_serializer.nil?
+                raise logger.value_mapper_exception_due_to_serializer_not_found_for_typed_value_field(
+                  typed_value_field.value
+                )
+              end
+
+              matched_serializer
+            end
+
+            def add_mapper(serializer)
+              @serializer_list << serializer
+              self
+            end
+
+            protected
+
+            def logger
+              Client::Impl::ExternalTaskClientLogger.client_logger
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/operaton/bpm/client/variable/impl/format/json/json_data_format.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../../../../spi/data_format"
+require_relative "../../../../exceptions"
+
+module Operaton
+  module Bpm
+    module Client
+      module Variable
+        module Impl
+          module Format
+            module Json
+              # Stands in for org.operaton.bpm.client.variable.impl.format.json
+              # .JacksonJsonDataFormat, using Ruby's JSON library.
+              class JsonDataFormat
+                include Spi::DataFormat
+
+                NAME = "application/json"
+
+                def name
+                  NAME
+                end
+
+                def can_map(value)
+                  json_native?(value) || value.respond_to?(:as_json) || value.respond_to?(:to_h)
+                end
+
+                def write_value(value)
+                  JSON.generate(jsonify(value))
+                end
+
+                # type_identifier is the stored objectTypeName; JSON deserialization
+                # in Ruby is generic (hashes/arrays), so it is not used for
+                # reconstruction the way Jackson uses Java type names.
+                def read_value(value, _type_identifier = nil)
+                  JSON.parse(value)
+                rescue JSON::ParserError => e
+                  raise DataFormatException.new("Unable to parse JSON value", e)
+                end
+
+                def canonical_type_name(value)
+                  value.class.name
+                end
+
+                protected
+
+                def jsonify(value)
+                  case value
+                  when Hash
+                    value.transform_values { |v| jsonify(v) }
+                  when Array
+                    value.map { |v| jsonify(v) }
+                  when String, Numeric, TrueClass, FalseClass, NilClass
+                    value
+                  else
+                    if value.respond_to?(:as_json)
+                      value.as_json
+                    elsif value.respond_to?(:to_h)
+                      jsonify(value.to_h)
+                    else
+                      value
+                    end
+                  end
+                end
+
+                def json_native?(value)
+                  case value
+                  when Hash, Array, String, Numeric, TrueClass, FalseClass, NilClass
+                    true
+                  else
+                    false
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/operaton/bpm/client/variable/impl/format/json/json_data_format_provider.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "../../../../spi/data_format_provider"
+require_relative "json_data_format"
+
+module Operaton
+  module Bpm
+    module Client
+      module Variable
+        module Impl
+          module Format
+            module Json
+              # Stands in for JacksonJsonDataFormatProvider; registered with the
+              # provider registry when the gem is loaded.
+              class JsonDataFormatProvider
+                include Spi::DataFormatProvider
+
+                def data_format_name
+                  JsonDataFormat::NAME
+                end
+
+                def create_instance
+                  JsonDataFormat.new
+                end
+              end
+
+              Spi::DataFormatProvider.register(JsonDataFormatProvider.new)
+            end
+          end
+        end
+      end
+    end
+  end
+end