#
#--
# Copyright (c) 2007, John Mettraux, OpenWFE.org
# All rights reserved.
# 
# Redistribution and use in source and binary forms, with or without 
# modification, are permitted provided that the following conditions are met:
# 
# . Redistributions of source code must retain the above copyright notice, this
#   list of conditions and the following disclaimer.  
# 
# . Redistributions in binary form must reproduce the above copyright notice, 
#   this list of conditions and the following disclaimer in the documentation 
#   and/or other materials provided with the distribution.
# 
# . Neither the name of the "OpenWFE" nor the names of its contributors may be
#   used to endorse or promote products derived from this software without
#   specific prior written permission.
# 
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
# POSSIBILITY OF SUCH DAMAGE.
#++
#
#

#
# "made in Japan"
#
# Alain Hoang at openwfe.org
#

require 'openwfe/participants/participant'


module OpenWFE

    #
    # A mixin gathering the methods a workitem store participant needs.
    #
    # Two kinds of methods are involved here, the ones used by the engine
    # (its participant map) and the ones used by 'workflow clients'.
    # Thus consume() and cancel() are triggered by the engine, and
    # save() and forward() are at the disposal of 'workflow clients'.
    #
    # A 'workflow client' is supposed to use methods similar to hash methods
    # to retrieve workitems, like in
    #
    #     storeparticipant.each do |fei, workitem|
    #         puts "workitem : #{fei.to_s}"
    #         do_some_work(workitem)
    #     end
    #
    #
    module StoreParticipantMixin
        include LocalParticipant

        #def initialize ()
        #end

        #
        # Called by the engine (the participant expression) when handing
        # out a workitem (to this participant).
        #
        def consume (workitem)

            self[workitem.flow_expression_id] = workitem
        end

        #
        # Called by the participant expression when this participant is
        # 'cancelled' within a flow. The workitem then gets removed.
        #
        def cancel (cancelitem)

            ldebug do 
                "cancel() removing workitem  #{cancelitem.flow_expression_id}"
            end

            self.delete(cancelitem.flow_expression_id)
        end

        #
        # The workitem is to be stored again within the store participant,
        # it will probably be reused later. Don't send back to engine yet.
        #
        def save (workitem)

            raise "Workitem not found in #{self.class}, cannot save." \
                unless self.has_key? workitem.flow_expression_id

            self[workitem.flow_expression_id] = workitem
        end

        #
        # The workflow client is done with the workitem, send it back to
        # the engine and make sure it's not in the store participant anymore.
        #
        def forward (workitem)

            raise "Workitem not found in #{self.class}, cannot forward." \
                unless self.has_key? workitem.flow_expression_id

            self.delete(workitem.flow_expression_id)
            reply_to_engine(workitem)
        end

        #
        # 'proceed' is just an alias for 'forward'
        #
        alias :proceed :forward

        #
        # Returns all the workitems for a given workflow isntance id.
        #
        def list_workitems (workflow_instance_id)

            result = []
            self.each_value do |workitem|
                result << workitem \
                    if workitem.fei.parent_wfid == workflow_instance_id
            end

            result
        end
    end

    #
    # The simplest workitem store possible, gathers the workitem in a 
    # hash (this class is an extension of Hash).
    #
    class HashParticipant < Hash
        include StoreParticipantMixin

        # that's all...
    end
end