lib/ruote/fei.rb in ruote-2.1.6 vs lib/ruote/fei.rb in ruote-2.1.7

@@ -1,7 +1,7 @@
 #--
-# Copyright (c) 2009, John Mettraux, [e-mail]
+# Copyright (c) 2005-2010, John Mettraux, [e-mail]
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
 # in the Software without restriction, including without limitation the rights
 # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
@@ -37,12 +37,25 @@
 
     Ruote::FlowExpressionId.to_storage_id(fei)
   end
 
   #
-  # TODO : document me
+  # The FlowExpressionId (fei for short) is an process expression identifier.
+  # Each expression when instantiated gets a unique fei.
   #
+  # Feis are also used in workitems, where the fei is the fei of the
+  # [participant] expression that emitted the workitem.
+  #
+  # Feis can thus indicate the position of a workitem in a process tree.
+  #
+  # Feis contain four pieces of information :
+  #
+  # * wfid : workflow instance id, the identifier for the process instance
+  # * sub_wfid : the identifier for the sub process within the main instance
+  # * expid : the expression id, where in the process tree
+  # * engine_id : only relevant in multi engine scenarii (defaults to 'engine')
+  #
   class FlowExpressionId
 
     CHILD_SEP = '_'
 
     attr_reader :h
@@ -64,16 +77,14 @@
     def sub_wfid
       @h['sub_wfid']
     end
 
     def to_storage_id
-
       "#{@h['expid']}!#{@h['sub_wfid']}!#{@h['wfid']}"
     end
 
     def self.to_storage_id (hfei)
-
       "#{hfei['expid']}!#{hfei['sub_wfid']}!#{hfei['wfid']}"
     end
 
     def self.from_id (s, engine_id='engine')
 
@@ -86,16 +97,14 @@
 
     # Returns the last number in the expid. For instance, if the expid is
     # '0_5_7', the child_id will be '7'.
     #
     def child_id
-
       h.expid.split(CHILD_SEP).last.to_i
     end
 
     def hash
-
       to_storage_id.hash
     end
 
     def == (other)
 
@@ -115,10 +124,9 @@
     end
 
     # Returns child_id... For an expid of '0_1_4', this will be 4.
     #
     def self.child_id (h)
-
       h['expid'].split(CHILD_SEP).last.to_i
     end
 
     def to_h
       @h