From 01de207814eb59009a318fc6a0afe057434b6908 Mon Sep 17 00:00:00 2001
From: Ian Young <ian@iay.org.uk>
Date: Sat, 11 Aug 2012 15:10:40 +0000
Subject: [PATCH] More internal documentation in the generate pipeline.
 Refactor merge stages by adding a parent which defaults to deduplication. Add
 a merge stage for production MDX relationships (none at present).

---
 mdx/common-beans.xml | 15 +++++++++
 mdx/uk/generate.xml  | 77 ++++++++++++++++++++++++++++++++++++++------
 2 files changed, 83 insertions(+), 9 deletions(-)

diff --git a/mdx/common-beans.xml b/mdx/common-beans.xml
index 7f84e74e..af8381c9 100644
--- a/mdx/common-beans.xml
+++ b/mdx/common-beans.xml
@@ -128,6 +128,16 @@
         <property name="serializer" ref="serializer"/>
     </bean>
     
+    <!--
+        merge_parent
+        
+        Parent for merge stages.  Defaults strategy to deduplication.
+    -->
+    <bean id="merge_parent" abstract="true" parent="stage_parent"
+        class="net.shibboleth.metadata.pipeline.PipelineMergeStage">
+        <property name="collectionMergeStrategy" ref="deduplicateMergeStrategy"/>
+    </bean>
+    
     <!--
         ***********************************************
         ***                                         ***
@@ -595,4 +605,9 @@
     -->
     <bean id="serializer" class="net.shibboleth.metadata.dom.DomElementSerializer"/>
     
+    <!--
+        Merge strategy that removes duplicates.
+    -->
+    <bean id="deduplicateMergeStrategy" class="net.shibboleth.metadata.DeduplicatingItemIdMergeStrategy"/>
+    
 </beans>
diff --git a/mdx/uk/generate.xml b/mdx/uk/generate.xml
index ef475151..145657e1 100644
--- a/mdx/uk/generate.xml
+++ b/mdx/uk/generate.xml
@@ -381,6 +381,17 @@
                 -->
                 <ref bean="uk_stripAdminContacts"/>
                 
+                <!--
+                    ***********************************************
+                    ***                                         ***
+                    ***   R E G I S T R A R   E N T I T I E S   ***
+                    ***                                         ***
+                    ***********************************************
+                    
+                    At this point, the collection contains only
+                    entities registered by the UK federation registrar.
+                -->
+                
                 <!--
                     Fork into new pipelines for the export aggregate and for
                     the registrar statistics.
@@ -426,12 +437,44 @@
                 -->
                 <ref bean="uk_performFixups"/>
                 
+                <!--
+                    ***************************************************
+                    ***                                             ***
+                    ***   P R O D U C T I O N   M D X   M E R G E   ***
+                    ***                                             ***
+                    ***************************************************
+                    
+                    Merge in entities from production metadata exchange sources.
+                -->
+                
+                <bean id="mergeProductionMDXEntities" parent="merge_parent"
+                    p:id="mergeProductionMDXortedEntities">
+                    <property name="mergedPipelines">
+                        <list>
+                            <!-- entries earlier in the list have higher precedence -->
+                        </list>
+                    </property>
+                </bean>
+                
+                <!--
+                    *************************************************
+                    ***                                           ***
+                    ***   P R O D U C T I O N   E N T I T I E S   ***
+                    ***                                           ***
+                    *************************************************
+                    
+                    At this point, the collection contains entities
+                    registered by the UK federation registrar plus
+                    entities received through production-status MDX
+                    relationships.
+                -->
+
                 <!--
                     Fork into new pipelines for the production, fallback and WAYF aggregates.
                 -->
-                <bean id="otherDemux" parent="stage_parent"
+                <bean id="productionDemux" parent="stage_parent"
                     class="net.shibboleth.metadata.pipeline.PipelineDemultiplexerStage"
-                    p:id="otherDemux">
+                    p:id="productionDemux">
                     <property name="pipelineAndSelectionStrategies">
                         <list>
                             <bean class="net.shibboleth.utilities.java.support.collection.Pair">
@@ -457,22 +500,38 @@
                 <ref bean="uk_default_regauth"/>
                 
                 <!--
+                    ***********************************************************
+                    ***                                                     ***
+                    ***   P R E - P R O D U C T I O N   M D X   M E R G E   ***
+                    ***                                                     ***
+                    ***********************************************************
+                    
                     Merge in entities from pre-production metadata exchange sources.
                 -->
-                <bean id="mergePreproductionImportedEntities" parent="stage_parent"
-                    class="net.shibboleth.metadata.pipeline.PipelineMergeStage"
-                    p:id="mergePreproductionImportedEntities">
-                    <property name="collectionMergeStrategy">
-                        <bean id="deduplicateMergeStrategy" class="net.shibboleth.metadata.DeduplicatingItemIdMergeStrategy"
-                            lazy-init="true"/>
-                    </property>
+
+                <bean id="mergePreproductionMDXEntities" parent="merge_parent"
+                    p:id="mergePreproductionMDXEntities">
                     <property name="mergedPipelines">
                         <list>
+                            <!-- entries earlier in the list have higher precedence -->
                             <ref bean="uk_ie_edugate_importPipeline"/>
                         </list>
                     </property>
                 </bean>
                 
+                <!--
+                    *********************************************************
+                    ***                                                   ***
+                    ***   P R E - P R O D U C T I O N   E N T I T I E S   ***
+                    ***                                                   ***
+                    *********************************************************
+                    
+                    At this point, the collection contains entities
+                    registered by the UK federation registrar plus
+                    entities received through both production-status
+                    and pre-production-status MDX relationships.
+                -->
+                
                 <!-- pipeline continues to generate test aggregate -->
                 <ref bean="uk_assembleHierarchicalAggregate"/>
                 <ref bean="uk_addTrustRoots"/>